KitPilot

A model-agnostic CLI AI coding agent. Bring your own key across providers, or borrow GitHub Copilot from a running VS Code window. Self-contained — the published package bundles everything, so install is dependency-free.

npm install -g @kitpilot/cli

Then run kit.

Quickstart

Set a key for the provider you want and go:

export ANTHROPIC_API_KEY=...        # or GEMINI_API_KEY / OPENAI_API_KEY / OPENROUTER_API_KEY
kit "create a hello.txt with the word hi, then read it back"

Or just run kit with no arguments: on first use it shows a connect picker (Anthropic / OpenAI / Gemini / OpenRouter / Ollama / GitHub Copilot) and remembers your choice. It then opens the interactive session (banner + prompt loop, multi-turn). Commands: /help, /clear, /mode, /resume, /sessions, /status, /exit. Re-open the picker anytime with kit --login.

Resume the last conversation in a folder with kit --resume.

Durable tasks and verification

Each task gets a durable record in .kitpilot/tasks/ with its requested outcome, changed files, and validation evidence. When a task edits the workspace, KitPilot requires a successful validation command (tests, lint, typecheck, build, or git diff --check) before it accepts completion. Resume an unfinished task with kit --resume "continue"; inspect recent task records with kit --status (or /status in the interactive session).

For longer autonomous work, use an isolated git worktree:

kit --worktree --yes "fix the failing tests"
kit --status
kit --apply <task-id>

The source checkout must be clean so the isolated branch starts from an exact revision. KitPilot runs and validates inside the worktree, commits the result to a kitpilot/task-* branch, and prints review/apply instructions. Applying is a separate explicit cherry-pick; conflicts are aborted without leaving the source checkout in a partial cherry-pick state. Worktree mode currently targets headless runs; unfinished isolated sessions resume with kit --resume "continue".

Providers & models

Pick with --provider (and optionally --model):

| Provider | Key | Default model | |---|---|---| | anthropic | ANTHROPIC_API_KEY | claude-opus-4-8 | | gemini | GEMINI_API_KEY | gemini-3.5-flash | | openai | OPENAI_API_KEY | gpt-5.5 | | openrouter | OPENROUTER_API_KEY | anthropic/claude-sonnet-4.5 | | ollama | (none — local) | llama3.1 |

kit --provider gemini "summarize this repo"
kit --provider openai --model gpt-5.4-mini "..."
kit --provider ollama --model qwen2.5-coder "..."   # any model you've pulled

Config

Set defaults in ~/.config/kitpilot/config.json (honors XDG_CONFIG_HOME):

{ "apiProvider": "gemini", "modelId": "gemini-3.5-flash" }

Precedence: built-in defaults < config file < KITPILOT_* env < CLI flags.

Parallel read-only research

For tasks with two or more independent investigation scopes, the supervisor can call parallel_research and wait for a bounded set of worker findings before it edits anything. This capability is enabled by default in code, architect, and ask modes.

Research workers are deliberately narrower than normal sub-tasks:

• only read_file, list_files, search_files, and codebase_search are available;
• shell commands, edits, web/MCP tools, user prompts, delegation, and mode switching are unavailable;
• each worker has an iteration limit and a hard wall-clock timeout; and
• completions need citations such as packages/api/src/client.ts:42-58. KitPilot verifies that every cited file and line range exists before passing the finding to the parent. The parent is still responsible for reconciling interpretations and conflicts.

Concurrency defaults are conservative: 2 through the VS Code/Copilot bridge, 3 for remote BYOK providers, and 1 for local Ollama. Every path is hard-capped at 4. Override or disable it with:

{
  "research": {
    "enabled": true,
    "concurrency": 2,
    "maxWorkers": 4,
    "maxIterations": 10,
    "timeoutMs": 180000
  }
}

The matching flags are --research, --no-research, and --research-concurrency <n>. Environment controls are KITPILOT_RESEARCH, KITPILOT_RESEARCH_CONCURRENCY, KITPILOT_RESEARCH_MAX_WORKERS, KITPILOT_RESEARCH_MAX_ITERATIONS, and KITPILOT_RESEARCH_TIMEOUT_MS.

With Copilot, managed workers require bridge extension 0.4.2 or newer (IPC protocol v2). Cancellation propagates to VS Code's CancellationToken, and a quota, permission, or missing-model failure stops queued workers instead of creating a retry storm. Ordinary non-worker bridge calls remain compatible with older extensions.

Native read-only tool scheduling

When a native-tool provider returns several calls in one assistant turn, KitPilot may run a contiguous batch of independent repository reads in parallel. The policy is host-authored and deliberately narrow:

