Kode cli

Kode CLI — Terminal AI Assistant

*rea:*Developer Platform
*ath:*dev/kode
*ind:*Go CLI + Bubble Tea TUI
*ersion:*1.3.7
*tatus:*Active

Role in the stack

dev/kode is the terminalnative client for the Kode AI assistant. It connects to services/ai/kode/platform via WebSocket relay and exposes a rich TUI (Bubble Tea) with markdown rendering, syntax highlighting, tool execution, and ambient context capture (Chronicle). It is the primary interface for developers who prefer a keyboarddriven, terminal-first workflow.

On session start, Kode captures git state, shell history, recently~~modified files and stderr buffer, and sends this snapshot to the relay so the AI has full dev~~environment context without any manual copy-paste.

Primary couplings

Module	Relationship
`services/ai/kode/platform`	WebSocket relay — all AI sessions go through the relay
`foundation/id`	OAuth2 Device Flow login for Claude, Gemini, OpenAI providers
`dev/kode` (self)	Chronicle context package captures local dev environment

Interfaces

CLI flags

kode [flags]
  --relay              Relay URL (default from ~/.config/kode/config.yaml)
  --model              AI model override
  --version            Print version
  --once <prompt>      Non-interactive: send a single prompt, print reply, exit (CI/scripts)
  --once /<command>    Non-interactive: dispatch a slash command via internal/core
  --once --json …      Same, emit JSON for downstream parsing
  --help               Show usage

kkode is a symlink alias to kode; when invoked under that name the binary skips the TUI and runs --once mode automatically — useful for shell aliases and scripts.

TUI slash commands (selected)

Command	Description
`/new`	New session
`/sessions`	List + navigate sessions
`/switch <id>`	Resume a session from any frontend
`/kill <id>`	Delete a session
`/rename <name>`	Name the current session
`/resume [id]`	Resume session filtered by current work_dir
`/folder list\|create\|assign\|unassign\|delete`	Organise sessions into named folders
`/model <id>`	Switch model
`/models [query]`	List and filter available models
`/login <provider>`	OAuth2 login (claude / gemini / openai / etc.)
`/persona list\|create\|use\|delete`	Manage AI personas
`/instructions [text]`	View or set custom instructions
`/memory list\|save\|search\|delete\|browse`	Manage cross-session memories
`/chronicle on\|off\|status\|now`	Toggle or trigger Chronicle snapshot
`/add <glob>`	Add files/images to AI context
`/drop <glob>`	Remove files from AI context
`/run <cmd>` / `!<cmd>`	Execute shell command and inject output
`/web <url>`	Fetch URL and inject into context
`/export [filename]`	Export conversation to Markdown
`/share`	Publish conversation as a public share link
`/commit [msg]`	Git commit with AI-authored message
`/diff`	Inject current git diff
`/git <cmd>`	Any git subcommand
`/lint` / `/test`	Run lint/test suite after AI edits
`/repomap`	Inject codebase structure map
`/watch [on\|off]`	Watch for `// kode:` directives in source
`/architect`	Dual-model mode (planner + coder)
`/dryrun [on\|off]`	Preview edits without writing to disk
`/yolo [on\|off]`	Auto-approve tool calls
`/hooks [event]`	Manage event hooks
`/k-tui [name]`	Switch TUI skin (kode, claude, gemini, codex)
`/tools`	Toggle allowed tools
`/thinking-tokens <N>`	Extended thinking budget
`/reasoning-effort low\|medium\|high`	Reasoning depth
`/paste` / `/copy`	Clipboard integration
`/cache [on\|off]`	Toggle prompt caching
`/usage`	Token usage per provider
`/providers`	Configured accounts
`/stats`	Session statistics
`/agents`	Multi-agent status
`/apply [id\|all]`	Apply queued dry-run writes
`/review`	AI code review of current diff
`/compact` / `/compress`	Compress session context
`/help`	Show full help

Conversation folders

Folders are stored client-side in ~/.config/kode/folders.json. Each folder has an ID, a name, and a list of session IDs. Sessions can belong to at most one folder. The session picker shows [folder-name] next to sessions that are assigned.

Config file

~/.config/kode/config.yaml:

relay_url: wss://kode.koder.dev/v1/relay/ws
default_provider: claude
default_model: claude-opus-4-7
work_dir: ~/dev
allowed_tools:
  - shell
  - read_file
  - write_file
  - list_dir
  - install_pkg
  - env_info
context:
  git_snapshot: true
  shell_history: true
  file_watcher: true
  stderr_buffer: true
  auto_kode_md: true
  chronicle:
    enabled: false
    mode: local
    interval_turns: 5
