Skip to content

Quickstart

Board up. First task running. Under five minutes.

Prerequisites: uv, git, a local repo, and at least one supported agent installed.

1. Install

# Don't have uv? One line:
curl -LsSf https://astral.sh/uv/install.sh | sh

uv tool install kagan
kagan --version

2. Launch

Start with the TUI unless you specifically want browser or editor-first supervision:

  • kagan - primary operator surface
  • kagan web - remote dashboard
  • VS Code extension - embedded companion surface
  • kagan mcp - MCP clients like Claude Code, Cursor, or OpenCode
cd your-project-directory
kagan

On a fresh install with no projects yet, bare kagan shows a one-time surface picker so you can choose TUI, web, chat, VS Code, Open VSX, or MCP setup. Runtime picks (TUI, web, chat) become the default for future bare kagan launches until you change them in settings.

Welcome screen -> open/create project -> board appears (BACKLOG -> IN_PROGRESS -> REVIEW -> DONE). The canonical flow is Create -> Start -> Review -> Merge; the board is where that flow begins.

Optional: use VS Code

If you want Kagan inside your editor, install the VS Code extension from the Visual Studio Marketplace or Open VSX.

If you install the extension, you do not need .vscode/mcp.json just to use the Kagan sidebar or @kagan chat.

Full guide: VS Code extension

3. Create a task

n -> title + description -> Ctrl+S save. Task appears in BACKLOG.

4. Run it

  • Run in background: Select task -> s to start. Use Shift+S to stop.
  • Open in editor or terminal: Select task -> a to launch in your configured backend.

Managed runs and interactive attach

5. Review and merge

Move to REVIEW -> Enter -> approve (a) / reject (x) -> merge (m).

Optional: import existing GitHub issues

Use Quick Actions (Ctrl+Shift+P) and run github import, or use:

kagan import github --repo owner/repo

Shortcuts

? Help · Ctrl+Shift+P Quick Actions · Ctrl+O Projects · Ctrl+R Repositories · Ctrl+, Settings · Ctrl+I AI Panel · Space Chat split · w Workspace (TUI) · Cmd/Ctrl+Shift+W Workspace (web)

Press ? from any screen to open context-aware help. Rare actions (repo sync, GitHub import, AI review) live in Quick Actions.

AI Panel

Ctrl+I toggles the AI Panel. Space cycles split layout while open. Press Esc to close and Ctrl+F to fullscreen it. Or use the standalone REPL:

kagan chat

Type /help for slash commands, /sessions to manage conversations.

Chat guide · ACP session lifecycle

TUI navigation

In the TUI board, Enter is two-step: the first press opens the inspector for the selected card, and the second press opens the full task screen.

Press w to switch from the board to the TUI Workspace screen. That view is orchestrator-first: the left sidebar lists orchestrator conversations, n starts a new session, / filters sessions, x deletes the selected session, and Ctrl+I jumps focus into the chat input. Esc steps back cleanly: from chat to the sidebar, then from the sidebar back to Kanban. The TUI board remains the primary operator surface; Workspace is the conversation companion inside the same client.

Workspace view

Kagan now has orchestrator-first workspace views in both clients:

  • TUI: press w from the board to switch into Workspace. Press w to return directly, or use Esc to step back from search/chat to the sidebar and then back to Kanban.
  • Web: click the Workspace icon in the activity bar or press Cmd/Ctrl+Shift+W for browser-based supervision and planning.

In both clients, the conversation itself is the workspace: you navigate between orchestrator sessions, continue planning in-thread, and treat tasks as outputs of that conversation rather than as separate sidebar chat tabs.

Open the web dashboard from another device

Open the web dashboard from any browser:

kagan web --host 0.0.0.0

Open the URL shown in the terminal from another browser on your network. The bundled dashboard is served directly by kagan web; it does not pair to a separate kagan serve instance. If you specifically need cross-device setup details, see the Remote access guide.

When things break

Startup runs doctor checks silently. If a critical blocker is found, Kagan prints the report and exits.

kagan doctor

Troubleshooting