Documentation Index
Fetch the complete documentation index at: https://docs.clideck.dev/llms.txt
Use this file to discover all available pages before exploring further.
Autopilot is a project-level workflow router. It watches your agents, waits for them to finish, then forwards one agent’s output to the next agent that should see it. It does not do the work itself, and it does not rewrite or summarize the routed content.
Think of it as a dispatcher: it reads the state of your project, understands each agent’s role, and decides who should act next.
Why This Architecture
Autopilot is a dispatcher, not a critic. It doesn’t evaluate quality, rewrite agent output, or inject its own instructions. It makes one small decision per round — who should see this output next — and gets out of the way.
This design is intentional:
- Cheap to run — The router’s only job is to pick the next handoff. Its average output is 30–50 tokens per round — a steering decision, not a conversation. Even expensive models cost very little when they only emit a tool call.
- Non-destructive — You can enable or disable Autopilot at any time. It doesn’t own the sessions. Stop it mid-workflow and your agents keep their full context. Start it again and it picks up from the current state.
- You stay in control — You can type directly into any agent session while Autopilot is running. Your input takes priority. Autopilot waits for all agents to go idle before acting, so it never races you.
The agents do the work. Autopilot picks the next handoff.
Requirements
Autopilot works on sessions within a project that have assigned roles. Both are required:
- Sessions must be grouped in the same project
- Each session must have a role assigned when created
- No two sessions in the same project can share the same role
- At least one session with a role must exist in the project
How It Works
The core loop:
- Wait for idle — Autopilot monitors all role-assigned sessions in the project. It acts only when all agents are idle.
- Inspect state — It reads the structured workflow state: which outputs are new, which were already routed, what the last handoff was, and whether progress has stalled.
- Consult the router — An LLM evaluates the current state and each agent’s role responsibilities, then calls one of two tools:
route(from, to) — Forward one agent’s output to anothernotify_user(reason) — Stop Autopilot and alert the user
- Forward output — The selected agent’s output is sent verbatim to the target agent’s terminal, wrapped with a small header showing routing context.
This cycle repeats until the task is complete, the workflow is blocked, or you stop it manually.
When Autopilot routes output from one agent to another, the receiving agent sees:
[Autopilot route | output #a1b2c3]
[Team: Programmer, Reviewer, Product Manager]
[You are: Reviewer]
[From: Programmer]
[Do not spawn internal agents.]
<original output from the source agent, verbatim>
Routing Intelligence
Autopilot tracks routing state to avoid useless loops:
- Output identity — Each output gets a hash ID. Autopilot knows if the same output was already routed to a given agent.
- Handoff history — A log of all routes is maintained per project. The router sees the last 30 entries.
- Waiting state — After routing, Autopilot records which role it’s waiting on for new output.
- Staleness detection — If all agents are idle and no new output has appeared since the last route, the state is flagged as stale. The router can use this to decide if the workflow is stuck.
The router prefers new output over previously routed output, and uses role responsibilities and restrictions to choose the most appropriate next specialist.
Role-Aware Routing
Autopilot reads each agent’s role instructions before every routing decision. It uses the instructions to understand what each agent is responsible for, what kind of output they should receive, and when they should be involved.
This means routing adapts to whatever roles you define. For example, say you have a team with a Programmer, a Reviewer, and an Innovation Officer whose role prompt says: “Check every code change for whether it pushes boundaries. If the approach is too conventional, send it back with suggestions for more creative solutions.”
Autopilot reads that prompt and understands: after the Programmer writes the code and the Reviewer approves it, route it to the Innovation Officer for a creativity check. If the Innovation Officer pushes back, route it back to the Programmer with the feedback.
You don’t configure this routing order anywhere. Autopilot infers it from the role instructions. The more specific your role prompts are about responsibilities and when an agent should be involved, the better Autopilot routes.
When It Notifies You
Autopilot calls notify_user only in specific situations:
- Work is naturally complete — All agents agree the task is done
- Truly blocked — Something prevents progress (missing dependency, conflicting requirements, etc.)
- Human input needed — A decision only a human can make
It does not ask for permission to continue, and it does not pause to check in. The expectation is that you can walk away and come back when notified.
Starting and Stopping
Each project header in the sidebar has an Autopilot button (visible when the project has role-assigned sessions).
- Click to start — Autopilot discovers all role-assigned sessions in the project and begins the routing loop
- Click to stop — Autopilot stops immediately. Active agent sessions are not affected.
When Autopilot starts, it seeds its state from the current screen output of any idle agents, so it can make an informed first routing decision without waiting for new work.
The Project Pill
While running, Autopilot appears as a pill in the sidebar under its project. The pill shows:
- Status — Working (spinner) when consulting the router, idle when waiting for agents
- Status text — Current action, e.g., “Consulting router…”, “Waiting on Reviewer”, “Programmer -> Reviewer”
Click the pill to view the Autopilot log — a timestamped feed of everything it did:
- Worker discovery (“Started with 3 workers: Programmer, Reviewer, Product Manager”)
- Routing decisions (“Routed Programmer -> Reviewer”)
- Status transitions (“Reviewer -> idle”)
- Notifications (“Notify: All tasks complete, tests passing”)
When Autopilot finishes via notify_user, the pill stays visible with a “Finished” status so you can review the log. It’s removed when you start a new Autopilot session or manually stop it.
Settings
Autopilot settings are in the Plugins panel under Autopilot.
| Setting | Description | Default |
|---|
| Enabled | Master switch — disables the Autopilot button when off | On |
| Provider | LLM provider for the routing decisions | Anthropic |
| Model | Which model to use (populated dynamically per provider) | claude-haiku-4-5 |
| API Key | API key for the selected provider | — |
| Debugging | Save router prompts and responses to disk | Off |
Supported Providers
| Provider | Env Var Fallback |
|---|
| Anthropic | ANTHROPIC_API_KEY |
| OpenAI | OPENAI_API_KEY |
| Google | GOOGLE_API_KEY or GEMINI_API_KEY |
| Groq | GROQ_API_KEY |
| OpenRouter | OPENROUTER_API_KEY |
| xAI | XAI_API_KEY |
| Mistral | MISTRAL_API_KEY |
| Cerebras | CEREBRAS_API_KEY |
Debugging
When debugging is enabled, each router consultation is saved to ~/.clideck/autopilot/logs/. Each file contains:
- The system prompt sent to the router
- The user message with workflow state and agent outputs
- The router’s response and tool call
Files are named with a sequence number, label, and timestamp for easy sorting. Useful when you want to understand why Autopilot made a specific routing decision.
Token Usage
Autopilot tracks input and output token counts per project. The total is shown in the Autopilot button tooltip (“Autopilot ON — 45,230 tokens”) and stored in ~/.clideck/autopilot/usage.json.
Data Storage
| Path | Purpose |
|---|
~/.clideck/autopilot/ | Autopilot data directory |
~/.clideck/autopilot/<projectId>.jsonl | Routing history (knowledge base) per project |
~/.clideck/autopilot/usage.json | Cumulative token usage |
~/.clideck/autopilot/logs/ | Debug logs (when debugging enabled) |
