Kanna
A web UI for the Claude Code and Codex agents, built for long sessions across many projects.
Documentation · Install guide · Changelog
What Kanna is
Kanna runs on your machine and puts a browser UI in front of the coding agents you already use: the Claude Agent SDK, the Codex app-server, OpenRouter models, and any Anthropic-compatible endpoint you register. Every chat belongs to a project, every event is saved to disk, and the UI works on a desktop, a phone, or through a tunnel.
Quickstart
curl -fsSL https://bun.sh/install | bash # if you don't have Bun 1.3.11+
bun install -g @cuongtran001/kanna
kanna # opens http://localhost:3210
Add a Claude OAuth token, a Codex login, or an OpenRouter key in Settings → Providers, open a project folder, and start a chat. The install guide covers requirements and flags.
How it fits together
One Bun process owns everything. The browser sends commands over a WebSocket, the agent coordinator runs each turn on a provider, and every change lands in an append-only event log under ~/.kanna/data. Refresh the page or restart the server and the chat comes back exactly as it was.
Features
Chat with any agent
- Claude, Codex and OpenRouter in one composer, with per-chat model, reasoning effort and context-window controls. Providers & models
- Custom endpoints: register any Anthropic-compatible API (GLM, Qwen, Kimi, DeepSeek, MiniMax, a local Ollama) in Settings and pick its models in the composer. Custom endpoints
- OAuth token pool: register several Claude tokens and Kanna rotates between them, failing over when one hits a rate limit. OAuth pool
- Live output: on chats that run on the Claude Agent SDK, thinking, text and tool input stream in as the model writes them, with the reply typed out behind a caret. Codex chats publish their plan as a live task list.
- Rich transcript: grouped tool calls, inline diffs, plan-mode approval, mermaid diagrams checked before you see them, and interactive charts, reports and flow diagrams the agent composes (generative UI).
- Slash commands everywhere:
/clear,/compact,/cron, plus your local Claude Code skills, on every provider. Slash commands
Let it work while you're away
- Subagents: named agents with their own prompts and tools. The main agent delegates, runs them in parallel or in the background, and gets the result back as a new turn. Subagents
- Autonomous loops: give a goal and a verify command; Kanna works through a durable task list until the check passes and stops on its own. Loops
- Cron jobs:
/cronschedules a recurring instruction, down to the second, in the same chat or a fresh one. Cron jobs - Durable queue: messages, wakes and scheduled runs wait in a per-chat queue that survives a server restart.
- Background tasks and workflows: dev servers, long builds and Claude Code workflows show live status, and Kanna keeps their session alive while they run.
Organize the work
- Projects and session tabs: chats grouped by project with live status, a split-pane workspace where Settings, Cron, Workflows, Boards and Webhooks open as tabs beside your chats, a project quick switcher, and one-click import of existing Claude Code sessions. Projects & sessions
- Kanban boards: Start work on a card creates a branch, a git worktree and a chat, so several agents can work at once without touching each other's files. Boards sync with GitHub issues. Boards
- Multi-repo stacks: group several repositories so one chat can read and edit across all of them. Stacks
Extend and connect
- Your MCP servers (
stdio,http,sse,ws, with OAuth 2.1) are available in every chat. Advanced - Kanna as an MCP server: Claude Code, Codex, Claude Desktop and ChatGPT can drive Kanna itself over MCP. Remote MCP
- Inbound webhooks: CI, GitHub or a
curlcall can post a card into a chat, queue a prompt, or start a new chat. Webhooks - Kanna plugins add sidebar pages, panels and
/commands, with a server half running in its own process. Plugins - Beacons pair another machine you own, so the agent can read files or run commands there within limits you set. Beacons
- Package updates for installed skills, Claude Code plugins and Codex plugins, checked and applied from Settings. Package auto-update
Run it anywhere
- Password gate, LAN or Tailscale binding, and Cloudflare tunnels (
--share,--cloudflared), plus an agent tool that exposes a dev server on request. Self-host - Read-only share links that render a chat exactly as you see it. Session share
- Resumable uploads for multi-gigabyte files, even behind a tunnel's request-size limit.
- Web push, PWA install, phone layout, customizable keybindings, and in-app self-update under pm2, systemd, Docker or a plain shell. Self-update
Usage
kanna # localhost only, opens a browser
kanna --port 4000 # custom port
kanna --remote # bind 0.0.0.0 (LAN, Tailscale)
kanna --password <secret> # require a password for the app, WebSocket and API
kanna --share # temporary public trycloudflare.com URL + terminal QR
kanna --cloudflared <token> # run a named Cloudflare tunnel
kanna plugin ls # manage Kanna plugins
kanna --help lists every flag. State lives in ~/.kanna; back it up to keep your chat history. Deployment recipes for pm2, systemd, Docker and a Cloudflare tunnel are in the wiki.
Development
git clone https://github.com/cuongtranba/kanna.git && cd kanna
bun install
bun run setup:hooks # gitleaks + commit-message hooks, once per clone
bun run dev # Vite client on :5174, server on :5175
bun run check # lint + types, comments, build
bun run test # Vitest via vp test, run under Bun
Start with CLAUDE.md and the contributing guide. The server is event-sourced, IO is sealed behind *.adapter.ts files, and the lint gates enforce both; the architecture page explains the shape. Releases are cut by release-please; see Releasing.
Documentation website
The docs at kanna-wiki.lowbit.link are built from wiki/ in this repo: an Astro Starlight site with its own package.json, kept apart from the root build, lint and tests. Every push to main that touches wiki/** rebuilds it and deploys it to GitHub Pages.
cd wiki
bun install
bun run dev # live preview of the docs site
bun run build # the same build CI deploys
Pages live in wiki/src/content/docs/. Change a page in the same PR as the behavior it describes.
The GitHub Wiki is a generated mirror of the same pages, rewritten from wiki/ on every push to main that touches it. Edit wiki/, never the GitHub Wiki: changes made there are overwritten on the next sync. To preview the mirror, run bun run export:github-wiki <dir> in wiki/.
Partners
Undercroft is an open-source, Vietnamese-first data platform (any REST source into an immutable raw lake, Postgres, dbt models and BI) whose MCP endpoint Kanna connects to as an MCP client over OAuth.