keelcode

Keelcode is a hosted coding agent for your terminal. It can inspect a project, edit files, run commands, search the web, use MCP servers, and verify its work.

Install

The quickest way downloads the native binary directly — no package manager, no Node, no Bun:

# macOS / Linux
curl -fsSL https://keelcode.ai/install.sh | sh

# Windows (PowerShell)
irm https://keelcode.ai/install.ps1 | iex

The installer verifies the download's checksum, installs under ~/.keelcode, and adds Keelcode to your PATH (pass --no-modify-path to skip that and get instructions instead).

Or install with any package manager. The command runs under Node 18+, which every one of these managers already provides — including on Windows:

npm  install --global @keelcode-ai/keelcode
pnpm add     --global @keelcode-ai/keelcode
yarn global  add      @keelcode-ai/keelcode
bun  add     --global @keelcode-ai/keelcode

On a machine that has Bun but no Node, use the curl | sh / install.ps1 script above instead — it installs a self-contained binary that needs no runtime at all.

If a package-manager install reports command not found, that manager's global bin directory isn't on your PATH. Print it with npm bin -g (or bun pm bin -g) and add it to your shell profile — or just use the curl installer, which handles PATH for you.

The package provides four equivalent commands:

keelcode
kc
kcode
keel

Staying current

Keelcode keeps itself up to date. At most once every six hours it checks the registry in the background; installs made with the curl/PowerShell script download the new version silently and switch to it on the next launch, while package-manager installs show a one-line notice on the startup screen instead — their node_modules tree belongs to the package manager, so Keelcode never writes into it behind the manager's back.

keelcode update           # update now, in the foreground
keelcode update --check   # just report whether a newer version exists

To opt out, set "autoUpdate": false in ~/.keelcode/settings.json, or export KEELCODE_AUTO_UPDATE=0. CI environments are skipped automatically.

To add your own command name after installation, run the guided setup or add one or more aliases directly:

keelcode alias setup
keelcode alias add mycode kk
keelcode alias list
keelcode alias remove kk

Custom aliases are created beside the package-manager shims. Keelcode refuses to overwrite an existing command and never edits shell startup files. Package installation stays non-interactive so it remains reliable in terminals, CI, containers, and package managers that disable lifecycle scripts.

Fonts are never downloaded and terminal settings are never edited during installation or normal startup. Keelcode defaults to font-independent Unicode, and falls back to ASCII for clearly limited terminals. Rich Nerd Font icons are an optional upgrade through keelcode setup; a failed or skipped setup keeps the safe icon set enabled.

The @keelcode-ai/keelcode npm package is a small launcher that installs the matching platform-suffixed version of that same package name for the current operating system, CPU, and Linux libc. Keelcode's application JavaScript, TypeScript, source maps, tests, and build configuration are not included in the public package.

Sign in and start

keelcode login
keelcode

If the machine cannot open a browser:

keelcode login --no-browser

Keelcode will also start sign-in automatically when an interactive session has no usable account. Authentication uses a short-lived device approval; provider credentials are never stored in the CLI.

Useful account commands:

keelcode whoami
keelcode usage
keelcode logout

Everyday use

Start in the current project:

keelcode

Run one prompt without opening the TUI:

keelcode -p "find and fix the failing test"
git diff | keelcode -p "review this diff"

Resume work:

keelcode -c
keelcode sessions
keelcode --resume 2

Choose a model at launch:

keelcode --model <model-alias>

Inside the TUI, use /models to open the current model picker and /usage to see the remaining hosted allowance. Run /help for the complete command list. The footer reports client-observed ttft and tps for the latest model turn. TTFT includes network and gateway latency; TPS uses provider-reported output tokens and excludes tool execution. A dash is shown when the stream does not contain enough timing or usage information for an honest measurement.

Measure local launcher startup:

keelcode bench
keelcode bench --json

The benchmark runs the installed launcher repeatedly, reports median/p90/min/max latency, and is useful for comparing terminals, package managers, and releases.

Common options

-m, --model <alias>        choose a Keelcode model
    --permission-mode <m>  default | plan | acceptEdits | bypassPermissions
    --yolo                 bypass permission prompts in trusted environments
    --cwd <dir>            set the working directory
    --icons <set>          unicode | nerd | ascii | auto
    --no-alt-screen        keep output in the main terminal buffer
-c, --continue             resume the newest session in this directory
    --resume [id]          resume by id/index; no argument lists sessions
-p, --print [prompt]       run one headless prompt
    --output-format <f>    text | json | jsonl
-h, --help                 show help
-v, --version              show the installed version

bypassPermissions and --yolo remove confirmation prompts for operations inside the workspace. Crossing the workspace boundary still requires explicit approval and fails closed in headless mode.

Configuration

Settings merge in this order, with later files winning:

1. ~/.keelcode/settings.json
2. <project>/.keelcode/settings.json and settings.local.json (sanitized, capability-reducing fields only)
3. trusted per-project overrides under ~/.keelcode/projects/<workspace-hash>/
4. command-line flags

Example project configuration:

{
  "model": "<model-alias>",
  "permissionMode": "default",
  "maxTurns": 100,
  "timeoutMs": 600000,
  "permissions": {
    "ask": ["Bash", "Write", "Edit"],
    "deny": ["Write(/etc/**)"]
  }
}

Committed or in-tree settings cannot enable MCP processes, inject environment variables, add allow rules, select acceptEdits/bypassPermissions, or define unknown future capabilities. Explicit per-project choices made through the CLI are stored outside the repository. Keelcode does not support bring-your-own-provider keys.

MCP and skills

Inspect extension health:

keelcode doctor
keelcode mcp list
keelcode skills list
keelcode import list

Use keelcode mcp --help and keelcode skills --help for management commands. MCP tools pass through the same permission checks as built-in tools.

Automation

For scripts and CI, prefer structured headless output:

keelcode -p "run the tests and summarize failures" --output-format json
keelcode -p "review this repository" --output-format jsonl

Human progress is written to stderr. Machine-readable results are written to stdout, so redirecting stdout does not mix logs into the protocol. Model performance is written to stderr in text mode and included as structured performance data in JSON/JSONL output.

Local data and privacy

Keelcode stores account sessions, settings, conversations, caches, and local receipts under ~/.keelcode. Sensitive state uses owner-only permissions on supported POSIX systems.

Anonymous product analytics are opt-in and can be controlled at any time:

keelcode telemetry status
keelcode telemetry enable
keelcode telemetry disable

Do not paste production secrets into prompts or commit .keelcode personal state to a repository.

Security

Report suspected vulnerabilities privately to [email protected]. Do not include real credentials or unrelated private data in a report.

License

Keelcode is proprietary software. Installation and use are governed by the license included with this package and the applicable Keelcode service terms.