Quickstart
bun install -g kanna-code
If Bun isn't installed, install it first:
curl -fsSL https://bun.sh/install | bash
Then run from any project directory:
kanna
That's it. Kanna opens in your browser at localhost:3210.
Features
- Multi-provider support — switch between Claude, Codex (OpenAI), Cursor, Grok Build, and Pi from the chat input, with per-provider model selection, reasoning effort controls, and Codex fast mode
- Bundled Pi agent — the pi coding agent ships as a dependency and runs in-process through the Model Registry (Settings): point it at OpenRouter, OpenAI, or any custom OpenAI-compatible endpoint, pin fave models to the picker, and use any model id with standardized reasoning efforts — no local pi installation involved
- Project-first sidebar — chats grouped under projects, with live status indicators (idle, running, waiting, failed)
- Drag-and-drop project ordering — reorder project groups in the sidebar with persistent ordering
- Local project discovery — auto-discovers projects from both Claude and Codex local history
- Rich transcript rendering — hydrated tool calls, collapsible tool groups, plan mode dialogs, and interactive prompts with full result display
- Quick responses — lightweight structured queries (e.g. title generation) via Haiku with automatic Codex fallback
- Plan mode — review and approve agent plans before execution
- Persistent local history — refresh-safe routes backed by JSONL event logs and compacted snapshots
- Auto-generated titles — chat titles generated in the background via Claude Haiku
- Session resumption — resume agent sessions with full context preservation
- WebSocket-driven — real-time subscription model with reactive state broadcasting
Architecture
Browser (React + Zustand)
↕ WebSocket
Bun Server (HTTP + WS)
├── WSRouter ─── subscription & command routing
├── AgentCoordinator ─── multi-provider turn management
├── ProviderCatalog ─── provider/model/effort normalization
├── QuickResponseAdapter ─── structured queries with provider fallback
├── EventStore ─── JSONL persistence + snapshot compaction
└── ReadModels ─── derived views (sidebar, chat, projects)
↕ stdio
Claude Agent SDK / Codex App Server / cursor-agent / grok CLI (local processes)
↕
Local File System (~/.kanna/data/, project dirs)
Key patterns: Event sourcing for all state mutations. CQRS with separate write (event log) and read (derived snapshots) paths. Reactive broadcasting — subscribers get pushed fresh snapshots on every state change. Multi-provider agent coordination with tool gating for user-approval flows. Provider-agnostic transcript hydration for unified rendering.
Requirements
Embedded terminal support uses Bun's native PTY APIs and currently works on macOS/Linux.
Install
Install Kanna globally:
bun install -g kanna-code
If Bun isn't installed, install it first:
curl -fsSL https://bun.sh/install | bash
Or clone and build from source:
git clone https://github.com/jakemor/kanna.git
cd kanna
bun install
bun run build
Usage
kanna # start with defaults (localhost only)
kanna --port 4000 # custom port
kanna --no-open # don't open browser
kanna --password <secret> # require a password before loading the app
kanna --share # create a public quick tunnel + terminal QR
kanna --cloudflared <token> # run a named Cloudflare tunnel from a token
Default URL: http://localhost:3210
Network access (Tailscale / LAN)
By default Kanna binds to 127.0.0.1 (localhost only). Use --host to bind a specific interface, or --remote as a shorthand for 0.0.0.0:
kanna --remote # bind all interfaces — browser opens localhost:3210
kanna --host dev-box # bind to a specific hostname — browser opens http://dev-box:3210
kanna --host 192.168.1.x # bind to a specific LAN IP
kanna --host 100.64.x.x # bind to a specific Tailscale IP
When --host <hostname> is given, the browser opens http://<hostname>:3210 automatically. Other machines on your network can connect to the same URL:
Password protection
Use --password to require a launch password before the app or websocket can connect:
kanna --password my-secret
bun run dev --password my-secret
Kanna verifies the password once, then sets a browser-session cookie. The password itself is not stored in the browser.
When password protection is enabled, the backend requires authentication for API routes and /ws. The SPA shell still loads, /health remains public for restart detection, and the same in-app password screen is used in both dev and production.
Public share link
Use --share to create a temporary public trycloudflare.com URL and print a terminal QR code:
kanna --share
kanna --share --port 4000
kanna --cloudflared <token>
--share is incompatible with --host and --remote. It does not open a browser automatically.
Without a token, it prints:
QR Code:
...
Public URL:
https://<random>.trycloudflare.com
Local URL:
http://localhost:3210
With --cloudflared <token>, Kanna runs cloudflared tunnel run --token <token> --url <local-url>.
If Kanna can detect the public hostname from cloudflared output, it prints the same QR/public/local block.
If not, it keeps the tunnel running, warns that no public hostname was detected, and prints the local URL so you can use the hostname already configured for that tunnel in Cloudflare.
Development
bun run dev
This is the beginning of the README. Read the rest at the original. Read the full README ↗
