Kode CLI
A terminal-native, multi-model coding agent that orchestrates subagents and expert-model consults across whole workflows.
- Source repo
- shareAI-lab/Kode-CLI
- Stars
- ★ 5.2k
- Last updated
- 4d ago
- License
- Apache-2.0
- Primary language
- TypeScript
- FA score
- 44/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformOpenAI API · Claude APIClaude Code (Partial support)
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- Developers who want each task phase on a different model — o3/GPT-5 for architecture, Qwen Coder or Claude Sonnet 4 for implementation, Grok 4 for hard reasoning
- Not a fit if
- Teams that require strict permission gates by default rather than YOLO-mode execution
- Users who want a single vendor-hosted service instead of configuring their own model endpoints and API keys
- Teams relying on older Q&A-oriented models for long autonomous tasks
- Source review
- 44/100 · Major gaps
What does this agent do, and when should you use it?
Kode is an AI coding assistant that lives in your terminal: it reads a codebase, edits files, runs shell commands, and carries multi-step development tasks to completion. Its distinguishing idea is genuine multi-model collaboration — a ModelManager holds model profiles plus main/task/compact/quick pointers, so the main loop, subagents, context compaction, and small utilities can each use a different model, switched at runtime without losing session context. Mentions like @ask-claude-sonnet-4 route to the AskExpertModel tool for isolated consultation, while @run-agent-architect or the Task tool delegate to subagent templates stored under .kode/agents. Surrounding it are MCP server support (.mcp.json), Agent Skills and a plugin marketplace, AGENTS.md instruction discovery compatible with legacy .claude layouts, and an ACP server mode via kode-acp. It ships as an npm package alongside per-platform native binaries, GitHub Releases single-file executables, and a Docker build; you bring your own model endpoints and keys.
Running kode opens an interactive terminal prompt that completes slash commands, file paths, subagents, configured models, and shell commands. On start it walks instruction files from the Git repo root down to the working directory, preferring AGENTS.override.md over AGENTS.md per directory (one file each) and also reading a legacy CLAUDE.md; discovered files are concatenated root-to-leaf with a 32 KiB cap adjustable via KODE_PROJECT_DOC_MAX_BYTES. Model profiles and pointers are managed through /model or kode models import/export YAML. The @ask-<model> mention invokes the AskExpertModel tool, which runs the expert model out-of-band so its answer doesn't disturb the main conversation, and @run-agent-<type> or Task(subagent_type: ...) hands work to agent templates loaded from .kode/agents and .claude/agents. Tools cover file reads, edits and writes, Bash execution, WebFetch/WebSearch, and MCP servers declared in .mcp.json/.mcprc. /cost reports per-model token usage and spend, kode plugin install pulls skill packs from local paths or GitHub owner/repo marketplaces into SKILL.md-based skills and slash commands, and kode-acp exposes the whole thing as a stdio JSON-RPC ACP agent for clients like Toad and Zed.
- Developers who want each task phase on a different model — o3/GPT-5 for architecture, Qwen Coder or Claude Sonnet 4 for implementation, Grok 4 for hard reasoning
- Teams standardizing coding-agent instructions in AGENTS.md while keeping existing CLAUDE.md and
.claudeconfigs working - Groups that want repeatable procedures packaged as
SKILL.mdskill packs and invoked as slash commands such as/pdfor/xlsx - Users of ACP clients like Zed or Toad who need a local stdio agent backend, launched with
kode-acporkode --acp - Engineers on machines where they prefer a portable single-file binary from GitHub Releases or a Docker container with mounted
~/.kodeconfig - Anyone facing a tricky bug who wants a second, stronger model consulted without polluting the main thread's context
How do you install or deploy this agent?
Install globally from npm; the kode, kwa, and kd commands all become available.
npm install -g @shareai-lab/kodeIf the default registry is slow (notably in China), use a mirror.
npm install -g @shareai-lab/kode --registry=https://registry.npmmirror.comFor the newest features there is a dev channel.
npm install -g @shareai-lab/kode@devPrefer no npm? Download a Bun-compiled single-file binary from GitHub Releases, or build the image from source.
git clone https://github.com/shareAI-lab/Kode-CLI.git
cd Kode
docker build --no-cache -t kode .The container runs as the unprivileged node user, so create the host config paths before mounting them.
cd your-project
docker run -it --rm \
-v "$PWD:/workspace" \
-v "$HOME/.kode:/home/node/.kode" \
-v "$HOME/.kode.json:/home/node/.kode.json" \
-w /workspace \
kodeCaveat: installing with --no-optional omits the per-platform ripgrep package, so supply a system rg or set KODE_RIPGREP_PATH. Nothing is downloaded from GitHub during install.
How do you use this agent?
Configure a model first. Global config lives in ~/.kode.json (or <KODE_CONFIG_DIR>/config.json); set it in the /model UI or import a shared YAML.
version: 1
profiles:
- name: OpenAI Main
provider: openai
modelName: gpt-4o
maxTokens: 8192
contextLength: 128000
apiKey:
fromEnv: OPENAI_API_KEY
pointers:
main: gpt-4o
task: gpt-4o
compact: gpt-4o
quick: gpt-4okode models import kode-models.yaml
kode models listStart an interactive session, or ask a one-shot question with -p. The default is YOLO mode with permission checks bypassed — add --safe when touching important files.
kode
kode -p "explain this function" path/to/file.js
kode --safeUse the mention system in the prompt for expert consults, subagents, and file references.
@ask-claude-sonnet-4 How should I optimize this React component?
@run-agent-architect Design a microservices architecture for this system
@packages/core/src/query/index.tsTo serve other ACP clients, run the ACP entry point:
kode-acp
toad acp "kode-acp"Subagent templates go in ./.kode/agents/reviewer.md and can be checked with kode agents validate.
---
name: reviewer
description: 'Review diffs for correctness, security, and simplicity'
tools: ['Read', 'Grep']
model: inherit
---
Be strict. Point out bugs and risky changes. Prefer small, targeted fixes.What are this agent's strengths and limitations?
- Multi-model orchestration is a first-class design, not a bolt-on: ModelManager profiles plus main/task/compact/quick pointers let the main loop, subagents, compaction, and utilities each use a different model, with runtime switching that keeps context
- The
@ask-<model>expert consult runs through AskExpertModel in isolation, so a second opinion doesn't derail the main conversation - Codex-style AGENTS.md discovery (root-to-cwd walk,
AGENTS.override.mdprecedence, 32 KiB cap, legacyCLAUDE.md) means instruction files carry over from other agent tooling - Broad extension surface in one tool: MCP servers via
.mcp.json/.mcprc,SKILL.mdskill packs, a plugin marketplace, custom output styles, and an ACP server mode - Three real distribution paths — npm with per-platform native binaries, GitHub Releases single-file builds, and a Docker image — and nothing is fetched from GitHub at install time
- No product telemetry by default; network traffic is tied to features you explicitly invoke
- YOLO is the default: permission checks are bypassed unless you pass
--safe, which is unsafe for repos with important files or for weaker models - Heavy toolchain: Node.js and npm to run, Bun to develop, per-platform ripgrep packages (or system
rg) for search, and bubblewrap on Linux if you want the system sandbox - The README warns that older Q&A-oriented models such as GPT-4o or Gemini 2.5 Pro perform poorly on sustained autonomous tasks, so results hinge on picking capable models and endpoints
- Configuration knowledge is spread across many docs files (agents, skills, plugins, output styles, MCP, ACP, binary distribution), raising the first-day learning cost
- You supply every provider endpoint and API key yourself; there is no hosted model or bundled quota
How does this agent compare with similar options?
The README's feature table compares Kode against a generic single-model CLI, contrasting unlimited configurable models, Option+M hot switching, parallel subagents, per-model cost tracking, per-purpose default models, and the AskExpertModel tool. It also credits anonkode for some code, gemini-cli for UI inspiration, and upstream agent CLIs for system design. All of this is the project's own framing, with no third-party benchmarks provided.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Kode CLI This agent | 44 · Major gaps | CLIFree + model costs | ★ 5.2k | 4d ago | TypeScript | OpenAI API · Claude API |
| CoreCoder | 59 · Major gaps | CLIFree + model costs | ★ 1.9k | 1d ago | Python | OpenAI API |
| Whale | 51 · Major gaps | CLIFree + model costs | ★ 933 | 6d ago | Go | — |
| Lime - Full-Stack Desktop AI Agent | 44 · Major gaps | Desktop appFree + model costs | ★ 1.5k | today | TypeScript | — |
How does FollowAgents rate this agent?
Why each dimension lost points
README explicitly states Kode runs in YOLO mode by default (equivalent to --dangerously-skip-permissions), bypassing all permission checks, recommended only for trusted environments, with --safe and Linux bwrap sandbox as mitigations; but default is maximum privilege, so least_privilege and user_confirmation score 1. The Network & Privacy section states no telemetry by default and network requests only on explicit networked features, giving data_flow_transparency 2; however data flows for model requests, MCP/plugin downloads are not itemized. For sensitive data, config docs recommend env vars for secrets and YAML export omits plaintext keys by default, but example configs still show plaintext apiKey fields and there is no at-rest encryption guidance, scoring 1. Dependency security has bun audit --audit-level=high in CI and check script, pinned action commits and frozen-lockfile, scoring 2; but no SBOM or vulnerability remediation record. External effects: command execution, file writes, plugin installs have no confirmation by default, scoring 1. Rollback: config save has backup and restore on failure, but file edits/command execution have no general undo, scoring 1. Source attribution: LICENSE has copyright, package.json has author and provenance:true, but publisher identity is unverified by FollowAgents and third-party skills only referenced via THIRD_PARTY_NOTICES, scoring 1.
self_consistency scores 1: README and docs are broadly consistent on default permission mode and sandbox dependencies (bwrap+socat), but the Docker example uses cd Kode while the repo is Kode-CLI, and some feature claims (e.g., multi-model collaboration) lack corresponding code evidence. dependency_availability scores 2: engines specify node>=20.18.1, optionalDependencies cover multi-platform binaries and ripgrep with documented --no-optional fallback, and CI verifies three platforms. failure_messages scores 1: ACP contract tests verify parameter validation error codes and messages (e.g., Missing required param: cwd), but overall error handling and user-facing failure messaging evidence is limited in the provided files.
audience_and_scenarios scores 2: README covers interactive/non-interactive, ACP, Docker, multi-model, subagents, skills/plugins for terminal developers. capability_boundaries scores 1: docs describe tools, permission modes and sandbox boundaries, but do not systematically list agent capability limits and unsuitable scenarios. trigger_precision scores 1: @ mentions, slash commands, # doc mode are described, but precise trigger conditions and conflict handling are missing. environment_fit scores 2: cross-platform install, mirror registry, Windows limitations, Linux sandbox dependencies are documented.
information_architecture scores 2: README is well structured and docs are organized by topic. install_notes scores 2: npm install, mirror, optional deps, standalone binaries, Docker are documented. naming_stability scores 1: command aliases kode/kwa/kd coexist with package name, and .kode vs .claude dual naming compatibility, stability evidence insufficient. examples_and_faq scores 2: many command examples and troubleshooting. known_limitations scores 1: only scattered mentions (Windows no system sandbox, optional seccomp), not centralized. license scores 3: full Apache-2.0 text with copyright. versioning_changelog scores 1: README has an update log snippet and semver release flow, but no full CHANGELOG. maintenance_responsibility scores 1: CI and release workflows exist, but publisher identity is unverified and maintenance ownership is unclear.
output_usability scores 1: CLI output is terminal-oriented, but provided files do not show output format or usability evidence. marginal_value scores 1: feature-rich but many similar terminal coding agents exist; differentiation evidence is mainly README self-description. cost_benefit scores 1: /cost and multi-model cost tracking are described, but no actual cost data or benchmarks.
claim_traceability scores 1: many README feature claims are not linked to specific code or tests. cross_source_corroboration scores 1: some claims (sandbox, config paths) are cross-corroborated in docs and tests, but most feature claims appear only in README. fact_inference_separation scores 1: docs mix factual descriptions with marketing phrasing (e.g., true multi-model collaboration) without clear separation.
- Runs in YOLO mode by default bypassing all permission checks; use only in trusted environments and explicitly use kode --safe for important files.
- Publisher identity is not verified by FollowAgents; verify the npm package and GitHub release source before installing.
- Linux system sandbox depends on bwrap and socat and degrades when missing; Windows has no equivalent system sandbox.
- Plugins and MCP servers can be downloaded from GitHub/URL and executed, posing supply-chain risk; review sources.
- Example configs show plaintext apiKey fields; use environment variables in practice.
FAQ
Will it run commands without asking?
--dangerously-skip-permissions) and recommends it only for trusted environments and non-critical projects. Use kode --safe to require approval for Bash commands and file writes/edits; plan mode further restricts the agent to read-only and planning tools.Who pays for the model usage?
/cost reports token usage and spend per model, and kode models export omits plaintext API keys by default so you can reference them via fromEnv environment variables.What leaves my machine?
bwrap sandbox with networking disabled unless KODE_SYSTEM_SANDBOX_NETWORK=inherit.How does AGENTS.md discovery actually work?
AGENTS.override.md to AGENTS.md; discovered files are concatenated root-to-leaf with a 32 KiB default cap overridable by KODE_PROJECT_DOC_MAX_BYTES. Prompts prefixed with # format the answer as documentation appended to AGENTS.md.Which runtimes and platforms are supported?
bwrap sandbox is optional — set KODE_SYSTEM_SANDBOX=0 to disable it or required to fail closed when it can't start.