AI Integrations (Opt-in)

export DOTFILES_AI=1
exec zsh

In zsh it sources the opt-in AI shell helpers (context suggestions and error analysis), and during chezmoi apply it lets the cockpit binary (dot-ai-tui) be built. zsh and bash leave it off by default; the Fish, Nushell and PowerShell configs export DOTFILES_AI=1. It does not install any AI tools or run any background service.

Why dot ai?

claude is one tool. dot ai is the cockpit for every AI CLI you use. Use it to install the tools, launch any of them with one keystroke, meter their cost in one place, and — the headline — run every one of them on your single Claude subscription through a built-in local gateway.

You use claude to talk to Claude. You use dot ai to run everything else on Claude and keep one cockpit over all of it.

Quick start

dot ai install all        # install the roster (only what's missing)
dot ai                    # open the cockpit (TUI)
dot ai "fix the auth bug" # one-shot on Claude — just like `claude "…"`
dot ai gateway serve      # serve your Claude subscription locally to every tool

Prerequisites

Most tools install through mise; claude, goose, agy, amp, cursor-agent, grok and kimi use their own pinned native installers, which need curl. When a tool you install needs mise and it is missing, dot ai offers to install it first. Nothing installs without your yes: dot ai install asks before a bulk install, dot ai <tool> asks before installing a missing tool, and --yes (or DOTFILES_YES=1) answers yes. With no terminal to ask, nothing installs. dot ai check lists what is missing (mise, node, uv, curl, go) and how to add it.

Command surface

The interface follows ADR-020 (dot ai <verb>), modelled on the Claude CLI: bare opens an interactive view and a prompt runs it. The older verbs in brackets still work.

The cockpit (dot ai)

Running dot ai on a terminal opens a glamorous, chat-centric TUI (built with Bubble Tea, Charm/Crush-style):

• Header — the ◆ dot ai wordmark plus gateway status (● :3456 / ○ off) and today's cost as colour chips.
• Left — the roster grouped by role, with ●/○ install markers and a ▌ selection accent.
• Right — a chat panel: pick a tool, type a prompt in the input box, press Enter, and the response streams back in the transcript — all without leaving the TUI.

Tab focus   ↑↓ move   ⏎ send   s serve   i install   c refresh   q quit

Two modes per tool: Enter on the roster opens the tool's full native session (where its own /exit, /model, /clear, … work); Tab / / drops into the quick in-cockpit streaming chat. In the chat input, typing / opens a tool-aware command palette — the cockpit commands (/help /clear /style /tool /serve /cost /exit, which run in-chat) plus the selected provider's common REPL commands (/compact /model /resume /agents for claude; /add /diff /commit for aider; /approvals /status for codex; …), tagged → <tool> session. Navigate with ↑↓, Tab to complete, Enter to run. Prompts run through dot ai <tool>, so the cockpit and the command line behave identically.

The cockpit also offers a model picker (/model <name> or the m key cycles default → opus → sonnet → haiku; the active model shows in the header and is applied to the Claude engine via ANTHROPIC_MODEL), session persistence (each completed turn is saved to $XDG_STATE_HOME/dot-ai-tui/session.json; /resume restores your last conversation, /save snapshots the current one), and desktop notifications when a reply takes longer than ~8s (macOS osascript / Linux notify-send). In non-interactive contexts (CI, pipes) dot ai falls back to a plain text roster listing. The cockpit binary (dot-ai-tui) is built on chezmoi apply via the mise-managed Go toolchain; DOT_AI_SNAPSHOT=1 dot-ai-tui prints a single frame for previews.

Steering styles

Styles in ~/.config/ai/patterns/ (source: defaults/dot_config/ai/patterns/) add focused context to any prompt with --style <name>:

• architect — shell setup and stack tuning
• hardener — security, encryption, and compliance
• refactor — POSIX compatibility, performance, and linting

dot ai run claude --style architect "optimize my zshrc"
dot ai run agy --style hardener "audit my ssh config"

The bridge also injects system details (OS, architecture, date) so the model has the context it needs. Quick aliases ship for the common combinations: dcla (Claude + architect), dagyh (Antigravity + hardener), dkir (Kiro + refactor).

Running tools

dot ai "explain this stack trace"            # one-shot on Claude
dot ai run codex "add a test for parse()"    # one-shot on a specific tool
dot ai start                           # pick a tool and open its session
dot ai start aider                     # open aider directly

The local Claude gateway (dot ai gateway serve)

Run one Claude subscription locally and point every tool at it — with no third-party dependency. dot-ai-serve is a small, stdlib-only Python server (no pip packages) that wraps the claude CLI you already have and exposes the standard Anthropic (/v1/messages) and OpenAI (/v1/chat/completions) endpoints. Any tool that speaks either protocol — codex, aider, Open WebUI, an OpenAI SDK — connects to http://127.0.0.1:3456 and gets Claude on your existing subscription.

claude login              # one-time: authenticate the engine
dot ai gateway serve          # start the gateway AND route the non-Claude tools
dot ai gateway serve status   # process + /health + routing state
dot ai gateway serve stop     # stop the gateway and un-route

