Advanced

Self-update

One click installs the new version and restarts Kanna on it. Works under pm2, systemd, Docker, or a plain shell via a host-agnostic supervisor, and you can install any prior release straight from the changelog. See Self-update for the strategies and overrides.

Expose port (Cloudflare tunnel)

The agent can call mcp__kanna__expose_port right after it starts a dev server, to surface that localhost port through a Cloudflare quick tunnel. Enable it under Settings → Cloudflare Tunnel (off by default) and pick a mode: Always ask shows a card in the chat that you accept, Auto-expose starts cloudflared immediately. Tunnels stop when the chat closes or the server restarts. Requires cloudflared on your PATH; see Cloudflare tunnel.

Custom MCP servers

Register your own MCP servers from Settings → MCP servers. Entries persist in settings.json (customMcpServers) and are merged in at chat spawn time, so their tools appear as mcp__<name>__<tool>.

• Transports: stdio, http, sse, ws. The name kanna is reserved.
• OAuth: http and sse servers support OAuth 2.1 (PKCE + dynamic client registration + rotating refresh). Kanna has no redirect server, so after the provider redirects to http://localhost:8765/callback?code=… you copy that URL from the address bar and paste it back into Settings to complete the flow. Tokens refresh automatically before expiry.
• Connect-test: creating or updating a server fires a list-tools probe; the row shows a status pill, and a manual Test button re-runs it.
• Trust model: user MCP tool calls auto-allow — if you installed it, Kanna trusts it.
• Secrets: settings.json is written with your default file mode, not 0600. On a shared machine, restrict the directory with chmod 700 ~/.kanna/data.

The LSP tool

Claude chats can call the LSP tool for go-to-definition, find-references and go-to-implementation. It is one tool for every language: the Claude CLI picks a language server from whichever *-lsp plugin you have installed. Adding a language means installing that plugin and putting its server on the PATH of the process that runs Kanna, for example npm i -g typescript-language-server typescript for typescript-lsp, or go install golang.org/x/tools/gopls@latest for gopls-lsp.

Workflow status panel

Kanna surfaces Claude Code’s native Workflow tool (dynamic multi-agent orchestration) in a read-only per-chat panel: every run with live status, drill-in progress, token totals, and an inline transcript card on the launch. It works by watching the wf_<runId>.json sidecars Claude writes to disk, so the panel stays accurate without touching the event stream. Stopping or relaunching runs from the panel is out of scope.

Agent chat re-entry

The agent can hand work off and have the chat pick it up again later, without polling on a timer.

Call mcp__kanna__delegate_subagent({ run_in_background: true, … }) and the tool returns immediately with a run id while the subagent works. When it finishes, Kanna re-enters the chat as a new turn carrying the result — so a long job costs one wake, not a polling loop. In a chat that is not running a loop the agent keeps its conversation; an armed loop clears the main agent’s context on every wake, because the task list is the plan. Delivery is event-driven and provider-agnostic, and it survives a server restart via event replay.

For work that should recur on a clock rather than on completion, use cron jobs.

Removed

The timer-based mcp__kanna__schedule_wakeup tool and its KANNA_MAX_AGENT_WAKES cap no longer exist — they were removed when re-entry became notification-driven. A self-polling agent lost momentum across context compaction, which is what the background-delegation path above fixes.

Local skills & slash commands

The composer’s / picker lists local Claude Code skills and slash commands discovered on disk alongside Kanna’s built-ins, so installed plugin skills are one keystroke away, on every provider including Codex. /clear, /compact and /cron are Kanna’s own — see Slash commands.

Text snippets

Settings → Text snippets maps a short shortcut to a longer expansion, expanded as you type in the composer. Useful for the paragraph of standing context you retype into every new chat.

Global instructions

Settings → Instructions appends text to the system prompt of every agent spawn, on every provider. This is the place for house rules that are not repo-specific — repo-specific ones belong in that repo’s CLAUDE.md or AGENTS.md, which the agent already reads.

Per-turn token cost

Each turn shows its token usage and estimated USD cost in the transcript, computed from the provider’s model pricing — so you can see what a session is spending as it runs.

Mermaid rendering, checked before you see it

Mermaid diagrams in agent output render inline in the transcript.

graph LR
  User --> Kanna
  Kanna --> SDK[Claude Agent SDK]
  Kanna --> Codex
  Kanna --> OpenRouter
  SDK --> Anthropic
  Codex --> OpenAI

Because a syntax error would reach you as a broken diagram, the agent validates its diagrams against mermaid’s real parser (mcp__kanna__validate_mermaid) before answering, and fixes them in the same turn — so you never see the bad version. If one slips through anyway, an end-of-turn check asks the agent to correct it, once per diagram. Set KANNA_MERMAID_GUARD=disabled to turn off that second pass; the tool itself stays.

Standalone HTML transcript export

Export any chat to a self-contained HTML file. Inline CSS + screenshots, no external dependencies, sharable.

Customizable keybindings

See Reference → Keybindings for the full default map and customization syntax.

Password gate

Protect the HTTP/WS/API surface with a password: run kanna --password <secret> and Kanna prompts on every browser session. See Security.

PWA / mobile layout

Kanna is installable as a PWA. Mobile layout adapts to small viewports with a slide-in sidebar and touch-tuned composer.