████████╗██╗   ██╗██╗
╚══██╔══╝██║   ██║██║
   ██║   ██║   ██║██║
   ██║   ██║   ██║██║
   ██║   ╚██████╔╝██║
   ╚═╝    ╚═════╝ ╚═╝
   K A N N A K A · T E R M I N A L

A production-grade coding-agent harness + an eight-tab constellation dashboard. Pure frontend, zero coupling.

kannaka-tui is the terminal harness for the Kannaka constellation. A full-screen ratatui app that never links kannaka-memory as a library — every operation shells out to the kannaka CLI binary. Its headline surface is the Agent tab: an agentic coding loop (read / write / edit / bash / glob / grep, plus HRM memory tools) that drives kannaka agent --json, renders the live transcript, and gates every filesystem/shell mutation behind a human approval dialog. The other seven tabs — Memory, Status, Bus, Constellation, Dreams, Chat, Cosmos — are windows into the same wave-interference substrate.

[]() []() []()

Tabs

┌──────────────────────────────────────────────────────────────────────────┐
│ Memory │ Status │ Bus │ Constellation │ Dreams │ Chat │ Cosmos │ Agent    │
│                                                                            │
│   ⚙ edit_file  src/main.rs              kannaka  Done. Added the guard.    │
│   ┌ Approval required ──────────────┐   a allow · s always · d deny        │
│                                                                            │
│ > fix the panic in the parser                                      [Ag]   │
└──────────────────────────────────────────────────────────────────────────┘

Agent harness

The Agent tab turns kannaka-tui into a production-grade coding agent. Type a task and press Enter; the agent investigates and edits your workspace through a tool-calling loop, with you in the loop on anything that changes state.

Tools (executed in your current directory): read_file, write_file, edit_file, bash, glob, grep, list_dir — plus kannaka's own recall / remember / status so the agent is HRM-grounded. Reads and searches run freely; write/edit/bash require your approval.

Approval — when the agent wants to mutate a file or run a command, a modal appears:

Permission modes (status strip shows the current one):

Stuck or want to redirect? Press Esc (or type /stop) while the agent is working to cancel the current turn, then type a new task. /clear resets the session.

Other commands: /model <id> (switch model), /clear (fresh session), /help. Hard-blocked commands (rm -rf /, curl … | sh, fork bombs) are refused outright; destructive-but-reversible ones (rm -rf, git reset --hard, …) are flagged ⚠ in the approval dialog.

Default AI: Kannaka's own brain

Since 2026-09-05 the default model behind the harness is kannaka-brain-v1 — Qwen2.5-14B with a LoRA trained on Kannaka's own writing (flaukowski/kannaka-brain-v1-GGUF), served on our own hardware behind the KAX gateway (ADR-0057). The harness is kannaka agent --json, so the default lives in kannaka's config, not here:

# ~/.kannaka/config.toml
[llm]
provider = "openai"                 # any OpenAI-compatible endpoint
model = "kannaka-brain-v1"          # or kannaka-brain-32b-v1
api_key = "sk-..."                  # a gateway virtual key
base_url = "http://<gateway>/v1"    # the KAX gateway (lab: 10.30.0.30:4000)

/model kannaka-brain-32b-v1 switches at runtime. To go back to a hosted model, set provider = "anthropic" (or KANNAKA_LLM_PROVIDER=anthropic in the env). A 14B on CPU answers in 15–30 s and is weaker at tool calls than a frontier model — that is the point: what breaks here is the next thing to fix.

The agent backend is the new kannaka agent --json subcommand (added to kannaka-memory); kannaka-tui is its harness front-end. Requires an LLM configured in ~/.kannaka/config.toml (Anthropic); the harness falls back to a current model if the configured one is unavailable.

Install

Requires the kannaka binary on PATH — see kannaka-memory.

# Pre-built binary
curl -L -o kannaka-tui \
  https://github.com/NickFlach/kannaka-tui/releases/latest/download/kannaka-tui-linux-x86_64
chmod +x kannaka-tui && mv kannaka-tui ~/.local/bin/

# Or build from git
cargo install --git https://github.com/NickFlach/kannaka-tui

Windows:

curl -L -o kannaka-tui.exe `
  https://github.com/NickFlach/kannaka-tui/releases/latest/download/kannaka-tui-windows-x86_64.exe

After kannaka update v0.5.15+, the kannaka binary will keep the TUI sibling up-to-date alongside itself when both are in the same directory.

Hotkeys

Command bar

The Memory and Chat tabs share a command bar. Recognized verbs run the matching kannaka subcommand on a background worker — the UI never blocks, even on long ones like ask — while anything unrecognized routes to chat.

remember "text"   recall "query"    forget <id>      search "query"
relate "query"    neighbors "query" boost <id>       dream [lite]
clusters          topology          assess  stats  cmf  invariant
hear <file|url>   see <file|url>    voice ...        ask "question"
swarm <subcmd>    market [...]      cosmos | constellation | radio

Set KANNAKA_BIN to point the TUI at a specific kannaka build; otherwise it resolves a sibling binary, then ~/Source/kannaka-memory/target/release, then PATH.

Architecture

┌────────────────────────────────────────────────────────────┐
│                       kannaka-tui                          │
├──────────────────────┬─────────────────────────────────────┤
│  Event loop          │  Long-lived workers                 │
│  · 100ms ticks       │  · chat-child  (kannaka chat --json)│
│  · ratatui draw      │  · bus reader  (kannaka swarm tail) │
│  · key dispatch      │  · status pollers (kannaka status)  │
├──────────────────────┴─────────────────────────────────────┤
│  Shellout subprocess layer                                 │
│  · Command::new("kannaka") → stdout NDJSON / text          │
│  · Per-op channels (mpsc) for non-blocking UI              │
├────────────────────────────────────────────────────────────┤
│  ratatui rendering                                         │
│  · Tabs widget · Gauges · Canvas (Braille) · Paragraph     │
└────────────────────────────────────────────────────────────┘

The TUI is a pure frontend: it never links kannaka-memory as a Rust library. Every operation goes out as a subprocess. This means TUI updates ship independently of the memory engine, and adding integrations with other constellation members (kannaka-code, Kannaktopus) is just another subprocess hook.

Constellation

License

MIT. See LICENSE.