Kana

A lightweight, untracked, and deeply personal terminal AI companion.
Instant single binary, zero telemetry. Transparent pairing ends black-box waiting, durable memory stops the amnesia loop, and reusable templates and subagents evolve alongside your workflow.

English · 简体中文

Kana is an open-source, single-binary, terminal-native AI agent built for coding, system workflows, and tool-driven productivity. From a focused interactive TUI that keeps reasoning, diffs, and execution in flow, to headless kana exec powering scripts and CI pipelines, it delivers a razor-sharp runtime with instant cold starts.

Unlike rigid black-box runners, Kana is a companion that evolves alongside you:

• Transparent pairing & shared growth: Break away from opaque spinners and passive waiting. With streamed reasoning, syntax-highlighted diffs, and visible traces, Kana doesn't just divide parallel work with you—it demystifies complex problems, helping you master system nuances and grow as you build together;
• Durable memory, built-in intuition: Put an end to the frustrating amnesia loop where every new session starts from scratch. Powered by a two-tier local memory architecture, Kana distills your architectural rules, habits, and past edge cases—turning every past correction into lasting intuition;
• Self-evolving capability: It doesn't just execute instructions—Kana can turn recurring workflows into reusable :prompt templates and author dedicated Subagent role cards as your needs evolve. The more you use it, the more it shapes itself into your personal toolkit.

Sovereign, private, and untracked. Kana sends no telemetry. During normal agent execution, network access is strictly limited to your configured model providers and MCP servers; explicit features such as updates, authentication, or installs access only their respective services. Your configs, sessions, memory, artifacts, and logs stay strictly on your machine.

Quick start

Single binary with zero runtime dependencies—no Node.js or Python required. Prebuilt for macOS and Linux on arm64 and x64:

curl -fsSL https://raw.githubusercontent.com/longyijdos/kana/main/scripts/install.sh | bash

1. Launch with DeepSeek (Default)

No account registration needed. Just export your API key and launch Kana inside any project directory:

export DEEPSEEK_API_KEY="sk-..."
cd your-project
kana

2. Or connect OpenAI Codex

Authenticate seamlessly through your browser:

kana auth login openai-codex

Set it in ~/.kana/config.toml, or switch directly inside the TUI anytime using /model:

[agent.model]
provider = "openai-codex"
name = "gpt-5.6-sol"

Once inside, switch providers, models, or reasoning efforts on the fly with /model. For local endpoints (Ollama, vLLM) or hosted gateways, connect via the Custom OpenAI-compatible provider.

Why Kana

Use Kana

1. Interactive pairing in the TUI

Once your model is ready, launch Kana inside any project directory:

kana                          # Start an empty pairing session
kana "diagnose failing tests" # Launch directly with an initial task
kana resume                   # Interactively resume or prune saved sessions
kana --clean                  # Launch an ephemeral, unsaved session

Inside the TUI, everything flows naturally through pure keyboard shortcuts and visible cues:

• Type / to open the command palette (/model to switch models, /memory to inspect memory, /tools for call history, /goal for bounded objectives);
• Type : to open the reusable prompt template palette to expand distilled workflows instantly;
• Type @ to open the Skill palette and inject specialized guidance on demand;
• Type !<command> to run local shell commands directly outside the agent loop;
• Non-blocking parallelism: Active subagents and background jobs stream in the Background · N strip, while tasks delegated back to you appear in Your tasks, keeping your main flow uninterrupted.

See TUI interaction for shortcuts, queued inputs, and complete controls.

2. Self-evolution: Memory, prompts, and specialized subagents

Kana shapes itself around your habits as you work:

• Two-tier durable memory: When correcting conventions or defining constraints, Kana records durable facts (inspect or consolidate anytime via /memory), retaining them across sessions separated by workspace and global scopes;
• Reusable prompt templates: Crystallize recurring routines into ~/.kana/prompts/<name>.md, then trigger them instantly in the editor with :<name>;
• Dedicated subagents: Define focused role cards under ~/.kana/agents/<role>.md with restricted tools or alternative models. The main agent spawns them asynchronously for deep audits or migrations while keeping the parent run responsive—auditable anytime via /agents.

See Subagents and Sessions and memory for details.

3. Headless automation and scripting

kana exec exposes the exact same runtime to scripts and automated pipelines:

kana exec "fix failing tests and verify"
printf 'summarize this codebase' | kana exec
kana exec resume <session-id> "continue this task"
kana exec --goal "resolve issue #42 end-to-end"
kana exec --timeout 30m "refactor this module"
kana exec --json "profile bottlenecks"

Emits the final answer to stdout and progress to stderr by default; --json produces versioned JSONL event streams. Power custom automation, or resolve issues into Pull Requests end-to-end using the Kana Agent reusable workflow. See Headless execution.

4. Extensibility: Skills and MCP

Install curated skills or sync them across other agent environments:

kana skills install
kana skills sync codex                               # Sync to Codex
kana skills sync --target-dir ~/.other-agent/skills  # Sync to any third-party agent

Kana auto-discovers project skills from .kana/skills and .agents/skills, reads project instructions from AGENTS.md, and connects to stdio or remote MCP servers. See Configuration and installation.

Updates and source install

Check and self-update

Installed release binaries can update themselves directly:

kana update --check
kana update

Install from source

Building from source requires Bun and Git:

git clone https://github.com/longyijdos/kana.git
cd kana
bun install --frozen-lockfile
./scripts/install.sh

Security and trust boundaries

Kana respects your local environment while keeping its boundaries transparent:

• Approvals are not a sandbox: Built-in tools and bash execute directly in your host environment. File tools can inspect paths outside the workspace, and shell commands run with your user privileges; never skip approvals in untrusted codebases.
• Pre-execution MCP trust: Stdio MCP servers spawn as local subprocesses before individual tool approvals; configure only trusted server binaries.
• Local sensitive data: Configurations, credentials, logs, and sessions live under ~/.kana/ (configurable via KANA_HOME) with restricted permissions. Sessions contain full execution history and should be treated as private data.

See Configuration and installation for the complete security model.

Documentation

See the Documentation index for architectural contracts, document sets, and routing guidance.

• Architecture & Setup: Architecture · Configuration and installation · Release process
• Core Runtime: Conversation runtime · Agent runtime · Tools and execution · Sessions and memory
• Models & Extensions: Providers · DeepSeek · OpenAI Codex · Custom provider · OAuth · MCP · Skills & system prompt · Subagents
• Frontend & Workflows: TUI interaction · Terminal rendering · Headless execution · Kana Agent workflow · Terminal-Bench evaluation

Development

Build from source and run the full verification suite:

bun install --frozen-lockfile
bun run check

bun run check runs Biome, TypeScript type checks, project style constraints, Knip dead-code analysis, and the Bun test suite.

Kana is actively evolving toward 1.0; see the Release process for versioning details. Contributions are warmly welcomed:

• For human contributors: Consult CONTRIBUTING.md for PR guidelines and development workflows;
• For coding agents: Consult AGENTS.md for agent-specific constraints and context.

License

MIT