• only read_file, list_files, search_files, and codebase_search are marked read_only and eligible to overlap;
• edits, commands, network/user approvals, process state, delegation, mode switches, and completion checks are ordering barriers;
• unclassified custom and MCP tools are exclusive by default; and
• results and lifecycle events are committed in the model's original call order, even when reads finish out of order.

Concurrency defaults to 4 and is hard-capped at 4. Set nativeToolConcurrency in config.json, pass --native-tool-concurrency <1-4>, or use KITPILOT_NATIVE_TOOL_CONCURRENCY. A value of 1 retains native tool schemas but serializes their execution.

Cancellation stops queued reads and records explicit error results for every unanswered tool_use id before checkpointing. This preserves any earlier side effect from the same turn without leaving an invalid transcript.

The VS Code LM bridge remains on the text/XML tool protocol and therefore continues executing one tool per model turn. Native VS Code LM tool calling is a separate future protocol change; this scheduler does not alter IPC or bridge cancellation behavior.

Isolated editing delegation

delegate_edit gives a single, self-contained implementation to an editing worker in a new branch-backed git worktree. It is off by default — each worker is a full model-driven task with real token cost, so enable it deliberately with --edit-delegation, KITPILOT_EDIT_DELEGATION=1, or "editingDelegation": { "enabled": true } in config. The host—not the model—owns its lifecycle:

1. The supervisor supplies literal relative scope paths, objective acceptance criteria, and any exact validation commands.
2. The worker receives local read/search/edit/command tools only. It cannot use MCP/web tools, ask the user, delegate again, switch modes, or touch the parent checkout.
3. The host rejects out-of-scope changes and completion without successful post-edit validation, then commits the accepted child worktree for review.
4. review_delegated_edit verifies the finalized commit is unchanged and returns its complete diff plus a SHA-256 review token bound to that commit.
5. The supervisor must call either apply_delegated_edit with the token and a concrete risk assessment, or reject_delegated_edit with the token and a reason. A task cannot complete while a delegation remains running, ready, or reviewed.

Apply is deliberately strict: the parent must still be clean and at the exact revision the child validated. The reviewed patch is applied as uncommitted, unstaged changes, so checkpoints, later edits, and the parent completion gate continue to work normally. Interactive runs show a merge approval diff; headless runs require --yes for this final merge. A ready result never mutates the parent on its own.

Failed or cancelled workers retain their transcript and dirty worktree and can be continued with resume_delegated_edit. A filesystem lease prevents two processes from resuming the same editor. Finalized/rejected worktrees are kept for audit and manual cleanup. Diffs above 120 KB receive no automated review token because the model could not inspect them completely; use the returned child task id with kit --status <id> and the existing explicit worktree review workflow instead.

The source checkout must be a git repository without user changes. Untracked KitPilot runtime state under .kitpilot/tasks, sessions, checkpoints, delegations, and leases does not falsely dirty the repository, while tracked changes at those paths still block isolation.

Configure limits in config.json:

{
  "editingDelegation": {
    "enabled": true,
    "maxIterations": 40,
    "timeoutMs": 900000
  }
}

Use --edit-delegation / --no-edit-delegation, or the environment variables KITPILOT_EDIT_DELEGATION, KITPILOT_EDIT_WORKER_MAX_ITERATIONS, and KITPILOT_EDIT_WORKER_TIMEOUT_MS.

Tools

In its working directory (--cwd to change it) the agent can: read_file, write_file, apply_diff (surgical edits with a diff preview), list_files, search_files, codebase_search (ranked), execute_command (destructive commands ask first), ask_followup_question, update_todo_list, and new_task (read-only sub-tasks), bounded parallel_research, and — when editing delegation is enabled — the isolated editing delegation review/apply tools. Tools from configured MCP servers are added automatically.

Modes: code (default), architect and ask (read-only). Set with --mode, or /mode in the session; the model can switch_mode itself.

MCP: add servers under mcpServers in the config file (Claude-Desktop shape).

Copilot mode (optional)

vscode.lm only exists inside VS Code, so KitPilot borrows Copilot from a running editor session over a local socket. Easiest path: run kit, pick GitHub Copilot in the connect picker — it opens VS Code in a folder you choose, offers to install the bridge extension, and waits for the bridge before connecting. Or, with the extension already running, use kit --copilot "…" from the same workspace folder. Pick a specific model via copilotBridge.selector (e.g. { "vendor": "copilot", "family": "gpt-4o" }).

License

Apache-2.0. KitPilot is a derivative work of Roo Code (itself derived from Cline); see NOTICE.