KitCode

English · Русский

  ╱\_╱\
 ( o.o )
  > ^ <

KitCode is a terminal coding agent. It reads and edits files, searches a project, runs commands, connects external tools through MCP, and keeps persistent session history.

The interface is built with TypeScript, React, and Ink. KitCode supports the Anthropic API and OpenAI-compatible providers, including OpenRouter and local model servers.

Features

• streaming responses with reasoning output;
• file reading, creation, and targeted editing;
• filename and content search;
• shell commands with approval prompts;
• normal, accept, and plan modes;
• persistent and resumable sessions with native terminal scrollback;
• searchable session management with rename, delete, and Markdown export;
• input history with the ↑ and ↓ keys;
• queued messages while the agent is working, with status and settings commands running immediately;
• image and UTF-8 text attachments;
• manual and automatic context compaction with a selectable context window;
• token, estimated cost, exact context-window, and provider rate-limit indicators;
• automatic file checkpoints with /undo;
• detected project checks after file edits;
• model and provider switching from the TUI;
• live MCP add, enable, disable, and delete operations, plus skills and subagents running concurrently;
• a local /checker report for the runtime, provider, session, context, and MCP setup;
• English and Russian interfaces with configurable accents.

Requirements

• Node.js 22 or newer;
• npm.

Install

npm i -g @kernelonpanic/kitcode

Install from source

git clone https://github.com/KernelEditor/KitCode.git
cd KitCode
npm install
npm run build
npm link

After npm link, the kitcode command is available globally. To run without a global link:

npm run dev

First run

kitcode

On first launch, KitCode asks for the interface language, an API base URL, and an API key. It then detects the provider type, loads the available models, and opens the main agent view.

Common base URLs:

https://api.anthropic.com
https://openrouter.ai/api/v1
http://localhost:11434/v1

Command line

Command	Purpose
kitcode	Start the TUI in the current directory.
kitcode -c	Continue the latest session for this project.
kitcode -r <id>	Resume a session by id.
kitcode --cwd <path>	Use another working directory.
kitcode --model <provider/model>	Start with a selected model.
kitcode --mode <normal|accept|plan>	Select the initial agent mode.
kitcode sessions	List saved sessions.
kitcode ask "question"	Run one request without the TUI.
kitcode add <url>	Add a provider; the key is entered in a hidden prompt.
kitcode add <url> --key-env <name>	Read the provider key from an environment variable.
kitcode trust	Enable this workspace's project config and skills.
kitcode config	Show the config and key locations.
kitcode config --local	Create a project config at ./kitcode.json.
kitcode prompt list	List saved prompts.
kitcode prompt rm <slug>	Delete a saved prompt.

TUI commands

Press / to open the command list.

Command	Purpose
/model [model]	Select a model; a full or unambiguous partial id skips the list.
/provider	Switch providers.
/login · /logout [provider]	Add a provider or choose exactly which provider to remove.
/key [provider]	Change API key for a provider.
/refresh [provider]	Reload a provider's model list, bypassing the 24h cache.
/effort [auto|low|medium|high|xhigh|max] · /thinking	Select reasoning effort and configure reasoning output.
/bell [on|off]	Toggle the beep when a long answer finishes or a permission prompt appears.
/context [tokens]	Show or set the model context window used by the meter and automatic compaction.
/memory show · /memory set <text> · /memory clear	View, replace, or clear this project's persistent notes.
/resume · /clear	Resume a session or start a new one.
/sessions	Search sessions, then resume, rename, delete, or export one.
/sessions list	List all saved sessions.
/sessions rename [id] <title>	Give a saved session a title.
/sessions delete <id>	Delete a saved session.
/sessions delete all	Delete every saved chat after two separate confirmations.
/sessions export [id] [path]	Export a session to a private Markdown file (default: .kitcode-exports/).
/attach <path> · /attach clipboard · /attach clear	Manage attachments for the next message; type @ in the prompt to find and attach a workspace file.
/compact	Replace older conversation context with a concise model-generated summary.
/update	Check npm for a newer KitCode version.
/subagents	Show the current number of active sub-agents.
/undo	Undo built-in file edits from the latest message.
/usage	Show tokens, requests, cost, balance/key limits, and response rate-limit headers when available.
/checker	Check the local setup and provider model listing without sending a paid chat request.
/prompt [name]	Insert a saved prompt.
/prompt save [name]	Save the latest message as a prompt, or pick a recent one and name it. Asks before replacing.
/prompt delete [name]	Delete a saved prompt.
/skills	Show discovered skills.
/skills install <source>	Install a skill from a GitHub URL, an npm package, or a local folder.
/skills remove [name]	Remove an installed global skill.
/mcp add <name> [-H "Name: value"] <https://url>	Add and connect a remote MCP server.
/mcp add <name> [-e KEY=value] -- <command> [args]	Add and connect a local MCP server.
/mcp list	Show configured MCP servers and connection status.
/mcp enable <name> · /mcp disable <name>	Connect or disconnect an MCP server without removing it.
/mcp delete <name>	Disconnect and remove an MCP server.
/theme [color] · /lang [en|ru]	Change the accent or interface language.
/config	Show the active config.
/bypass	Toggle approval-free operation.
/help · /exit	Show help or quit.

