autopilot (formerly kimiflare)
The open-source coding agent inside dl. It doesn't ask permission.
Free GPT-6 and DeepSeek tokens every week with a GitHub sign-in, no credit card. Or bring your own key: OpenRouter, Anthropic, OpenAI and 25+ more.
## Get it
```sh
curl -fsSL https://dl.new | sh
```
That installs **dl** ([Directionally Local](https://directionallylocal.com)'s installer), which installs and runs Autopilot. Under dl, Autopilot shows dl's name and version (`dl 0.30.1`, "Ask dl anything") and `dl --version` names both. dl keeps Autopilot on a version it has tested and updates them together, so use dl's update command, not npm, to update.
Autopilot on its own, without dl: `npm i -g autopilot-ai` and run `autopilot`.
Part of Directionally Local, an open-source stack for running coding agents on your own hardware, alongside Hotcell and Serverless Objects. Product page: directionallylocal.com/autopilot. Get it at dl.new.
## How it works
On the free tier, model calls go through Directionally Local's free tier service to its model host; it keeps usage counts, never prompts or code. With **your own key**, autopilot sends every model call straight to **the provider you choose** — nothing proxied, nothing marked up. On first run you pick a provider, connect it once (the key is checked before it's saved) and pick a model. That's the whole setup. [OpenRouter](https://openrouter.ai) is the recommended default; see [Providers](#providers) for the rest.
On OpenRouter you also get:
- **Any model, one key.** The model picker is OpenRouter's live catalog — Claude, GPT, Gemini, Grok, Qwen, GLM, Kimi, DeepSeek, free models and more — opening on the best & latest by benchmark score, with fuzzy search over everything. Switch any time with `/model`.
- **Real cost, per turn.** OpenRouter reports what each generation actually cost; the status bar shows it (a local estimate marked `≈$` only until the billed number arrives). `/cost` totals it by session, day, month and all time.
- **Reliable tool calling.** Requests only go to upstream providers that support every parameter autopilot sends (tools above all), and OpenRouter routes tool-calling traffic to the providers with the best tool-call success rates. The status bar shows which provider served the last turn.
- **Prompt caching that stays warm.** Each session pins to one upstream provider (OpenRouter sticky routing), so the long, stable prompt prefix keeps hitting the provider's cache across turns.
## What to remember
- **Up to 1M+ context** (model-dependent) — Read entire modules, large configs, and full stack traces without the model losing track.
- **Image understanding** — Drop image paths (PNG, JPG, WebP, GIF, BMP up to 5 MB) into any prompt. Great for UI reviews, diagrams, and screenshots.
- **Plan / Edit / Auto modes (opt-in)** — Modes are off by default: every interactive turn runs in `auto` until you turn them on with `/settings modes on` (`/settings modes off` turns them off again). With modes on, the session starts in `edit` and `Shift+Tab` or `/mode` switches between them. SDK sessions always have modes and start in `edit`. `plan` is a whitelist-only research mode: only read-only tools (read, glob, grep, web search, GitHub read-only, browser fetch) are allowed. Writes, edits, mutating bash, MCP tools, and LSP renames are all blocked. `edit` prompts per mutating call. `auto` approves everything for trusted tasks. In `plan` and `edit`, reading a credentials file (`~/.ssh`, `~/.aws`, Autopilot's own config with your provider keys, `.env`, `/proc/*/environ`) also asks first (print mode denies it unless a rule names the exact path), so a prompt injection cannot quietly read a key and send it out with `web_fetch`. Likewise `web_fetch` and `browser_fetch` ask before reaching a local or private network address (localhost, `127.0.0.1`, `10.x`/`192.168.x`, cloud metadata at `169.254.169.254`, including names and redirects that resolve there), approved per origin, so a prompt injection cannot read metadata credentials or local services.
- **Guardrails and `/undo`** — Irreversible actions always ask, even in `auto`, under `--dangerously-allow-all`, or under a broad allow rule: deleting untracked work, `git reset --hard`, force pushes, dropping a database. A production-looking target needs its name typed, not just Enter. Before a destructive file or git action Autopilot saves a recovery point outside the repo, and `/undo` restores the latest one. `/audit` reports what the agent could destroy from here and what would save you.
- **Setup import from other coding agents** — Autopilot finds your `CLAUDE.md`, `GEMINI.md`, Cursor rules, Copilot instructions, Claude Code commands and MCP servers and uses them in place, quietly; `/setup-import` shows the checklist. Nothing is copied into the repo or sent anywhere.
- **Subagents** — By default, the coordinator assesses substantial tasks for independent research and may delegate without special phrasing. Worker calls still go through permission checks and need a configured backend. See the [subagents guide](docs/subagents.md) for examples, controls, limits, and setup.
- **Long-running unattended runs** — The headless server can launch detached jobs, sleep between check-ins, and resume from saved checkpoints. Overall runtime, token, cost, and action budgets are optional; explicit budget exhaustion pauses for input. See the [long-running runs guide](docs/long-running-unattended-runs.md).
- **Windows support** — OS-aware shell auto-detects `cmd.exe` / PowerShell on Windows, `bash` on Unix. The `bash` tool works out of the box on all platforms.
- **Message queuing** — Submit multiple messages while the agent is busy; they queue and auto-drain. Escape interrupts the current turn but preserves the queue.
- **Smart permission modal** — Denying a tool opens inline feedback so you can tell the agent what to do instead. Keyboard-native navigation (`↑/↓`, `j/k`, `Alt+1/2/3`).
- **Loop guardrails** — Agent hard-stops when all tools in a turn are blocked, preventing infinite token-burning cycles.
- **Persistent all-time cost history** — Append-only `history.jsonl` tracks daily usage forever, so `/cost` shows true all-time and monthly totals that survive across sessions and version updates.
- **LSP + MCP** — Semantic code intelligence (hover, go-to-definition, references, diagnostics) via Language Server Protocol. Extend with external tools via Model Context Protocol.
- **Local structured memory** — SQLite + embeddings cross-session memory. The agent recalls facts, instructions, and preferences across sessions via `remember`, `recall`, and `forget` tools.
- **Web search, GitHub, and headless browser** — Research the web, read GitHub repos, and fetch JavaScript-rendered pages without leaving your terminal.
## Recently shipped
- **OpenRouter as the model provider** — Every OpenRouter model, your own key, billed cost per turn. Replaces Cloudflare Workers AI / AI Gateway (see [Upgrading from Cloudflare](#upgrading-from-the-cloudflare-version)).
- **OS-aware shell with Windows support** — Auto-detects `cmd.exe`, PowerShell, or bash based on platform. Override with `AUTOPILOT_SHELL` or `/shell`.
- **Smart permission modal with inline feedback** — Deny a tool and immediately tell the agent what to do instead. Keyboard-native navigation with `↑/↓`, `j/k`, `Alt+1/2/3`.
- **True message queuing** — Enter queues messages while the agent is busy; Escape interrupts and auto-drains the queue.
- **Hard-stop loop guardrail** — Stops token-burning cycles when all tools in a turn are blocked.
- **Headless SDK** — Programmatic `createAgentSession` API and JSONL-over-stdio RPC mode for building on top of autopilot.
See the full changelog at [github.com/directionally-local/autopilot/releases](https://github.com/directionally-local/autopilot/releases).
## Quick start
```sh
npm install -g autopilot-ai
autopilot
```
On first run, autopilot asks **"How should it think?"**: choose **Free — sign in with GitHub** (no credit card), **Use my own API key** to pick a provider such as OpenRouter and then a model, or **Use your own GPUs** (see [Your own GPUs](#your-own-gpus)). A provider key already in your environment skips the question and is used as-is. That's it.
The free tier gives free tokens every week. When they run out, `/upgrade` offers dl Pro or a one-time top-up, and you can always switch to your own key or your own GPUs.
### Troubleshooting: the screen fails to start or keeps crashing
The full screen view runs in the Camouflage renderer. If the renderer crashes, autopilot reopens the conversation in a fresh one. If it crashes 3 times within a minute, or exits before it drew anything, autopilot switches to the **simple view**: a plain prompt where each line you type is a turn, with the reply and tool calls printed as plain lines (Ctrl+C stops a turn, `/exit` quits). The conversation carries on and is saved after every turn. Actions that would need your approval are refused there, as in `-p` mode.
To start in the simple view yourself, run `autopilot --simple` (add `-c` or `-S ` to continue a conversation) or set `AUTOPILOT_SIMPLE_VIEW=1`. Under dl, use `AUTOPILOT_SIMPLE_VIEW=1 dl`. The simple view has no first-run setup, so connect a provider first (for example `autopilot auth openrouter`, or a key such as `OPENROUTER_API_KEY` in the environment).
Crash reports are saved as `~/.camouflage/crash-*.txt`, and autopilot prints the path. Please attach the report to an [issue](https://github.com/directionally-local/autopilot/issues).
### Your own GPUs
Before that question, the first run looks for GPUs on this machine. With an Nvidia card of 24 GB or more and Autopilot started by dl, it asks **"Run a private model on it?"**: yes hands over to `dl model up`, which sets up vLLM on the GPU, tests it and opens Autopilot on it; no is remembered. A smaller Nvidia card gets a one-line hint that `dl model up` can run small models on it. If the setup fails, a menu offers to retry, see what failed (the reason and the log file), pick another model, or carry on without a local model.
**Use your own GPUs** asks where they are:
- **On this machine**: hands over to `dl model up`, as above.
- **Another server of mine**: run `curl -fsSL https://dl.new | sh` and then `dl model up` on that server, then enter its address. `dl model up` serves on that server's `127.0.0.1`, so to reach it from here keep an SSH tunnel open (`ssh -N -L 8000:127.0.0.1:8000 you@that-server`) and enter `127.0.0.1` and port 8000.
- **I already run vLLM or another OpenAI-compatible server**: enter its URL and an optional key.
Either way Autopilot checks the server with `/v1/models`, you pick a model, and it is saved as the `vllm` provider. Your code and prompts stay on your hardware. What `dl model` does on the GPU is in [dl's README](https://github.com/directionally-local/installer#on-your-own-gpus).
Or install with Homebrew on macOS or Linux (Homebrew installs Node.js for you):
```sh
brew install directionally-local/tap/autopilot
autopilot
```
Or run without installing:
```sh
npx autopilot-ai
```
> **Coming from `kimiflare`?** The package was renamed. Run `npm uninstall -g kimiflare && npm install -g autopilot-ai` and use `autopilot` instead of `kimiflare`. Your settings, keys, sessions, memory, traces and cost history are kept: on first start Autopilot moves `~/.config/kimiflare` to `~/.config/autopilot`, `~/.local/share/kimiflare` and `~/.kimiflare` to `~/.local/share/autopilot`, and `~/.local/state/kimiflare` to `~/.local/state/autopilot` (honouring `XDG_*_HOME`), and leaves a symlink at each old path so an older `kimiflare` binary still finds the same files. A file that already exists in the new folder is never overwritten; it stays in the old folder and Autopilot names it once. Project `.kimiflare/` folders are not moved: Autopilot reads `.autopilot/` first, then `.kimiflare/`, and creates only `.autopilot/`. `KIMIFLARE_*` environment variables still work.
Requires Node.js 22.23.4+, 24.22.1+ or 26.12.1+ (earlier releases have the Brotli bug CVE-2026-111497, and `web_fetch` refuses to run on them).
If npm warns that it blocked `isolated-vm`'s install script, nothing is broken: `isolated-vm` is an optional dependency that ships prebuilt binaries for Node 22 and 24, and on a Node version without one Autopilot runs with Code Mode's sandbox off and tells you once per session how to build it.
To pick up an earlier conversation, run `autopilot resume ` (the exact command is printed when you exit), `autopilot resume` to choose one from this directory, or `autopilot -c` for the most recent one. Inside autopilot, `/resume` does the same.
To continue a Claude Code conversation (say it stopped on a usage limit), run `autopilot --from-claude-code` in the same folder. It finds that folder's most recent conversation in `~/.claude/projects`, asks first, and starts a new session whose first message is a short handoff: your last request, the files changed, commands run and last errors, and Claude's last message (at most 12,000 characters, likely keys redacted). The transcript is read on this machine and goes only to your model, as the session's first message.
### Providers
| Provider | id | Key | Notes |
|---|---|---|---|
| [OpenRouter](https://openrouter.ai) (default) | `openrouter` | `OPENROUTER_API_KEY` or browser sign-in | 400+ models, billed cost per turn, sticky routing, subagents, Jev checks |
| Anthropic | `anthropic` | `ANTHROPIC_API_KEY` | native Messages API: extended/adaptive thinking, explicit prompt caching (API keys only — Claude Pro/Max sign-in isn't permitted for third-party tools) |
| OpenAI | `openai` | `OPENAI_API_KEY` | Responses API: reasoning carries across tool loops (encrypted, stateless), codex models |
| Google Gemini | `gemini` | `GEMINI_API_KEY` / `GOOGLE_API_KEY` | OpenAI-compatible endpoint; Gemini 3 thought signatures are kept with each tool call |
| ChatGPT (Plus/Pro/Team plan) | `chatgpt` | `autopilot auth chatgpt` (browser sign-in with token sharing) | your plan's GPT models over the Responses API; tokens refresh automatically; usage counts against your plan. Uses OpenAI's official token-sharing sign-in, not the Codex backend |
| GitHub Copilot | `copilot` | `autopilot auth copilot` (GitHub device login; `--enterprise `) | your Copilot plan's models — Claude over Messages, GPT over Responses; usage counts as premium requests. Not a documented public API, so GitHub may change it |
| Google Vertex AI | `vertex` | Google credentials (`gcloud auth application-default login`, a service-account key in `GOOGLE_APPLICATION_CREDENTIALS`, or `GOOGLE_VERTEX_ACCESS_TOKEN`) + `GOOGLE_VERTEX_PROJECT` (or `autopilot auth vertex --project …`) | Gemini and partner models through Vertex's OpenAI-compatible endpoint, Claude through Anthropic's Messages API on Vertex; location `GOOGLE_VERTEX_LOCATION` (default `global`) |
| Amazon Bedrock | `bedrock` | `AWS_BEARER_TOKEN_BEDROCK` (Bedrock API key), or AWS credentials (env or `~/.aws/credentials` / `AWS_PROFILE`; for SSO, `eval "$(aws configure export-credentials --format env)"`); region `AWS_REGION` | Converse API with SigV4 signing; Claude thinking and prompt caching; inference-profile ids like `global.anthropic.claude-sonnet-5-5` |
| DeepSeek | `deepseek` | `DEEPSEEK_API_KEY` | |
| MiniMax | `minimax` | `MINIMAX_API_KEY` | OpenAI-compatible endpoint with split reasoning (`` tags are separated out if they appear) |
| Moonshot AI (Kimi) | `moonshot` | `MOONSHOT_API_KEY` | |
| Kimi Code (subscription) | `kimi-code` | `KIMI_API_KEY` | |
| Z.ai (GLM) | `zai` | `ZHIPU_API_KEY` | |
| Z.ai GLM Coding Plan | `zai-coding` | `ZHIPU_API_KEY` | |
| xAI | `xai` | `XAI_API_KEY` | Grok over the Responses API |
| Mistral | `mistral` | `MISTRAL_API_KEY` | tool-call ids adapted to Mistral's format; `mistral-embed` |
| Groq · Cerebras · Together AI · Fireworks AI · DeepInfra | `groq` · `cerebras` · `together` · `fireworks` · `deepinfra` | `GROQ_API_KEY` · `CEREBRAS_API_KEY` · `TOGETHER_API_KEY` · `FIREWORKS_API_KEY` · `DEEPINFRA_API_KEY` | fast / open-model hosts |
| Vercel AI Gateway | `vercel` | `AI_GATEWAY_API_KEY` | many vendors with one key |
| Cloudflare Workers AI | `cloudflare` | `CLOUDFLARE_API_TOKEN` + `CLOUDFLARE_ACCOUNT_ID` (or `autopilot auth cloudflare --account-id …`) | Cloudflare-era kimiflare configs reuse their credentials, and memory stays on `bge-base-en-v1.5`. For **AI Gateway**, use its OpenAI-compatible URL as a `custom` endpoint |
| Azure OpenAI | `azure` | `AZURE_API_KEY` + `AZURE_RESOURCE_NAME` (or `autopilot auth azure --resource `) | v1 API over Responses; model ids are your deployment names, discovered from the resource. Entra ID sign-in isn't supported yet — use a key |
| Ollama (local) | `ollama` | none | installed models are discovered; `providers.ollama.baseUrl` for another host |
| LM Studio (local) | `lmstudio` | none | |
| vLLM (local) | `vllm` | none | your own GPUs; `dl model up` sets it up on one Nvidia GPU, tests it and connects autopilot (see [Your own GPUs](#your-own-gpus)), or run `vllm serve` yourself with `--enable-auto-tool-choice --tool-call-parser ` for tool calls |
| Requesty | `requesty` | `REQUESTY_API_KEY` | |
| Any OpenAI-compatible endpoint | `custom` | `AUTOPILOT_API_KEY` (optional) | `AUTOPILOT_BASE_URL` — LiteLLM, vLLM, llama.cpp, a company gateway |
- **First run** asks "How should it think?" — Free (sign in with GitHub) or your own key, which opens the provider picker. A provider with a key already in your environment skips the question and is used without saving the key.
- **Switch any time** with `/provider [key]` (`/provider` lists them and where each key comes from), or from the CLI: `autopilot auth ` (saves a key and makes it active), `autopilot auth use `, `autopilot auth status`. For one run, set `AUTOPILOT_PROVIDER=`.
- **`autopilot connect`** runs the first-run screens on their own — the searchable provider list, key entry checked with the provider, then its live model list — and saves the choice, so a plain `autopilot` uses it. Installers and scripts can hand setup to it instead of asking for a key themselves: `--state-file ` writes the result (`provider`, `name`, `baseUrl`, `apiKey`, `apiKeyEnv`, `keyRequired`, `model`, `authHeader`, `authFormat`) as JSON readable by you only, and hides providers a plain key gateway cannot proxy (Copilot, ChatGPT, Vertex, Bedrock, Azure, Workers AI). `--model-only` keeps the active provider and only changes the model. Exits 0 when saved, 1 when cancelled, 2 on a usage error.
- **Everything follows the provider**: chat, compaction and memory side-calls, memory/skill embeddings, the model picker (each provider's own catalog — models.dev for hosted providers, live discovery for Ollama, LM Studio and vLLM), pricing, error messages and the status page link. Nothing is sent to OpenRouter while another provider is active.
- **OpenRouter-only features** switch off on other providers: billed-cost confirmation (elsewhere `/cost` shows estimates from the provider's published prices), Hotcell subagents, and the Jev completion/triage checks.
- **Embeddings**: providers without an embeddings API (Anthropic, DeepSeek, Moonshot, Kimi Code, the Coding Plan, LM Studio, vLLM) keep memory working through text and topic-key recall. To keep vector recall, set `"embeddingProvider": "openai"` (or `AUTOPILOT_EMBEDDING_PROVIDER`) with that provider's key, or `memoryEmbeddingModel`.
Config file shape (keys can live here instead of the environment):
```json
{
"provider": "deepseek",
"providers": {
"deepseek": { "apiKey": "sk-…", "model": "deepseek-v4-pro" },
"ollama": { "baseUrl": "http://gpu-box:11434/v1" }
}
}
```
### Your OpenRouter key
Three ways to provide it — the first one found wins:
1. **Environment:** `OPENROUTER_API_KEY` (or `AUTOPILOT_OPENROUTER_KEY`). With this set, the setup screen never appears — the way to run autopilot headless (CI, a VM, a container).
2. **Sign in / setup screen / CLI:** "Sign in with OpenRouter" on first run, or `autopilot auth openrouter` — approve in the browser and a key is created and saved (OpenRouter's OAuth PKCE flow). Over SSH or in a container it shows a link to open on any device and asks for the code OpenRouter displays (force this with `--code`). `--paste` prompts for an existing key instead, and `autopilot auth openrouter ` saves one directly. Inside the TUI, `/key set ` replaces it.
3. **Config file:** `"openrouterApiKey": "sk-or-…"` in `~/.config/autopilot/config.json` (created with mode 600).
`/key` shows which key is in use, what it has spent and how much credit is left. Model calls — including memory embeddings and small internal side-calls (summaries, memory extraction) — are all billed to this key.
A key with no credits can still use OpenRouter's **free models** (the "Free" section of `/model`, ids ending in `:free`), subject to OpenRouter's daily request cap.
### Upgrading from the Cloudflare version
Earlier kimiflare versions ran on Cloudflare Workers AI / AI Gateway. On the first launch after upgrading you'll be asked for an OpenRouter key once; after that:
- Your settings (theme, MCP/LSP servers, hooks, memory, sessions, cost history) carry over.
- Model ids are migrated (`@cf/moonshotai/kimi-k2.6` → `moonshotai/kimi-k2.6`, and so on), and the retired Cloudflare fields (OAuth login, gateway, Unified Billing, provider keys) are removed from `config.json`.
- Memory keeps working unchanged: on OpenRouter, embeddings use the same `bge-base-en-v1.5` model Workers AI served.
- `/gateway`, `autopilot auth cloudflare`, `--cloud` and the Cloud-only commands are gone. `/multi-agent` (Commute) is retired; subagents now run locally through Hotcell.
### Subagents
For substantial tasks, the agent can hand independent investigations to **subagents**: separate Autopilot instances that each explore the repository in their own local [Hotcell](https://github.com/directionally-local/hotcell) sandbox and report back cited findings. Several subagents run in parallel behind a single approval while the main agent keeps the conversation and does the edits. You don't need to ask for them; say "don't use subagents" to opt out, or "use subagents" to insist.
Setup: install and start Hotcell, then add your OpenRouter key to its host key store (`hotcell keys add openrouter`). The real key never enters a sandbox. Subagents are read-only (no edits, shell, PRs, or MCP) and see your current working tree, including uncommitted changes — it is streamed into the sandbox, so private repositories work and nothing needs to be pushed (secrets like `.env` are never copied). The first subagent after an install builds a cached runtime (about two minutes, once per version); later ones start in seconds. See [docs/subagents.md](docs/subagents.md) for limits and troubleshooting.
While subagents run they are listed in the activity panel (`/agents`). `/subagents cancel ` stops one without interrupting the turn, and `/subagents stats` shows how often subagents were offered, used, and succeeded over the last week (kept locally in `~/.local/share/autopilot/subagents.jsonl`; no prompts or code are recorded).
### Model
You pick the model on first run, and can switch any time with `/model`. The picker opens on the **best & latest** models — recent, tool-capable models ranked by the agentic and coding benchmark scores OpenRouter publishes (Artificial Analysis), at most two per lab — so it stays current as new models ship, with no list maintained in code. Start typing to fuzzy-search all of them (`sonet` finds Claude Sonnet, `gpt 6` the GPT-6 family). Or set one directly:
```sh
/model moonshotai/kimi-k3 # 1M context
/model anthropic/claude-sonnet-5
/model deepseek/deepseek-v4-flash
autopilot -m moonshotai/kimi-k2.7-code -p "..."
```
Any OpenRouter model id works, including variants like `:free` and `:nitro`. Models OpenRouter lists without tool calling are hidden from the picker — a coding agent needs tools.
**Provider routing (optional).** OpenRouter serves most models through several upstream providers. autopilot always requires providers that support every parameter it sends, and otherwise leaves routing to OpenRouter (price-weighted, uptime-aware, tool-calling quality first, sticky per session for caching). To steer it, add an `openrouterProvider` object to the config file — any of OpenRouter's [provider preferences](https://openrouter.ai/docs/guides/routing/provider-selection):
```json
{ "openrouterProvider": { "ignore": ["SomeProvider"], "data_collection": "deny" } }
```
Avoid `order` / `sort` unless you need them: they turn off sticky routing, which is what keeps the prompt cache warm.
### Custom gateway endpoint
Point every model call at your own OpenAI-compatible endpoint instead of OpenRouter — useful when a
host application (CI, an agents platform, a container) fronts model access with its own broker and
doesn't want to hand autopilot a raw provider key:
```sh
export AUTOPILOT_BASE_URL="https://your-broker.example.com/v1" # /chat/completions is appended
export AUTOPILOT_API_KEY="" # optional; header omitted if unset
autopilot -p "..." # or --mode rpc — no OpenRouter key needed
```
The same pair can be persisted in `~/.config/autopilot/config.json` as `baseUrl` / `apiKey`
(env vars win over the file, field by field). When a base URL is configured:
- Chat requests go to `/chat/completions` and memory embeddings to `/embeddings`,
with `Authorization: Bearer $AUTOPILOT_API_KEY` (no `Authorization` header at all when the key is
unset — e.g. a local llama.cpp/Ollama server).
- Model ids pass through in the request body unchanged; your endpoint owns provider dispatch.
- Cost is the local estimate only — your endpoint does its own metering.
### Requesty (optional)
[Requesty](https://requesty.ai) is another OpenAI-compatible gateway you can use with your own key
instead of OpenRouter. It is opt-in: it is only used when no OpenRouter key and no custom endpoint
are configured, so an existing setup never changes.
```sh
export REQUESTY_API_KEY="" # from https://app.requesty.ai/api-keys
autopilot # or: autopilot auth requesty (checks and saves the key)
autopilot -p "..." -m openai/gpt-4o-mini
```
- The key can also live in `~/.config/autopilot/config.json` as `requestyApiKey` (the env var wins).
- `REQUESTY_BASE_URL` picks a region, e.g. `https://router.eu.requesty.ai/v1` for the EU. Only https URLs on Requesty's hosts (`router.requesty.ai`, `router.eu.requesty.ai`, `router.us.requesty.ai`, `router.ap.requesty.ai`) are accepted, so the key is never sent anywhere else.
- `/model` lists Requesty's managed policies first (short ids such as `kimi-k2.6` or
`claude-sonnet-4-5`), then its full `vendor/model` catalog. Both kinds of id work.
- Defaults on Requesty: `kimi-k2.6` for the main model, `deepseek-v4-flash` for side calls, and
`openai/text-embedding-3-small` for memory embeddings.
- Cost per turn is the one Requesty reports inline. `/key` shows whether the key is valid; OpenRouter
only features (browser sign in, `/key set`, the billed cost lookup) are not available.
### One-shot mode
```sh
autopilot -p "summarize PLAN.md" # stream answer to stdout
autopilot -p "fix the failing test" # edits files and runs commands, as the TUI does
autopilot -p "..." --dangerously-allow-all # also approve what would need a person
autopilot -p "..." --reasoning # include chain-of-thought in stderr
```
**Permissions.** Print mode (`-p`) follows the interactive TUI's policy. What the TUI approves
without asking, print mode approves: edits, writes (except to credentials paths, below), and safe or recoverable commands, with the
same recovery points for `/undo`. What the TUI would stop and ask a person about is denied,
because no one can answer:
| Tool call in print mode | Without `--dangerously-allow-all` | With it |
| --- | --- | --- |
| Read-only tools | run | run |
| Edits, writes, safe and recoverable commands, other tools that ask | **approved** (recovery point first when something is lost) | approved |
| Matches a config `deny` rule | denied | approved (the flag overrides rules and hooks, as before) |
| Matches a config `allow` rule | approved | approved |
| Matches a config `ask` rule, or a `PreToolUse` hook answers `ask` | denied, unless a `PermissionRequest` hook allows it | approved |
| A `PermissionRequest` hook answers | the hook decides | approved |
| Reading or writing credentials (`read`/`grep`, or `write`/`edit`, on `~/.ssh` incl. `authorized_keys`, `~/.aws`, Autopilot's config, `.env`, `/proc/*/environ`, …; the TUI's auto mode approves these). Bash commands that write there (`>> ~/.ssh/authorized_keys`) aren't recognised yet | denied, unless an `allow` rule for that tool names that exact path (`"read": { "~/.aws/credentials": "allow" }`, `"write": { ".env": "allow" }`); broad rules and hooks don't count | approved |
| Irreversible action (guardrails: `git reset --hard`, `terraform destroy`, force push, …) | denied, unless a rule names that exact action | same: the flag doesn't cover it |
With the modes feature flag on (`modesEnabled`), the TUI starts in `edit` mode and asks before
mutating tools, so print mode denies them too unless a rule, a hook or the flag approves.
The model is told the run is headless: no one can answer questions, so it shouldn't ask for
permission or confirmation, and after a denial it should find another way or finish and report
what's left.
To keep the old read-only behaviour (earlier versions denied every mutating call in print mode
without the flag), add deny rules to `~/.config/autopilot/config.json`:
```json
{ "permissions": { "write": { "**": "deny" }, "edit": { "**": "deny" }, "bash": { "**": "deny" } } }
```
**Exit codes.**
| Code | Meaning |
| --- | --- |
| `0` | The run finished. |
| `1` | API error (after retries). |
| `42` | `--max-input-tokens` budget exhausted. |
| `43` | Agent loop detected (repeated blocked calls). |
| `44` | A `UserPromptSubmit` hook blocked the prompt. |
| `45` | The run didn't finish: a tool call was denied, the final reply asks a question, the model offered plan options to choose from, or a limit stopped the turn. |
For `45`, the reason goes to stderr in `text` mode, to an `unfinished` field in `json`, and to an
`unfinished` event (with `reasons`, `denied`, `question`) before `done` in `stream-json`. The
question check is deliberately narrow: the last non-empty line of the final reply, outside a code
block and ignoring trailing markdown, quotes and closing brackets, ends with `?`. A reply that
ends with a statement, such as "Let me know if you need anything else.", counts as finished.
### Run tasks on your own server
Send a task to an Autopilot server you run. It works in its own sandbox and opens a pull request, and you can close your laptop while it does.
```sh
autopilot remote add https://acme.example.com # approve the code in your browser; no keys copied
autopilot --on acme "fix the flaky checkout test" # runs on the server; uncommitted changes go along
autopilot runs # what's running or done, with PR links
autopilot runs watch # follow a run (Ctrl-C detaches, the run keeps going)
autopilot pull # check out the run's branch here
```
The run starts from the last commit your branch shares with `origin`. Unpushed commits, staged and unstaged edits, and untracked files that aren't ignored are sent along as a patch, up to 3 MiB. Add `--detach` to return right away and `-m ` to pick one of the server's models. Each task gets its own sandbox and branch, so several can run at once. The server keeps the model key and GitHub credentials; your laptop holds only a revocable, 90-day pairing credential in `~/.config/autopilot/remotes.json`. Setting up the server side is covered in [docs/dl-server-api.md](docs/dl-server-api.md).
### Headless SDK
Use autopilot programmatically from your own application — no TUI required.
```ts
import { createAgentSession } from "autopilot-ai/sdk";
const { session } = await createAgentSession({
cwd: "/path/to/project",
config: {
openrouterApiKey: process.env.OPENROUTER_API_KEY,
model: "moonshotai/kimi-k2.7-code",
},
});
// Stream every event: text deltas, tool calls, tasks, usage
session.subscribe((event) => {
console.log(event.type, event);
});
// Send a prompt
await session.prompt("Refactor auth to JWT + Redis");
// Mid-flight correction while the agent is still running
await session.steer("Use Redis instead of in-memory store");
// After the turn finishes
await session.followUp("Also add unit tests");
// Clean up
session.dispose();
```
**Key features:**
- `subscribe()` — receive typed events (`SessionEvent` in `src/sdk/types.ts`): `session.start` / `session.end`, `message.start` / `message.delta` / `message.reasoning` / `message.end`, `tool.start` / `tool.result`, `usage`, `permission.request` / `permission.resolved`, `tasks.update`, `warning`, `hook.failed`, `context.compacted`, `status` and `worker.finished`. Errors arrive as `session.end` with `reason: "error"`.
- `prompt()` / `steer()` / `followUp()` — full conversation lifecycle
- `abort()` — stop the running turn
- `setModel()` / `setMode()` / `setReasoningEffort()` — change the model, permission mode (sessions start in `edit`) or reasoning effort (`low|medium|high`)
- `resolvePermission()` — answer a `permission.request` event
- `getStatus()` / `getUsage()` / `save()` — inspect and persist session state
- Custom `permissionHandler` — decide programmatically whether to allow mutating tools
- Optional `memoryEnabled`, `lspEnabled`, `costAttribution` flags
#### Ending a session
Call `session.dispose()` when you're done with a session: it is the reliable way to end it
(SessionEnd [hooks](#hooks), the trace's `session_end`, background subagents, LSP and memory).
As a safety net, a live session also ends if your process exits without `dispose()`. On
`beforeExit`, SIGTERM, SIGINT or SIGHUP the SDK runs SessionEnd hooks and flushes OpenTelemetry
events within a 3 s budget. It never calls `process.exit` and doesn't change whether your
process exits:
- If your app has its own listener for the signal, the SDK starts the shutdown work and your
handler decides what happens next.
- If it doesn't, the SDK finishes the work, then re-raises the signal, so the process still dies
from it (exit status 143 for SIGTERM, 130 for SIGINT).
An uncaught exception that would crash the process, or an explicit `process.exit()`, leaves no
time for asynchronous work. The SDK only starts the SessionEnd hook commands, and buffered
OpenTelemetry events may be lost. If your app handles `uncaughtException` itself, the SDK leaves
its sessions alone; call `dispose()` from your handler.
Apps that manage their own lifecycle can turn this off:
```ts
const { session } = await createAgentSession({ cwd, handleProcessExit: false });
```
#### SDK Authentication
The SDK uses the active [provider](#providers) — `provider` in `config` (or `AUTOPILOT_PROVIDER`),
else OpenRouter — and needs its key: `providers..apiKey` in `config` or the provider's env var
(`OPENAI_API_KEY`, `DEEPSEEK_API_KEY`, …). A [custom gateway endpoint](#custom-gateway-endpoint)
(`baseUrl` / `apiKey` in `config`, or `AUTOPILOT_BASE_URL` / `AUTOPILOT_API_KEY`) needs no other key.
For OpenRouter, the key is resolved in this priority order:
1. **Explicit `config` object** (`openrouterApiKey`) — recommended for apps
2. **Environment variables**: `OPENROUTER_API_KEY` / `AUTOPILOT_OPENROUTER_KEY`
3. **Config file**: `~/.config/autopilot/config.json`
A [Requesty](#requesty-optional) key (`requestyApiKey` in `config`, or `REQUESTY_API_KEY`) also works
when no OpenRouter key is set; pass a Requesty model id such as `openai/gpt-4o-mini` as `model`.
Pass `provider` in `createAgentSession` options to set OpenRouter provider-routing preferences for that session.
**For Electron / desktop apps**, we recommend storing the key in the OS keychain (e.g. Electron `safeStorage` or `keytar`) and passing it explicitly:
```ts
import { createAgentSession } from "autopilot-ai/sdk";
const openrouterApiKey = await keytar.getPassword("autopilot", "openrouter");
const { session } = await createAgentSession({
cwd: projectPath,
config: { openrouterApiKey },
});
```
#### RPC mode (subprocess)
If you need process isolation or a non-Node consumer, run autopilot in JSONL-over-stdio RPC mode:
```sh
node bin/autopilot.mjs --mode rpc
```
Give the subprocess `OPENROUTER_API_KEY` — or a [custom gateway endpoint](#custom-gateway-endpoint)
(`AUTOPILOT_BASE_URL` + `AUTOPILOT_API_KEY`), ideal for host apps that broker model access themselves.
```ts
import { spawn } from "node:child_process";
const proc = spawn("npx", ["autopilot-ai", "--mode", "rpc"], {
cwd: projectPath,
stdio: ["pipe", "pipe", "pipe"],
});
// Read events
proc.stdout.on("data", (chunk) => {
for (const line of chunk.toString().split("\n")) {
if (!line.trim()) continue;
const event = JSON.parse(line);
console.log(event.type, event);
}
});
// Send commands
proc.stdin.write(JSON.stringify({ type: "new_session" }) + "\n");
proc.stdin.write(JSON.stringify({ type: "prompt", message: "Hello" }) + "\n");
// Resolve a permission request
proc.stdin.write(
JSON.stringify({ type: "resolve_permission", requestId: "req_0", decision: "allow" }) + "\n"
);
// Resume a previous session after a process restart (the `new_session`
// response echoes back the sessionId to store for later)
proc.stdin.write(JSON.stringify({ type: "new_session", sessionId: "sdk-session-…" }) + "\n");
```
### Image understanding
```sh
autopilot
› fix the layout bug in this screenshot docs/bug.png
› convert this mockup design.png to Tailwind HTML
```
## Slash commands
| Command | Effect |
|---------|--------|
| `/settings` | List feature settings; `/settings modes on\|off` turns plan/edit/auto modes on or off (off by default), `/settings diagnostics on\|off` toggles post-edit diagnostics, `/settings ideas on\|off` the project summary and starter tasks on a repository's first session (off by default), `/settings refocus on\|off` bringing the terminal back after a browser sign-in (macOS), `/settings pr-footer on\|off` the line "Opened with [dl](https://dl.new), a free coding agent." at the end of pull requests the agent opens (on by default, every provider; never added to commits; also `prFooter: false` in config.json or `AUTOPILOT_PR_FOOTER=0`), `/settings invite-tip on\|off` the one-time invite line after your first opened PR or passing tests on the free tier |
| `/usage` | Directionally Local: your plan (Free or Pro), tokens used and left this week, top-up tokens left, invite bonus, place in line when queued, and when the week resets |
| `/invite` | Free tier: your invite link (copied to the clipboard where the terminal allows it), how many joined, how many were active this week, and the bonus earned; each friend who starts using dl gives you both extra free tokens every week. Also `autopilot invite` |
| `/upgrade` | Directionally Local: buy dl Pro or a one-time top-up (choose an amount; opens the payment page, then waits up to 10 minutes for it to show); on Pro, opens the page to manage or cancel your plan. Also `autopilot upgrade [pro\|topup]`. When free usage runs out mid-session, a screen offers dl Pro first (at the price the service sends), then a top-up, asking for more free usage (`/request`), your own key (`/provider`) and your own GPUs (`dl model up`); the blocked request continues once a purchase shows |
| `/tour` | A short step-by-step tour of what's different about dl: providers and the free tier, invites, memory, bringing your setup from other agents, background work, where sessions live, your own GPUs. → / l / Enter next, ← / h back, Esc / q close; nothing is printed. The startup screen shows a `/tour` hint until it has been opened once |
| `/ideas` | Summarize this project (name, kind, file count, test command, open GitHub issues when `gh` is signed in) and suggest three tasks; type 1–3 to start one. With `/settings ideas on`, also shown on the first session in each git repository (remembered in `~/.local/state/autopilot/project-tour.json`, never in the repo); one small model call words the tasks (capped at 200 output tokens, local suggestions after 4 s) |
| `/mode edit\|plan\|auto` | Switch permission mode (needs modes on) |
| `/shell auto\|bash\|cmd\|powershell` | Show or set the shell for the bash tool |
| `/resume` | Pick a past conversation to restore |
| `/checkpoint [label]` / `/checkpoint list` | Save a checkpoint in the current session, or list this session's checkpoints |
| `/undo` | Restore the latest recovery point Autopilot saved before a destructive file or git action in this project |
| `/audit` | Read-only report of what the agent could destroy from here: allowed destructive actions, reachable databases and cloud accounts (names and hosts only), recovery that exists, and suggested rules |
| `/compact` | Summarize older turns to free context |
| `/init` | Scan repo and write `AGENTS.md` project context (refreshes an existing `AGENTS.md`, or a legacy `KIMI.md`, `KIMIFLARE.md` or `AGENT.md` in place) |
| `/setup-import` | Show what Autopilot uses from your other coding agents (Claude Code, Cursor, Gemini CLI, GitHub Copilot, OpenCode) |
| `/memory` | Show memory stats and search |
| `/mcp list` / `/mcp reload` | Manage MCP servers |
| `/reasoning` | Toggle chain-of-thought display |
| `/model` | Pick a model from the active provider's catalog (or `/model `, `/model list [filter]`) |
| `/provider` | List providers, or switch with `/provider [key]` (see [Providers](#providers)) |
| `/jev` | Ask Jev for a typed, scoped one-shot decision |
| `/subagents` | List running subagents; `/subagents cancel \|all` stops them; `/subagents off\|suggest\|auto` sets the delegation policy (default: `auto`) |
| `/now` | Run your latest queued message now instead of after the current turn |
| `/key` | Show the active provider's key — on OpenRouter with spend and credit (`/key set `, `/key clear`) |
| `/cost` | Show cost by session, day, month and all time (OpenRouter-confirmed, or estimated from the provider's prices) |
| `/good` / `/bad` `[note]` | Rate the last turn; recorded in the session trace when [tracing](#session-traces-and-evals) is on |
| `/update` | Check for updates |
| `/help` | List all commands |
There is no `/thinking` command. In the interactive UI the reasoning effort for each turn follows the request's intent tier (light → `low`, medium → `medium`, heavy → `high`), and a custom command (`/command create`) can pin it with `effort`. `reasoningEffort` in config (or `KIMI_REASONING_EFFORT`) sets the session default, and SDK sessions can change it with `setReasoningEffort()`.
### Subagent routing
`/subagents auto` is the default: on substantial tasks the agent is asked to look for independent parts and delegate them, and it decides whether delegation is worth it. `suggest` only hints at delegation for likely parallel work, and `off` disables harness guidance (you can still ask for subagents explicitly). Explicit requests to use subagents or to work without them always win. Set the policy with `/subagents`, `AUTOPILOT_SUBAGENT_POLICY`, or `subagentPolicy` in config.
The harness never starts a subagent by itself: the agent calls the `subagent` tool, which always needs normal tool permission (one prompt covers a parallel batch) and obeys provider, read-only, spend, concurrency, and timeout limits. In Code Mode the `subagent` tool stays a direct tool next to `execute_code`. Jev (a fast yes/no decision model on OpenRouter) sharpens this: in `auto` mode it checks whether a substantial request has independent parts (strong delegation guidance at ≥80%, otherwise the softer nudge), and in `suggest` mode it decides whether to suggest at all. It receives at most 1,200 characters of redacted request text, runs alongside other pre-turn work, and any failure falls back to the default guidance.
### Finishing the job
When a substantial turn ends without the agent asking you anything, a Jev yes/no check asks whether it actually finished — or clearly explained a blocker — rather than stopping after a plan or "next I'll…". If it clearly didn't, the agent is told to continue (once per turn), so you don't have to type "go on". Typically under a second; OpenRouter only. Turn it off with `"completionCheck": false` in config or `AUTOPILOT_COMPLETION_CHECK=0`.
## Running shell commands yourself
Type `!` followed by a command (for example `! gh auth login`) to run it in your own terminal, inside the session. Logins, password prompts and interactive programs work because the command gets the real TTY. The output is added to the conversation so the agent can see it. The agent's own `bash` tool has no terminal, so autopilot suggests `! ` when something needs you: a login, a `sudo` password, an SSH passphrase, or a secret you'd rather not paste into chat. On macOS and Linux the output is captured with `script(1)`; elsewhere the command still runs but its output isn't captured.
## Keyboard shortcuts
| Shortcut | Action |
|----------|--------|
| `Ctrl+C` / `Esc` | Interrupt current turn when busy; exit when idle |
| `Ctrl+R` | Toggle reasoning display |
| `Ctrl+O` | Toggle verbose tool output |
| `Shift+Tab` | Cycle mode (edit → plan → auto) when modes are on (`/settings modes on`) |
| `↑` / `↓` | Walk prompt history |
### Messages sent while the agent is working
A message you send mid-turn is triaged instead of always waiting in line:
- **interrupt** ("stop, that's the wrong file"): the turn stops at the next safe point and your message runs next. Running subagents are never cancelled by an interrupt; while they run, the message is delivered as soon as they finish.
- **steer** ("also handle the empty case"): folded into the current task at the agent's next step.
- **queue** ("after this, update the changelog", or anything unclear): runs as its own turn afterwards. Send `/now` to promote it.
- **aside** ("how's it going?"): answered from the current state without disturbing the turn.
Clear phrasing is decided instantly; ambiguous messages get a quick model check (OpenRouter only), and anything uncertain is queued. Use `/subagents cancel ` to stop a single subagent.
## Running inside herdr
[herdr](https://github.com/herdrdev/herdr) is a terminal multiplexer for coding agents. Run `autopilot` (or `autopilot -p "…"`) in a herdr pane and it reports its own state there, so herdr doesn't have to guess from the screen:
- `working` while a turn runs, `blocked` while a permission prompt or a plan choice waits on you, `idle` when Autopilot is ready for your next message;
- the first line of the current task as the `summary` token (use `$summary` in herdr's Agent sidebar rows);
- the command that reopens the conversation (`autopilot --session `, or `autopilot --continue` before the first message), so the pane comes back in the same session after a herdr server restart;
- a release of the pane when Autopilot exits.
There is nothing to install or configure: Autopilot reports when `HERDR_PANE_ID` and `HERDR_SOCKET_PATH` (or `HERDR_BIN_PATH`) are set, which herdr does for every pane, and does nothing otherwise. Reports go over herdr's socket API (falling back to the `herdr` CLI), run in the background with a 500 ms timeout, and never hold up the agent; a failure is logged once (`herdr.report_failed`). An Autopilot started from inside another one in the same pane leaves the reporting to the outer one. Check what herdr sees with `herdr agent list`. Remote sessions (`autopilot --on `, the dl server) don't report.
## Logs
autopilot writes structured JSON logs of agent-side activity (tool calls,
permission decisions, MCP/LSP lifecycle, session events, errors) to
`~/.config/autopilot/logs/.jsonl`, one file per day, with 7-day
retention pruned automatically at startup.
The logs deliberately exclude prompts and completions. To capture full
request/response payloads locally for debugging, run with
`AUTOPILOT_DUMP_LLM=1`; each generation is also visible in your
[OpenRouter activity log](https://openrouter.ai/activity).
```sh
autopilot logs path # today's file
autopilot logs dir # log directory
autopilot logs prune # delete files older than 7 days
# Tail this session's activity, formatted:
tail -f $(autopilot logs path) | jq
# Find the slowest tool calls in the last day:
jq -r 'select(.event == "tool:end") | "\(.data.duration_ms)\t\(.data.tool)"' \
$(autopilot logs path) | sort -rn | head
```
Disable the file sink entirely with `AUTOPILOT_LOG_SINK=off`. The
separate `AUTOPILOT_LOG_LEVEL` env var (default `off`) controls stderr
output — independent of the file sink.
### Shipping to an OpenTelemetry collector
If you set `AUTOPILOT_OTEL_ENDPOINT`, autopilot also ships each log
entry to that endpoint over [OTLP/HTTP](https://opentelemetry.io/docs/specs/otlp/)
so it lands in Datadog, Honeycomb, Grafana Loki, an internal collector,
or any other backend that speaks OTel. Batched every 5 s (or every
100 entries, whichever first) and best-effort — never blocks the agent
loop.
```sh
# Full path:
export AUTOPILOT_OTEL_ENDPOINT="https://otel.example.com/v1/logs"
# Or just the base URL (we auto-append /v1/logs):
export AUTOPILOT_OTEL_ENDPOINT="https://otel.example.com"
# Optional headers (comma-separated key=value pairs) — e.g. for auth:
export AUTOPILOT_OTEL_HEADERS="Authorization=Bearer xyz,X-Tenant=acme"
```
Each log entry maps to one OTel `LogRecord`. Correlation IDs
(`session_id`, `turn_id`, `request_id`) become record attributes,
`data.*` fields are flattened to attributes with type-preserving
encoding, and a `service.name=autopilot` + `service.version` pair sits
on the resource.
## Session traces and evals
Autopilot can record its own sessions so you can see how it performs on your work, and compare setups on your own tasks. Everything stays on your machine.
### Session traces
Tracing is off by default. Turn it on for one run with `AUTOPILOT_TRACE=1`, or always with `"trace": { "enabled": true }` in `~/.config/autopilot/config.json`. Each session then writes a `trace.jsonl` under `~/.local/share/autopilot/traces/` (`AUTOPILOT_TRACE_DIR` or `trace.root` to change it), one event per line:
- every model request and response, with tokens, cost and latency
- tool calls and their results, and each permission decision
- compactions, completion checks, subagents and turn ends
- **outcome signals:** the git changes a session made, test, lint, typecheck and build commands and whether they passed, your `/good` and `/bad` ratings (with an optional note), and whether your next message corrected the agent or told it to carry on
Large bodies are stored once, by hash, next to the trace. Likely secrets are redacted before anything is written, nothing is uploaded, and a single session stops recording at 200 MB.
### Insights
`autopilot insights` aggregates your traces into one row per model: requests per user message, parallel-call share, bash share and bash-as-read share, tool failure rate by error code, guardrail hits, cache hit rate, redundant reads and cost. It is how model profiles are tuned — a profile is only changed when these numbers (and an eval comparison) say it helps.
```sh
autopilot insights # every traced session under the trace root
autopilot insights --since 2026-10-01 # recent sessions only
autopilot insights --model deepseek/deepseek-v4.1-flash --json
```
### Local history
Autopilot never deletes your saved sessions or traces on its own; they are yours to analyze. Once they pass 1 GB, a new session mentions how much space they take. To see where they live, or to free space:
```sh
autopilot history # counts, sizes and paths
autopilot history prune --older-than 30 # delete sessions and traces untouched for 30 days
```
### Evals
`autopilot eval` runs Autopilot headlessly on a set of tasks and compares two configurations: a model, a setting, or a harness change.
```bash
autopilot eval run --tasks evals/tasks/autopilot-bench --config evals/configs/baseline.json --model --out /tmp/eval-a
autopilot eval run --tasks evals/tasks/autopilot-bench --config evals/configs/my-change.json --model --out /tmp/eval-b
autopilot eval compare /tmp/eval-a/results.jsonl /tmp/eval-b/results.jsonl
```
Each task is a JSON file naming a repo, a base commit, a prompt and a test command. Every run gets its own git worktree with tracing forced on, and the task passes if the test exits 0. `eval compare` prints success rates with a paired significance test, cost, turns and the tasks that flipped. This repository ships `autopilot-bench`, twenty tasks mined from its own merged pull requests; see [evals/README.md](evals/README.md) for the task format and how to build a set from your own repo.
## Hooks
autopilot can fire shell commands at these points, configured
per-project (`.autopilot/settings.json`) or globally
(`~/.config/autopilot/settings.json`); the older kimiflare paths are
still read (see [Settings location](#settings-location)):
| Event | Fires when | Veto? |
|--------------------|-------------------------------------------------|-------|
| `SessionStart` | A session's first prompt, before `UserPromptSubmit` (`source`: startup/resume) | No |
| `PreToolUse` | A tool call is about to run | Yes |
| `PostToolUse` | A tool call just finished (success or failure) | No |
| `PostToolUseFailure` | A tool call failed (also fires `PostToolUse`) | No |
| `PermissionRequest` | You're about to be asked to approve a call | Allow / deny |
| `UserPromptSubmit` | A prompt is submitted, in every mode (TUI, `-p`, `--emit-events`, `serve`, SDK) | Yes |
| `Stop` | A turn ended cleanly | No |
| `StopFailure` | A turn was interrupted or failed, instead of `Stop` (`error`, `is_interrupt`) | No |
| `PreCompact` | Compaction is about to run (`trigger`: auto/manual) | No |
| `SessionEnd` | autopilot exits, or `/clear` (`reason`) | No |
Hooks receive the event payload as JSON on stdin **and** as
`AUTOPILOT_HOOK_*` env vars (for shell-one-liner ergonomics; every one
is also set under its old `KIMIFLARE_HOOK_*` name, so existing scripts
keep working). The full
JSON copy in `AUTOPILOT_HOOK_PAYLOAD` is only set for payloads up to
32 KiB (OSes cap environment variable size); above that it is omitted,
`AUTOPILOT_HOOK_PAYLOAD_OMITTED=1` is set, and stdin is the only source —
prefer reading stdin. Payloads
also carry Claude Code's field names (`hook_event_name`, `tool_name`,
`tool_input`, `tool_response`, `tool_call_id`, `transcript_path`), so
Claude Code hook scripts — and tools built for them, like
[Agent Beacon](docs/beacon.md) — work unchanged. A successful
`write`/`edit`'s `tool_response` carries Claude Code's `structuredPatch`
and `originalFile` (and `type: "create" | "update"` for `Write`); see
[docs/beacon.md](docs/beacon.md#tool-names-and-result-shapes) for the
size limits.
#### Turn ends: `Stop` and `StopFailure`
Every prompt that reaches the model ends in exactly one `Stop` or one
`StopFailure`, so an observer (a status board, a session log) never
shows a finished turn as still running. `StopFailure` fires when the
turn ends without a clean finish, with:
- `error`: `interrupted` (you stopped it: Esc, Ctrl+C, an SDK or
`serve` abort), `model_error` (the model or its provider failed after
retries), `budget_exhausted`, `context_limit`, or `error` (anything
else). More kinds may be added; read an unknown one as a failure.
- `is_interrupt`: `true` only for `interrupted`.
It carries no error text, only the kind. A guardrail that ends the
turn with a summary fires `Stop`, as before.
#### Payload stability
Every payload carries `hook_payload_version` (currently `1`) and
`autopilot_version`. Within a payload version fields are only added:
an existing field is never renamed, retyped or removed, and an event
keeps its meaning. Any of those changes bumps `hook_payload_version`
and is called out in the changelog. The stable fields are the ones in
this section and in [docs/beacon.md](docs/beacon.md): `hook_event_name`,
`session_id`, `cwd`, `client` (`"autopilot"`), `transcript_path` /
`transcript_format`, the tool fields (`tool_name`, `tool_input`,
`tool_response`, `tool_use_id`, `error`, `is_interrupt`), and each
event's own fields (`source`, `model` and `provider` on `SessionStart`;
`prompt` on `UserPromptSubmit`; `last_assistant_message` on `Stop`;
`error` and `is_interrupt` on `StopFailure`; `permission_mode` on
`PermissionRequest`; `trigger` on `PreCompact`; `reason` on
`SessionEnd`). Payloads never carry API keys or provider tokens, and
the transcript is redacted (see docs/beacon.md).
Hooks run in the turn: Autopilot waits for each one, up to its
`timeoutMs` (default 30 s). An observer should return at once and do
its work in the background; give it a short `timeoutMs` (a few seconds)
so a hung observer can't hold a turn.
A blocked `UserPromptSubmit` never reaches the model: the TUI shows the
reason, `-p` and one-shot `--emit-events` exit with code **44**,
`serve` answers `403 prompt_blocked`, and the SDK's `prompt()` rejects
with `PromptBlockedError` (details in
[docs/beacon.md](docs/beacon.md#session-and-prompt-events)).
#### Blocking and exit codes
Veto events (`PreToolUse`, `UserPromptSubmit`) follow Claude Code's rules:
| Hook result | Effect |
|-------------|--------|
| exit `0` | Allowed. Stdout may carry a JSON decision (below). |
| exit `2` | **Blocked.** Stderr (or stdout if stderr is empty) is the reason shown to the model. |
| any other non-zero exit, timeout, command not found (127), spawn error | The hook **failed**: you get a warning and the action is **allowed** (fail-open), so a broken or missing hook never wedges every tool call — unless the hook sets `"failClosed": true` (see [Hook failures](#hook-failures-and-failclosed)). |
A `PreToolUse` hook that exits `0` can instead print a JSON decision:
```json
{ "hookSpecificOutput": { "hookEventName": "PreToolUse",
"permissionDecision": "deny", "permissionDecisionReason": "no writes to prod config" } }
```
- `deny` blocks, with `permissionDecisionReason` as the reason.
- `ask` sends the call through the normal permission prompt, even for
tools that don't usually ask. Hosts with no one to ask deny it
(`--print` denies unless `--dangerously-allow-all`).
- `allow` means the hook doesn't object; it does **not** bypass your own
permission rules or mode.
With several hooks, `deny` wins over `ask`, which wins over `allow`.
The legacy `{"decision": "block", "reason": "..."}` form also blocks
(use it for `UserPromptSubmit`). Stdout that isn't JSON is ignored, as
before. Hooks written for older versions that blocked with `exit 1`
must switch to `exit 2`.
#### Hook failures and `failClosed`
When a hook times out, can't be started (missing binary, exit 127) or
exits non-zero (other than `2` on a veto event), Autopilot tells you
instead of only logging it:
- The TUI (classic and Camouflage) shows a warning naming the hook, the
event, why it failed and what happened to the action. `--print` writes
it to stderr (`hook_failed` event in `--output-format stream-json`, a
`hookFailures` array in `json`); `--emit` sends a `RuntimeError`
warning; the SDK emits a `hook.failed` session event; `autopilot
serve` sends a `hook.failed` SSE event and lists them under
`hookFailures` in `GET /session/:id`.
- It is shown **once per hook per session**. Later failures are counted
(`/hooks list` shows `[failed N× this session]`) but not shown again.
- Every failure is also an OpenTelemetry event, `autopilot.hook.failed`
at WARN, with `hook.id`, `hook.event`, `hook.failure`
(`timeout` / `spawn_failed` / `command_not_found` / `nonzero_exit`),
`hook.reason`, `hook.allowed`, `hook.fail_closed` and
`hook.failure_count`, so a collector such as Agent Beacon records that
a policy hook did not run.
For a policy hook that must never be skipped, set `"failClosed": true`
on it. On the veto events (`PreToolUse`, `UserPromptSubmit`,
`PermissionRequest`) a failure then **blocks** the action, with a reason
naming the hook and the failure. It has no effect on informational
events.
```json
{ "hooks": { "PreToolUse": [
{ "id": "policy", "command": "my-policy-check", "timeoutMs": 10000, "failClosed": true }
] } }
```
#### `PermissionRequest` and `PostToolUseFailure`
`PermissionRequest` fires when Autopilot is about to ask you to approve a
tool call — after plan mode, `--dangerously-allow-all` and config
permission rules have had their say, so it never fires for calls those
already settled. In print mode it fires for every such call, before print
mode's own default (approve what the TUI approves without asking). The payload has `tool`, `args`, `tool_call_id`,
`mode` (`edit`, `plan`, …; also `$AUTOPILOT_HOOK_MODE`), plus Claude Code's `tool_name`,
`tool_input`, `tool_use_id` and `permission_mode`; `matcher` matches the
tool name. The hook decides like a `PreToolUse` hook:
- exit `2`, or `{"hookSpecificOutput": {"permissionDecision": "deny", "permissionDecisionReason": "..."}}`:
**denied** without asking you; the reason goes to the model.
- `permissionDecision: "allow"`: **approved without asking you**. Unlike
`PreToolUse`, where `allow` only means "no objection", answering the
approval prompt is what this event is for. It never overrides plan mode
(an `allow` there still shows the prompt) or a config deny rule (those
calls never reach the hook).
- `"ask"`, no JSON, or a hook that fails open: the normal prompt.
Hosts with no one to ask follow their own policy (`--print` approves
what the TUI would approve without asking and denies the rest).
Claude Code's form, `{"hookSpecificOutput": {"decision": {"behavior": "allow"|"deny", "message": "..."}}}`,
works too.
`PostToolUseFailure` fires when a tool call fails — an error, a denied
permission, or a `bash` command that exits non-zero or is killed — with
`tool`, `args`, `tool_call_id`, `error` (the failure as text) and
`result`, plus Claude Code's `tool_name`, `tool_input`, `tool_use_id`,
`error` and `is_interrupt`. `PostToolUse` **keeps firing for failures
too**, as before, so existing hooks are unaffected; register a hook on
only one of the two if you don't want to see a failure twice.
Both fire from every host: the TUI, `--print`, `--emit`, the SDK and
`autopilot serve`.
### Settings location
Hooks are read from four files and merged, in this order:
1. `~/.config/kimiflare/settings.json` (legacy global; after the one-time move it is a link to the file below and is read once)
2. `~/.config/autopilot/settings.json` (global)
3. `.kimiflare/settings.json` (legacy project)
4. `.autopilot/settings.json` (project)
`~/.config` is `$XDG_CONFIG_HOME` when that is set. For each event,
hooks run in that order; an entry with the same `id` as an earlier one
replaces it (ids are derived from event + command when not set, so a
hook copied verbatim from a legacy file runs once). The autopilot paths
are canonical: `/hooks enable`, the hook wizard and the dashboard write
new hooks there, while enabling or disabling an existing hook edits the
file it lives in. Project legacy files are never moved or dropped (the
global one moves with the rest of `~/.config/kimiflare`); if your hooks
are only in a legacy file, autopilot shows a one-time notice naming the
new path. `/hooks path` prints all four.
### Project trust
A repository can ship hooks (`.autopilot/settings.json`,
`.kimiflare/settings.json`) and language servers (`.autopilot/lsp.json`,
or the older `.kimiflare/lsp.json`),
and both run commands on your machine. Autopilot does not load a
project's copies until you have trusted them, so cloning a repository and
starting Autopilot in it runs nothing the repository chose. When a project
has untrusted settings, Autopilot says so at startup.
- `/trust` (or `autopilot trust` in the project directory) lists every
command the files would run. `/trust yes` (or answering `y`) trusts
exactly that content.
- Trust is recorded per file as a SHA-256 of its content in
`~/.config/autopilot/trusted-project-files.json`. Any later change,
such as a `git pull` or a branch switch, needs review again.
- Hooks you add with `/hooks`, the wizard or the dashboard, and LSP
settings saved by `/lsp config`, stay trusted: they are your own edits.
- For CI and other headless runs in repositories you control, set
`AUTOPILOT_TRUST_PROJECT=1` to trust project files for that process.
Global settings (`~/.config/...`) are always loaded.
### Matchers
`matcher` is a regex tested against the tool name for `PreToolUse`,
`PostToolUse`, `PostToolUseFailure` and `PermissionRequest`. It is tried against both autopilot's native name and the
Claude Code name (`bash`/`Bash`, `edit`/`Edit`, `write`/`Write`,
`read`/`Read`, `glob`/`Glob`, `grep`/`Grep`, `web_fetch`/`WebFetch`,
`search_web`/`WebSearch`; an edit with `edits[]` also answers to
`MultiEdit`), so a matcher copied from a Claude Code config works.
| Matcher | Matches |
|---------|---------|
| `bash`, `Bash`, `^bash$` | bash calls |
| `Bash\|Edit`, `^(edit\|write)$` | either tool |
| `^mcp_` | every MCP tool |
| `*`, `""`, or no matcher | every tool |
Matching is case-sensitive (`BASH` matches nothing) and unanchored
(`dit` matches `edit`; use `^…$` for an exact name). An invalid regex
matches nothing.
### Browse + enable from the TUI
```text
/hooks # list configured hooks
/hooks recommended # list starter hooks shipped with autopilot
/hooks enable stop-bell # enable one (writes to .autopilot/settings.json)
/hooks enable stop-bell global # ...or the global file
/hooks disable stop-bell
/hooks path # print settings.json paths (incl. legacy ones)
/hooks reload # re-read settings.json after a manual edit
```
The recommended catalog includes terminal bells / macOS notifications
on `Stop`, secret-file guards on `PreToolUse` (e.g. block edits to
`*.env`), auto-format-with-prettier on `PostToolUse`, and a tool-call
audit log. All ship disabled — `/hooks recommended` lists them.
### Schema example
```json
{
"hooks": {
"PreToolUse": [
{
"id": "no-secrets",
"matcher": "^(edit|write)$",
"command": "case \"$AUTOPILOT_HOOK_PATH\" in *.env|*.pem) echo 'blocked' >&2; exit 2;; esac"
}
],
"PostToolUse": [
{
"id": "format-ts",
"matcher": "^(edit|write)$",
"command": "npx --no-install prettier --write \"$AUTOPILOT_HOOK_PATH\" >/dev/null 2>&1 || true"
}
],
"Stop": [
{ "id": "bell", "command": "printf '\\a'" }
]
}
}
```
Per-hook fields:
- `command` (required) — the shell command.
- `matcher` (optional) — regex matched against the native or Claude Code
tool name for `PreToolUse` / `PostToolUse` (see [Matchers](#matchers)).
Ignored for other events.
- `id` (optional) — stable handle for `/hooks enable|disable`.
Auto-derived from `event + command` when omitted.
- `enabled` (default `true`) — set `false` to keep a hook in config
but skip it.
- `timeoutMs` (default `30000`) — hard kill if the hook hangs (the
action then proceeds, with a warning).
- `description` (optional) — shown by `/hooks list`.
- `failClosed` (default `false`) — on veto events, block when the hook
itself fails instead of failing open.
Hooks are always-on infrastructure: they fire whether the TUI is open
or autopilot is running in `--print` mode. They also fire for tool
calls generated from inside the Code Mode sandbox (heavy-tier turns),
because hook firing lives on the `ToolExecutor` itself — every call
path uses the same plumbing.
When intent classification has assigned a tier, hook payloads include
it as `tier: "light" | "medium" | "heavy"` (on `UserPromptSubmit`,
`PreToolUse`, `PostToolUse`) and as `$AUTOPILOT_HOOK_TIER`. Useful for
"skip auto-format on light turns" or "audit every heavy-turn write."
SDK consumers opt in to hooks with `enableHooks: true` on
`createAgentSession`. Default is off because the SDK is a primitive,
not the TUI. SDK sessions fire SessionEnd on `dispose()`, or when the
process exits without it (see [Ending a session](#ending-a-session)).
## MCP servers
Add servers to `~/.config/autopilot/config.json` (or `$XDG_CONFIG_HOME/autopilot/config.json`) under `mcpServers`. There is no interactive add wizard: `/mcp list` shows what is connected and `/mcp reload` reconnects after an edit.
```json
{
"mcpServers": {
"filesystem": {
"type": "local",
"command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
},
"linear": { "type": "remote", "url": "https://mcp.linear.app/sse" },
"meta-ads": {
"type": "http",
"url": "https://mcp.facebook.com/ads",
"headers": { "Authorization": "Bearer ${META_ADS_ACCESS_TOKEN}" }
}
}
}
```
- `local` runs a command over stdio.
- `remote` uses the legacy SSE transport.
- `http` uses the MCP Streamable HTTP transport (POST plus an optional SSE stream), which most hosted servers use. `${VAR}` in `url`, `env` and `headers` is expanded from the environment, so a token can stay out of the file.
Servers configured in Claude Code, Cursor and OpenCode are also picked up automatically; they stay off until a task needs one. Hosted servers that require OAuth (rather than a bearer token) are not supported yet — use a user or system-user access token in `headers` instead.
## Development
```sh
git clone https://github.com/directionally-local/autopilot
cd autopilot
npm install
npm run build
npm link
```
Scripts:
- `npm run build` — bundle with tsup
- `npm run dev` — run via tsx
- `npm run typecheck` — `tsc --noEmit`
- `npm test` — run tests
## Community
Questions, ideas, or something you built with it: [join the Directionally Local Discord](https://discord.gg/zeBnJTgcRK).
## Contributing
1. Fork the repository
2. Create a branch: `git checkout -b feat/your-feature`
3. Make your changes
4. Run `npm run typecheck` and `npm run build`
5. Commit with [Conventional Commits](https://www.conventionalcommits.org/)
6. Open a Pull Request
---
Built by [Sina Meraji](https://github.com/sinameraji) and [contributors](https://github.com/directionally-local/autopilot/graphs/contributors) · MIT License