Kanna

A beautiful web UI for the Claude Code & Codex CLIs

# require a password before loading the app kanna --share # create a public quick tunnel + terminal QR kanna --cloudflared # 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`: ```bash 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 ` is given, the browser opens `http://: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: ```bash 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: ```bash kanna --share kanna --share --port 4000 kanna --cloudflared ``` `--share` is incompatible with `--host` and `--remote`. It does not open a browser automatically. Without a token, it prints: ```text QR Code: ... Public URL: https://.trycloudflare.com Local URL: http://localhost:3210 ``` With `--cloudflared `, Kanna runs `cloudflared tunnel run --token --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 ```bash bun run dev ``` 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: ```bash bun run dev --share bun run dev --cloudflared 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: ```bash bun run dev:client # http://localhost:5174 bun run dev:server # http://localhost:5175 ``` ## Scripts | Command | Description | | -------------------- | ---------------------------- | | `bun run build` | Build for production | | `bun run check` | Typecheck + build | | `bun run dev` | Run client + server together | | `bun run dev:client` | Vite dev server only | | `bun run dev:server` | Bun backend only | | `bun run start` | Start production server | | `bun test` | Unit/integration tests | | `bun run test:e2e` | Playwright browser smoke suite | ## Project Structure ``` src/ ├── client/ React UI layer │ ├── app/ App router, pages, socket client, useKannaState + feature hooks │ │ (useChatCommands, useSendMessage, useAppSettingsSync, │ │ useUpdateRestart, useShareExport, snapshotEquality) │ ├── components/ Messages, chat chrome (incl. chat-ui/git/ panel modules), │ │ dialogs, buttons, inputs │ ├── hooks/ Theme, standalone mode detection │ ├── stores/ Zustand stores (chat input, preferences, project order) │ └── lib/ Formatters, path utils, transcript parsing, storage keys ├── 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 │ ├── cursor-cli.ts / pi-agent.ts Cursor and Pi provider adapters │ ├── provider-catalog.ts Provider/model/effort normalization │ ├── quick-response.ts Structured queries with provider fallback │ ├── ws-router.ts WebSocket command routing & snapshot subscriptions │ ├── skills.ts Skill search/install/uninstall │ ├── 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 e2e/ Playwright smoke suite (boots the real server) ``` ## Data Storage All state is stored locally at `~/.kanna/data/`: | File | Purpose | | ---------------- | ----------------------------------------- | | `projects.jsonl` | Project open/remove events | | `chats.jsonl` | Chat create/rename/delete events | | `messages.jsonl` | Transcript message entries | | `turns.jsonl` | Agent turn start/finish/cancel events | | `snapshot.json` | Compacted state snapshot for fast startup | 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](LICENSE)