Native session, never a key. The gateway authenticates through your claude CLI's native session — there is no API key anywhere. Routing is applied per-invocation to non-Claude tools (dot ai codex "…"); it is not sourced into your interactive shell. The primary claude is never routed — it always uses its own native session, so claude.ai connectors stay enabled. (Setting ANTHROPIC_API_KEY in your shell would disable those connectors, which is exactly why routing stays scoped to each tool's subprocess.)

Streaming, routing & metering. Replies stream token-by-token (real SSE for both protocols). Model aliases/routing map friendly names to a Claude tier — cheap/fast → haiku, smart → opus, and common OpenAI ids (gpt-4 → sonnet, gpt-3.5-turbo → haiku); extend with DOT_AI_MODEL_MAP. Every request is metered: GET /metrics (Prometheus text) and GET /v1/usage (JSON) report requests, tokens, and estimated cost per model. An optional DOT_AI_DAILY_BUDGET (USD) caps daily spend — once reached, requests get 429.

Config: DOT_AI_HOST (default 127.0.0.1), DOT_AI_PORT (default 3456), DOT_AI_DEFAULT_MODEL (default sonnet), DOT_AI_API_KEY (shared secret; defaults to a generated token), DOT_AI_ALLOWED_HOSTS (extra accepted Host values), DOT_AI_DAILY_BUDGET (USD, 0 = off), DOT_AI_MODEL_MAP / DOT_AI_PRICING (JSON overrides).

Security: the server binds to loopback by default. If you set DOT_AI_HOST to a LAN address, both the launcher and the server itself refuse to start unless DOT_AI_API_KEY is set — an unprotected network proxy leaks your subscription. Every request needs a key: without DOT_AI_API_KEY the server and dot ai proxy local on share a random 0600 token at $XDG_STATE_HOME/dot/ai/serve/gateway.token (dot-ai-serve --token-path prints its location). Requests whose Host header is not the server's own address are refused (DNS-rebinding guard), and the claude engine runs with all tools disabled in an empty temporary directory.

Engine limits. The gateway wraps the claude CLI (an agent), not the raw API, so two things are handled gracefully rather than forwarded: image blocks are acknowledged inline but not sent (the engine is text-only), and function/tool-calling requests are answered in plain text (the CLI can't return caller-defined tool_use blocks). Session resumption is still out of scope.

The roster

These tools are not installed for you. Install what you want with dot ai install <tool> (or dot ai install all):

• Agents (autonomous) — full coding agents that plan and execute:

  • claude — Anthropic's flagship agentic coder (Claude Code)
  • codex — OpenAI's autonomous coding agent
  • copilot — GitHub Copilot in the terminal
  • goose — Block's open-source coding agent
  • crush — Charm's glamorous TUI coding agent
  • amp — Sourcegraph's agentic coder
  • cursor-agent — Cursor's terminal agent
  • grok — xAI's terminal coding agent (Grok Build; needs a SuperGrok / X Premium+ plan)
  • kimi — Moonshot AI's Kimi Code CLI; installed natively to ~/.kimi-code/bin/kimi and supports native interactive use and one-shot prompts

• Coding (interactive) — focused pair-programming assistants:

  • aider — Git-aware AI pair programmer
  • opencode — open-source terminal coding agent
  • autohand — autonomous multi-file coding agent
  • vibe — Mistral's coding agent
  • qwen — Alibaba Qwen coding assistant
  • zai — Zhipu GLM coding agent

• General (prompt-based) — quick prompt/shell helpers:

  • agy — Google's Antigravity agent
  • sgpt — ChatGPT for the shell (Shell-GPT)

• Runtime (local):

  • ollama — run local and cloud-hosted open models (ollama signin for cloud)

• Cloud (platform):

  • kiro-cli — AWS's agentic dev assistant

dot ai list shows install status grouped by role and offers an interactive install picker. Status is cached in ~/.cache/dotfiles/ai/status.tsv for 5 minutes (tune with DOTFILES_AI_STATUS_TTL).

Run cost and telemetry

Every run through the bridge is logged to a local SQLite database (~/.local/share/dotfiles-ai.db). dot ai cost show reports spend across providers, and the cockpit's cost panel and recent-runs list read from the same log. Token-level cost is populated for providers that surface it (and for everything routed through dot ai gateway serve).

Old command names

The top-level provider shortcuts were removed in 0.2.538: each now exits 127 and prints its new name.

These verbs inside dot ai still work but print a one-line hint with the new name. The shortcut aliases (dagy, dkm, dcla, dkia, …) run dot ai <tool>; dcl and dki are the Docker aliases (docker compose logs, docker info).

Agentic terminal workflows

If your terminal has built-in AI agents, keep your shell lean and fast:

• Use DOTFILES_FAST=1 or DOTFILES_ULTRA_FAST=1.
• Let the terminal handle agents and its own UI.
• Keep dotfiles focused on consistency, safety, and clean repeats.

Privacy and safety

• No AI tools are installed for you.
• No background services run by default; the gateway runs only while you keep dot ai gateway serve up.
• You control AI helpers with DOTFILES_AI=1.
• The gateway uses your native Claude session — no API keys are stored or required.