Keyboard shortcuts

Key	Action
Enter	Send a message or choose an item.
↑ / ↓	Browse input history or menu items.
Tab	Complete a slash command or selected @ file.
Shift+Tab	Cycle normal → accept → plan.
Ctrl+V / Cmd+V	Attach an image from the system clipboard; /attach clipboard is the explicit fallback.
Esc	Cancel the current request or close an overlay.

Messages entered while the agent is running are queued and processed in order; they are listed above the input, and ↑/↓ on an empty input pick one to edit. Status and settings commands — /help, /usage, /context, /model, /effort, /thinking, /bell, /budget, /theme, /lang, /subagents, /config, /checker, /exit — run immediately instead. Commands that change the running turn or the session (/clear, /compact, /resume, /undo, /login, /provider, /logout, /key, /refresh, /mcp, /sessions) wait for the turn to finish.

Modes

• normal — file changes, shell commands, and MCP calls request approval when needed;
• accept — file edits are accepted automatically;
• plan — the agent explores the project and returns a plan without changing files.

The lower status panel shows the active mode, model, and usage. A left-to-right context capsule stays on the right, changing from green to yellow at 60% and red at 85%, with the connected MCP count below it. ctx ? means the provider has not returned exact usage for the current model yet. Completed output is committed to normal terminal scrollback, so it remains smooth to scroll while a response is streaming.

When exact usage reaches 80% of a known context window, KitCode automatically summarizes older turns while keeping the latest two user turns. /compact runs the same operation manually, and /context sets the window when the provider does not report one.

Context window

/context shows the window currently in use and opens a picker with the common sizes — 256k, 512k, 1M — plus auto. The argument form accepts the same values and any explicit token count:

/context 256k
/context 1m
/context 400000
/context auto

The value is stored in the config as contextWindow and survives restarts. A manual value outranks whatever the provider catalogue reports, so a gateway that understates its window does not distort the meter. It feeds both the status-bar capsule and the 80% threshold for automatic compaction. auto returns to the provider's number; when the provider reports none, the meter shows ctx ? and automatic compaction stays off, because it needs a known window to decide anything.

Before the built-in write and edit tools change a file, KitCode creates a private checkpoint. /undo restores the latest checkpoint and leaves files with newer manual changes untouched. After a message changes files, KitCode detects common project checks such as lint, typecheck, and test. The exact commands are shown for approval before they run.

Reasoning effort

Use /effort to open the picker or /effort high to choose a level directly. The command shows both the selected level and the value KitCode will send to the API for the current conversation. This confirms request encoding, not whether a gateway honors the parameter.

auto uses medium for short general requests and high for long requests or messages containing coding-task keywords. It is a local heuristic, not a model-based difficulty assessment. Manual levels bypass this heuristic. For the original GPT-5, GPT-5.1 and o-series, KitCode maps xhigh and max to high; for GPT-5.2–5.4, it maps max to xhigh. It omits effort for unrecognized OpenAI-compatible model names. The Anthropic adapter sends the resolved level in output_config. Supported levels and their effect depend on the model and provider.

Project memory

Project notes persist across chats, /clear, and restarts. Manage them with:

/memory show
/memory set Run npm test before committing. Put changelogs only in GitHub Releases.
/memory clear

set replaces the whole note; clear asks for confirmation. Notes are limited to 16,000 characters and stored under ~/.kitcode/memory/, separately for each canonical workspace path.

The agent can also use the memory tool to read, add, replace, or delete notes. Mutations require a source, such as a user instruction or file/tool evidence. Updates appear in the tool transcript with a diff. Exact-match replacement and deletion help avoid overwriting unrelated notes. The tool is allowed by default in normal and accept modes; set permissions.memory to ask or deny to restrict it. Plan mode blocks the tool, including its read action.

The agent is instructed to retain confirmed project facts, explicit preferences and accepted decisions, and to verify potentially stale notes against current files. Temporary progress belongs in the conversation. Secret-pattern redaction is best effort; do not put credentials in memory. Context compaction separately asks the model to preserve requirements, evidence, verification commands and outcomes, assumptions, and remaining work. Generated summaries can still omit details.