auto_lint: false
auto_test: false
auto_commit: false
tui_skin: kode
yolo_mode: false

Local files:

File	Contents
`~/.config/kode/config.yaml`	Runtime config
`~/.config/kode/credentials.enc`	OAuth2 tokens (AES~~256~~GCM)
`~/.config/kode/folders.json`	Conversation folder assignments
`~/.config/kode/personas/`	Custom persona YAML files
`~/.config/kode/hooks/<event>/`	User hook scripts
`~/.config/kode/chats/`	Session transcripts (auto-save)
`~/.config/kode/kode.md`	Global KODE.md auto-loaded on startup

Architecture

graph TD
    A[kode CLI] -->|WebSocket WSS| B[ai/kode/platform relay]
    B -->|REST/SSE| C[ai/gateway]
    C --> D[Claude]
    C --> E[Gemini / OpenAI / others]
    A -->|OAuth2 device flow| F[foundation/id]
    A -->|reads| G[git / shell history / files]
    A -->|stores| H[~/.config/kode/]

Source layout

products/dev/kode/
  cmd/kode/main.go        Entry point — --version, --help, --once flags; kkode alias
  app/
    tui/                  Bubble Tea TUI surface (formerly internal/tui/, moved per RFC-006 §4)
      app.go              Model — UI loop, legacy slash-command switch
      styles.go           Lipgloss styles
      skins.go            TUI skin system (kode, claude, gemini, codex)
      repomap.go          /repomap codebase tree
    cli/                  One-shot non-interactive mode (DKODE-085, 2026-05-04)
      cli.go              Run() — slash via core.Dispatch, prompts via relay session
  app/
    tui/
      core_bridge.go      Wires TUI Model to internal/core dispatcher (DKODE-089)
  internal/
    core/                 UI-agnostic dispatcher (DKODE-084, 2026-05-04)
      core.go             Line, Result{Lines,ChangedFlags,Exit,Handled,Err}, State, Dispatch
      handlers_session.go /status /reset /verbose /trace /cache /dryrun /thinking-tokens /reasoning-effort /output-style
      handlers_relay.go   /usage /instructions /switch /kill /rename
      handlers_config.go  /config show|set|validate
      handlers_lifecycle.go /about /exit /quit /bye
      handlers_permissions.go /perms list|test
    permissions/             Allow/deny matcher (DKODE-092)
      matcher.go             Match(lists, verb, target) → (Decision, rule)
    tools/
      executor.go            Execute / ExecuteWithAudit (msg, allowedTools, perms, auditLog, sessionID) → consults CheckPermission, optionally appends audit JSONL line per call (DKODE-093 + DKODE-098). Denied calls fail KODE-PERM-001.
    audit/
      log.go                 JSONL forensic log at ~/.config/kode/audit/<day>.jsonl; opt-in via cfg.AuditLog (DKODE-098)
    hooks/
      hooks.go               Subprocess runtime + stdout JSON protocol + KODE-HOOK-NNN error IDs (DKODE-092)
    relay/
      client.go           WebSocket client — auth, send/recv, reconnect
      protocol.go         Wire types (mirrors services/ai/kode/platform/relay/protocol.go)
    context/
      git.go              Git snapshot
      shell.go            Shell history reader
      stderr.go           Stderr ring buffer (128 KB)
      watcher.go          File watcher (hot files, 30s poll)
      injector.go         Compose + format context snapshot
    auth/
      store.go            Credential storage (AES-256-GCM)
      oauth2.go           Device Flow + PKCE
      login.go            /login handler
    config/
      config.go           YAML config + sub-structs
      hierarchy.go        LoadHierarchical — defaults → user → workspace overlay (DKODE-043)
      folders.go          FolderStore — client-side session grouping
      kode_template.go    Default KODE.md template
    persona/
      store.go            Persona YAML storage
    hooks/
      hooks.go            Event hook runner
    tools/
      executor.go         Local tool execution (shell, file I/O)

TUI Skins

Skin	Provider default	Style
`kode`	Claude	Purple/indigo theme
`claude`	Claude	Minimal dark
`gemini`	Gemini	Blue/cyan
`codex`	OpenAI	Green terminal

Chronicle ambient context

Chronicle is an opt-in feature that captures the developer's environment:

*it snapshot*— current branch, modified files, recent diff
*hell history*— last 20 commands from bash/zsh history
*ile watcher*— files modified in the last 2 hours (max 20)
*tderr buffer*— last stderr from the terminal
*TY capture*— periodic terminal output (/chronicle on)
*uto KODE.md*— session summary written to .kode/KODE.md on exit

