GitHub - jakemor/kanna: A beautiful web-based UI for Claude Code & Codex

A beautiful web UI for the Claude Code & Codex CLIs

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:

That's it. Kanna opens in your browser at localhost:3210.

Features

• Multi-provider support — switch between Claude and Codex (OpenAI) from the chat input, with per-provider model selection, reasoning effort controls, and Codex fast mode
• 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 (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

• Bun v1.3.5+
• A working Claude Code environment
• (Optional) Codex CLI for Codex provider support

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

The same --remote and --host flags can be used with bun run dev for remote development. --share is also supported in dev mode and exposes the Vite client URL publicly:

bun run dev --share
bun run dev --cloudflared <token>
bun run dev --port 3333 --share

In dev, --port sets the Vite client port and the backend runs on port + 1, so bun run dev --port 3333 --share publishes http://localhost:3333. --share remains incompatible with --host and --remote. Use bun run dev --port 4000 to run the Vite client on 4000 and the backend on 4001.

Or run client and server separately:

bun run dev:client   # http://localhost:5174
bun run dev:server   # http://localhost:5175

Scripts

Project Structure

src/
├── client/          React UI layer
│   ├── app/         App router, pages, central state hook, socket client
│   ├── components/  Messages, chat chrome, dialogs, buttons, inputs
│   ├── hooks/       Theme, standalone mode detection
│   ├── stores/      Zustand stores (chat input, preferences, project order)
│   └── lib/         Formatters, path utils, transcript parsing
├── server/          Bun backend
│   ├── cli.ts       CLI entry point & browser launcher
│   ├── server.ts    HTTP/WS server setup & static serving
│   ├── agent.ts     AgentCoordinator (multi-provider turn management)
│   ├── codex-app-server.ts  Codex App Server JSON-RPC client
│   ├── provider-catalog.ts  Provider/model/effort normalization
│   ├── quick-response.ts    Structured queries with provider fallback
│   ├── ws-router.ts WebSocket message routing & subscriptions
│   ├── event-store.ts  JSONL persistence, replay & compaction
│   ├── discovery.ts Auto-discover projects from Claude and Codex local state
│   ├── read-models.ts  Derive view models from event state
│   └── events.ts    Event type definitions
└── shared/          Shared between client & server
    ├── types.ts     Core data types, provider catalog, transcript entries
    ├── tools.ts     Tool call normalization and hydration
    ├── protocol.ts  WebSocket message protocol
    ├── ports.ts     Port configuration
    └── branding.ts  App name, data directory paths

Data Storage

All state is stored locally at ~/.kanna/data/:

Event logs are append-only JSONL. On startup, Kanna replays the log tail after the last snapshot, then compacts if the logs exceed 2 MB.

Star History

Contributing

Contributions are welcome! Feel free to open PRs

License

MIT