Subagents

The task tool hands one self-contained sub-task to a subagent that works in its own fresh context and reports back a single summary. Subagents share the filesystem and working directory but have no memory of the conversation and cannot ask questions, so the prompt has to stand alone.

Consecutive task calls in one model response run concurrently, and there is no fixed cap on how many: five or ten start together. Each subagent gets its own execution lane, so their tool calls and model requests overlap instead of queueing. Two things stay deliberately serialized: approval prompts, because the interface shows one at a time, and the per-message budget, which the whole turn shares. The live box lists up to three running subagents and collapses the rest into a count; /subagents prints every active task with its latest progress.

Configuration

KitCode uses these main paths:

Path	Contents
~/.kitcode/config.json	Global settings.
~/.kitcode/auth.json	Provider keys.
~/.kitcode/sessions/	Saved sessions.
~/.kitcode/checkpoints/	Automatic file checkpoints used by /undo.
~/.kitcode/prompts/	Saved prompts.
~/.kitcode/skills/	Global skills.
./.kitcode/skills/	Project skills.
./kitcode.json	Project-local config.

Minimal manual provider configuration:

{
  "version": 1,
  "model": "openrouter/openai/gpt-5",
  "providers": {
    "openrouter": {
      "type": "openai",
      "baseUrl": "https://openrouter.ai/api/v1",
      "keyEnv": "OPENROUTER_API_KEY"
    }
  }
}

The main settings are model, effort, thinking, contextWindow, maxTokens, budget, diagnostics, theme, permissions, providers, and mcp. budget controls local per-message safety limits for model requests, tokens, estimated cost (when model pricing is available), and subagents. These values are not the provider's account balance or rate limits. diagnostics.autoRun enables checks after file edits; diagnostics.commands can replace automatic detection with up to eight explicit commands. KitCode checks npm for a newer version on every app start and prints the upgrade command when one is available. /update repeats the check manually. Manual editing is usually unnecessary: add a provider during onboarding or with /login.

Project settings and project skills are enabled after reviewing the workspace and running:

kitcode trust

Run kitcode trust --revoke to return to global settings and skills for that workspace.

MCP and skills

MCP supports local stdio servers and remote HTTP servers. Add one from the TUI and it connects immediately without a restart:

/mcp add docs https://mcp.example.com/mcp
/mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem "C:\My Projects"
/mcp add github -e GITHUB_TOKEN=${env:GITHUB_TOKEN} -- npx -y @modelcontextprotocol/server-github
/mcp add search -H "Authorization: Bearer ${env:SEARCH_TOKEN}" https://mcp.example.com/mcp
/mcp list
/mcp disable filesystem
/mcp enable filesystem
/mcp delete filesystem

Quotes keep spaces in paths and values. -e sets environment variables for a local server and -H sets headers for a remote one; both go before the URL or command. The server is saved to the active config. Use ${env:NAME} references for secrets, on the command line or in the config, so the secret itself never lands in the config file:

{
  "mcp": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${env:GITHUB_TOKEN}"
      }
    }
  }
}

A skill is a directory containing a SKILL.md file, plus any scripts or reference files it uses. Global skills live in ~/.kitcode/skills; project skills live in ./.kitcode/skills. Install one without leaving the TUI:

/skills install https://github.com/anthropics/skills/tree/main/skills/pdf
/skills install @scope/some-skill
/skills install ./my-skill
/skills remove pdf

The whole skill folder is copied (symlinks are skipped). A link to a repository with several skills lists them so you can pick one by its path.

Attachments support PNG, JPEG, GIF, and WebP images up to 10 MB, plus UTF-8 (or UTF-16) text files up to 256 KB. Pasting or dragging a standalone existing path queues it automatically and displays a chip below the prompt. File contents are sent only when the attachment is submitted with a message. Large or very tall images are scaled down to fit the API limits.

Writing @path/to/file in a message sends that workspace file along with it. Mentions never reach outside the workspace and never pick up credentials (.env, keys, ~/.ssh): attach those explicitly with /attach if you really mean to. If the model refuses an image (for example, it has no vision), the image is removed from the conversation so the next message still goes through.

Development

npm run dev        # run the TypeScript entry point through tsx
npm run build      # build dist/index.js
npm run typecheck  # check TypeScript
npm test           # run the test suite

Project layout:

src/app/        application startup and runtime
src/core/       agent loop, sessions, and usage
src/providers/  Anthropic and OpenAI-compatible adapters
src/tools/      file, shell, and utility tools
src/mcp/        MCP client and tool bridge
src/ui/         Ink TUI
test/           Vitest tests

License

MIT