Release history

Version	Date	Summary
1.2.3	20260427	PDF analysis — `/add file.pdf` extracts plain text via `ledongthuc/pdf`; no binary sent to AI
1.2.2	20260427	`/share` command — publish conversation as a public share link via relay REST API
1.2.1	20260427	Conversation folders (`/folder` command, client-side storage, session picker tags)
1.2.0	20260426	Command autocomplete palette (inline, prefix-filtered, ↑↓ navigate)
1.1.1	20260426	YoloMode auto-disable after 30 min idle
1.1.0	20260426	Skin field on sessions, double-Esc rewind (skin=claude)
1.0.0	20260426	Hooks framework, /hooks command, dry-run interactive apply
0.4.0	20260425	Memory browser TUI, OAuth2 auto-refresh, PTY chronicle
0.3.5	20260423	/memory commands, Chronicle ambient context
1.3.0	20260504	RFC~~006 sector layout: TUI moves to `app/tui/`; new `app/cli/` one~~shot mode + `kkode` alias; `internal/core/` UI~~agnostic dispatcher (DKODE~~084 + DKODE-085); hierarchical config + workspace overlay + `/config show	set	validate `(DKODE-043); specs` kodeconfig-format.kmd `+` kodehooks.kmd` published
1.3.1	20260504	DKODE~~089 fatia 1: 17 commands in `internal/core` (added `/about /exit /quit /bye /switch /kill /rename /usage /instructions /thinking~~tokens reasoning~~effort /output~~style /cache /dryrun /verbose /trace`); TUI bridge consults` core.Dispatch `before legacy switch;` Result.Exit `signal; legacy duplicates removed from` apptuiapp.go`.` status /reset /yolo /providers /model` stay TUI~~bound pending DKODE~~090.
1.3.2	20260504	DKODE090: `core.State` gains session counters (`TurnCount`, `ToolCalls`, `CodeChanges`, `*Ms`); `/status` and `/reset` migrated (19 commands now in core). Bridge `coreState()` snapshots counters; `reset:buffers` ChangedFlag wipes Model scrollback. `/yolo /providers /model` remain TUIbound.
1.3.3	20260504	DKODE~~092: new `internal/permissions/` package with `Match(lists, verb, target)` (default~~deny for `bash:`, deny>allow, longest~~rule~~wins, recursive `` glob). `Cfg.Permissions{Allow,Deny}` added; `/perms list` + `/perms test` handlers in core (20 commands now). `internal/hooks/` extended with stdout JSON output protocol (`block``annotation``replace_prompt``replace_tool_input`) + `Result.ErrorID = KODE-HOOK-001..004`. Tool executor wiring + overlay tighten~~only check + full trigger audit deferred to DKODE~~093*094/095.
1.3.4	20260504	DKODE~~093: `tools.Execute(msg, allowedTools, perms)` now consults `permissions.CheckPermission` before each tool call. Denied calls fail with `KODE~~PERM-001: tool %q denied by rule %q`. Mapping: shell→bash, read_file/list_dir→fs:read, write_file→fs:write, install_pkg→bash, others→tool. TUI call site updated to pass` cfg.Permissions`.
1.3.5	20260504	DKODE~~094: workspace overlay tighten~~only validation. `LoadHierarchicalWithWarnings()` returns `OverlayWarning`s for overlay `allow` rules that try to loosen explicit user~~level `deny`. Default~~deny on `bash:*` does NOT count (overlays can carve out bash exceptions freely). `/config validate` reports dropped rules.
1.3.6	20260504	DKODE-095: hook trigger audit + JSON output protocol consumers. TUI's UserPromptSubmit honours ReplacePrompt + Annotation; PreToolUse honours ReplaceToolInput (commandpathcontentpkgcwd) + Annotation; PostToolUse and Stop converted goroutine→sync to print Annotation to scrollback. CLI gains SessionStart, UserPromptSubmit, Stop triggers (Annotation→stderr; ReplacePrompt rewrites outgoing text).
1.3.7	20260504	k~~evolve batch: DKODE~~096 (CLI streaming — `kode --once` prints AI tokens to stdout as they arrive; `--json` keeps buffered emit), DKODE~~097 (stdin as prompt — `echo "x" \| kode -~~once `works; non-TTY detection via` stat`), DKODE-098 (forensic audit log JSONL at` ~.configkodeauditday.jsonl`, opt-in via` cfg.AuditLog`, captures every tool execution with verbtargetdecisionruleexit_codeduration_ms).