# 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: ```bash # macOS / Linux curl -fsSL https://keelcode.ai/install.sh | sh ``` ```powershell # 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: ```bash 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: ```text 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. ```bash 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: ```bash 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 ```bash keelcode login keelcode ``` If the machine cannot open a browser: ```bash 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: ```bash keelcode whoami keelcode usage keelcode logout ``` ## Everyday use Start in the current project: ```bash keelcode ``` Run one prompt without opening the TUI: ```bash keelcode -p "find and fix the failing test" git diff | keelcode -p "review this diff" ``` Resume work: ```bash keelcode -c keelcode sessions keelcode --resume 2 ``` Choose a model at launch: ```bash keelcode --model ``` 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: ```bash 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 ```text -m, --model choose a Keelcode model --permission-mode default | plan | acceptEdits | bypassPermissions --yolo bypass permission prompts in trusted environments --cwd set the working directory --icons 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 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. `/.keelcode/settings.json` and `settings.local.json` (sanitized, capability-reducing fields only) 3. trusted per-project overrides under `~/.keelcode/projects//` 4. command-line flags Example project configuration: ```json { "model": "", "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: ```bash 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: ```bash 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: ```bash 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 `security@keelcode.ai`. 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.