Skip to content
ka

Quickstart

A first session with a local model

Section titled “A first session with a local model”

If you have Ollama running, ka needs no API key at all:

Terminal window
cd your-project
ka --model ollama/qwen3.5:9b

The TUI opens a fresh session. Type a request, press Enter, and watch ka read, search, and edit under your permission mode. Press Esc at any time to abort the turn.

Using an API provider

Section titled “Using an API provider”

Set the provider’s key (e.g. ANTHROPIC_API_KEY) in your environment or in ~/.config/ka/.env, then:

Terminal window
ka --model anthropic/claude-sonnet-5

ka providers lists known providers and whether their key env vars are set. /model inside the TUI opens a picker over the whole catalog: filter as you type, pick with Enter.

The keys that matter

Section titled “The keys that matter”
Key Action
Enter Send, or steer mid-turn while ka is working
+text then Enter, or Alt+Q Queue a message (or a slash command) until the current turn ends
Esc / Ctrl-C Abort the current turn
↑ / ↓ Input history
PgUp / PgDn Scroll the transcript (Esc re-pins to the tail)
⇧Enter (or Ctrl-J) Newline in the draft
/help Everything else

The transcript renders markdown: headers, lists, fenced code with syntax coloring. Each tool call is a state-tinted card you can expand in place; thinking collapses to a foldable band; every turn ends with a verdict row.

Coming back to sessions

Section titled “Coming back to sessions”
Terminal window
ka -c                      # continue this terminal's last session
ka --session 3f9c2a81      # resume by id prefix
ka sessions                # list session ids for this directory
ka export --session 3f9c   # export one as markdown

ka -c is waypoint-aware: each terminal remembers its own latest strand, so two panes next to each other resume their own conversations.

Headless, one turn

Section titled “Headless, one turn”
Terminal window
ka run "summarize the build error"

Prints the final answer. Add --print ndjson for ka’s event stream, or --print stream-json for Claude-Code-shaped output. Exit codes: 0 ok, 1 error, 2 aborted. See headless.

Point ka at your project

Section titled “Point ka at your project”

ka reads your project’s conventions automatically; no wiring required:

  • AGENTS.md (or CLAUDE.md) instructions, from repo root down to your cwd
  • SKILL.md skills and markdown agents in .ka/, .agents/, .claude/
  • custom slash commands in .ka/commands/*.md

Run ka init to generate a starter AGENTS.md from a quick scan of your repository shape.

Next steps

Section titled “Next steps”