Skip to content
/
Tier A A16 Cross-vendor router

Kagan

kagan · kagan-sh/kagan · ★ 88 · last commit 2026-05-25

Primitive shape 1 total
MCP tools 1
00

Summary

Kagan — Summary

Slug: kagan
GitHub: https://github.com/kagan-sh/kagan
Stars: 88
License: MIT
Language: Python 3.12+ (Textual TUI), TypeScript (VS Code extension, React web)
Version: 0.11.4-beta.1
Status: Active (last commit 2026-05-25); Discord community

What It Is

Kagan is a Kanban TUI for AI coding agents with a mandatory structural human review gate. It enforces a state machine (BACKLOG → IN_PROGRESS → REVIEW → DONE) where the REVIEW → DONE transition is not automatable. No agent-authored task reaches main branch without explicit human approval.

Core differentiator: "That transition — REVIEW to DONE — cannot be automated away. It is not a setting."

Key Features

  • Textual TUI (primary interface) + React 19 web dashboard + VS Code extension
  • State machine with enforced human merge gate (hardcoded, not configurable)
  • Git worktree isolation per task
  • 14 supported agent backends (Claude Code, Codex, Gemini CLI, OpenCode, Kimi CLI, GitHub Copilot, Goose, OpenHands, Auggie, Amp, Docker cagent, Stakpak, Mistral Vibe, VT Code)
  • MCP server with WORKER/REVIEWER/ORCHESTRATOR role modes
  • SQLite + Alembic migrations for state persistence
  • Interactive launchers: tmux, nvim, vscode, cursor, windsurf, kiro, antigravity
  • kagan attach — interrupt a managed run for interactive session

Architecture Stack

TUI (Textual, Python)
    + MCP server (FastMCP, stdio)
    + API server (Starlette + FastMCP, SSE)
    + SQLite (kagan.db, Alembic migrations)
    + Git worktrees (one per task)
    + Web dashboard (React 19 + jotai + Tailwind CSS 4)
    + VS Code extension (kagan.kagan-vscode)

State Storage

All state stored outside the project repo at ~/.local/share/kagan/ (worktrees, config.toml, kagan.db).

01

Overview

Kagan — Overview

Origin and Positioning

Website: https://kagan.sh
Docs: https://docs.kagan.sh
Discord: discord.gg/dB5AgMwMy

Kagan positions itself as "The Orchestration Layer for AI Coding Agents" — focused on giving operators structured oversight without requiring manual coordination of every step.

The central thesis: AI coding agents are useful but should not be able to merge their own work. Human review before merge is a structural property of the system, not a configuration option.

Core Principle: Mandatory Human Gate

From the README:

"No agent-authored task reaches your main branch without an explicit approval — the state machine enforces it. That transition — REVIEW to DONE — cannot be automated away. It is not a setting."

This is enforced at the state machine level in _transitions.py. The REVIEW → DONE transition is gated behind is_review_approved() — there is no bypass flag.

Target Audience

Developers who want to delegate coding tasks to AI agents but need:

  • Structured visibility into what agents are doing
  • Git isolation (worktrees) so agent work doesn't pollute the working copy
  • Explicit merge control that cannot be accidentally bypassed

Companion Surfaces

The Textual TUI is the primary operator surface. Two optional companions:

  1. Web dashboard (kagan web) — browser-based board for remote access or second monitor
  2. VS Code extension (kagan.kagan-vscode) — sidebar panel, @kagan chat participant, SCM integration

Both companions share the same state via the same API server (SSE streaming).

Agent-Agnostic Design

Kagan does not ship a specific AI model — it supports 14 named agent backends via the ACP (Agent Communication Protocol) streaming interface, with claude-code as the default. Any backend that supports ACP streaming gets full state machine integration; non-ACP backends run in managed detached mode.

Glama Rating

Listed on Glama MCP server registry (glama.ai/mcp/servers/kagan-sh/kagan).

02

Architecture

Kagan — Architecture

Distribution

  • Install: uv tool install kagan or uvx kagan
  • PyPI: kagan (v0.11.4-beta.1)
  • MCP: uvx kagan mcp or registered via kagan serve

Package Structure

kagan/
├── src/kagan/
│   ├── core/                    # Domain layer
│   │   ├── _transitions.py      # State machine (ALL status mutations here)
│   │   ├── _tasks.py            # Task CRUD + audit
│   │   ├── _agent.py            # Backend registry + launcher (14 backends)
│   │   ├── _launchers.py        # tmux, nvim, IDE launchers
│   │   ├── _worktrees.py        # Git worktree lifecycle
│   │   ├── _reviews.py          # is_review_approved() gate
│   │   ├── _db.py               # SQLite engine (SQLModel)
│   │   ├── _prompts.py          # 3-layer prompt resolution
│   │   ├── _verification.py     # Post-agent verification
│   │   ├── _audit.py            # Audit log
│   │   ├── _checkpoints.py      # Session checkpoints
│   │   ├── _compaction.py       # Context compaction handling
│   │   ├── enums.py             # TaskStatus, SessionStatus, AgentRole, TaskType
│   │   ├── models.py            # SQLModel schemas
│   │   ├── transitions.py       # Public transition functions
│   │   ├── adapters/            # Backend adapter normalization
│   │   └── integrations/        # GitHub, (future: Jira/Linear)
│   ├── tui/                     # Textual TUI
│   │   ├── screens/             # Kanban, task detail, settings screens
│   │   ├── widgets/             # Kanban columns, task cards, diff viewer
│   │   └── styles/              # Textual CSS
│   ├── cli/                     # Click CLI
│   │   ├── main.py              # Root Click group
│   │   └── [subcommand modules] # doctor, serve, web, mcp, attach, etc.
│   ├── mcp/                     # MCP server (FastMCP)
│   │   ├── toolsets/            # Per-domain tool sets
│   │   └── prompts/             # MCP prompts
│   ├── server/                  # HTTP + SSE API server (Starlette + FastMCP)
│   │   ├── _routes.py           # REST endpoints
│   │   ├── _event_routes.py     # SSE event channels
│   │   └── responses.py         # Response models → JSON Schema → TypeScript
│   ├── crypto/                  # X25519 key exchange, TLS, tokens, QR
│   └── integrations/            # GitHub, (future: Jira/Linear)
├── packages/
│   ├── vscode/                  # VS Code extension (TypeScript)
│   │   └── src/providers/       # Chat participant, tree view, SCM, reviews
│   └── web/                     # React 19 + jotai + Tailwind CSS 4
├── alembic.ini                  # DB migrations config
└── server.json                  # MCP server registration

Database

  • Engine: SQLite
  • ORM: SQLModel (SQLAlchemy)
  • Migrations: Alembic
  • Location: ~/.local/share/kagan/kagan.db

State Files Location

All state stored OUTSIDE the project repo:

Path Contents
~/.local/share/kagan/kagan.db SQLite: tasks, sessions, projects, audit log
~/.local/share/kagan/worktrees/ Git worktrees for all tasks
~/.local/share/kagan/config.toml User configuration

MCP Server Registration

{
  "name": "io.github.kagan-sh/kagan",
  "packages": [{
    "registryType": "pypi",
    "identifier": "kagan",
    "version": "0.11.4-beta.1",
    "runtimeHint": "uvx",
    "transport": { "type": "stdio" },
    "environmentVariables": [
      {"name": "KAGAN_DB_PATH", "description": "Custom path for Kagan database file"}
    ]
  }]
}

State Machine

Defined in src/kagan/core/transitions.py. All mutations enforced through transition_task() or transition_session(). Direct field assignment outside these functions is explicitly forbidden.

BACKLOG → IN_PROGRESS  (start work)
IN_PROGRESS → REVIEW   (agent done)
IN_PROGRESS → BACKLOG  (agent cancelled / requeue)
REVIEW → IN_PROGRESS   (review rejected / requeue)
REVIEW → BACKLOG       (requeue from review)
REVIEW → DONE          (merge — REQUIRES passing review gate)
DONE → BACKLOG         (requeue completed task)
03

Components

Kagan — Components

CLI Binary: kagan (also kg)

Install: uv tool install kagan

Subcommands

Subcommand Description
kagan (default) Launch Textual TUI
kagan serve Start API server for integrations
kagan web Launch React web dashboard
kagan mcp Start MCP server (stdio)
kagan doctor Preflight checks (all required tools)
kagan attach Interrupt managed run for interactive session
kagan chat CLI chat REPL
kagan update Update kagan
kagan reset Reset project state

MCP Role Mode

kagan mcp --role WORKER       # Provides task execution tools
kagan mcp --role REVIEWER     # Provides review tools
kagan mcp --role ORCHESTRATOR # Provides orchestration tools

Agent Backends (14)

All backends discovered via AGENT_BACKENDS registry in _agent.py:

Backend ID Display Name ACP Support
claude-code Claude Code Yes (ACP streaming)
codex Codex CLI Yes (ACP via npx @zed-industries/codex-acp)
gemini-cli Gemini CLI Yes (gemini --experimental-acp)
opencode OpenCode Yes (opencode acp)
kimi-cli Kimi CLI Yes
github-copilot GitHub Copilot Yes
goose Goose Yes (goose acp)
openhands OpenHands Yes (openhands acp)
auggie Auggie Yes (auggie --acp)
amp Amp Yes (amp acp)
docker-cagent Docker cagent Yes (cagent acp)
stakpak Stakpak Yes (stakpak acp)
mistral-vibe Mistral Vibe Yes
vt-code VT Code Yes

Default: claude-code

Task Type Classification (12 types)

TaskType enum used for analytics and routing:

  • code_implementation, bug_fix, refactoring, documentation, architecture, design, analysis, testing, deployment, investigation, optimization, unknown

Agent Role Enum (3 roles)

AgentRole.WORKER, AgentRole.REVIEWER, AgentRole.ORCHESTRATOR

Used by MCP server to expose role-appropriate tool sets.

Interactive Launchers (7)

Defined in _launchers.py:

Launcher Command Description
tmux launch_tmux() Detached tmux session at worktree
vscode code Open VS Code at worktree
cursor cursor Open Cursor at worktree
windsurf windsurf Open Windsurf at worktree
kiro kiro Open Kiro at worktree
antigravity antigravity Open Antigravity at worktree
nvim nvim Open Neovim at worktree

IDE launchers: vscode, cursor, windsurf, kiro, antigravity (frozenset _IDE_BACKENDS)

Prompt Resolution (3-layer)

Defined in _prompts.py:

  1. Dotfile (~/.kagan/) — user-level customizations
  2. Defaults + behavioral — system defaults with agent behavior rules
  3. Additional instructions — task-specific prompt additions

VS Code Extension (kagan.kagan-vscode)

Published to VS Marketplace and Open VSX.

Features:

  • Sidebar panel (Kagan board view)
  • @kagan chat participant (chat-driven task creation/management)
  • SCM integration (source control manager integration)
  • Review interface

Web Dashboard (kagan web)

  • Tech: React 19 + jotai + Tailwind CSS 4
  • Started by: kagan web command
  • Uses same API server as TUI via SSE streaming
  • Same state as TUI (shared SQLite DB)

Integrations

  • kagan/core/integrations/: GitHub (native), future: Jira, Linear
  • kagan.glama.json: Listed on Glama MCP registry
05

Prompts

Kagan — Prompts and Key Artifacts

State Machine Transition Table (verbatim from transitions.py)

Legal task (from, to) pairs
────────────────────────────
BACKLOG        → IN_PROGRESS  (start work)
IN_PROGRESS    → REVIEW       (agent done)
IN_PROGRESS    → BACKLOG      (agent cancelled / requeue)
REVIEW         → IN_PROGRESS  (review rejected / requeue)
REVIEW         → BACKLOG      (requeue from review)
REVIEW         → DONE         (merge — requires passing review gate)
DONE           → BACKLOG      (requeue a completed task)
ANY            → (same)       n/a — same-status "no-op" calls are rejected

REVIEW → DONE Gate Enforcement (verbatim from transitions.py)

async def transition_task(
    client: KaganCore,
    task_id: str,
    to: TaskStatus,
    *,
    by: str = "system",
) -> Task:
    ...
    if (src, to) == (TaskStatus.REVIEW, TaskStatus.DONE):
        if not await _has_passing_review(client, task_id):
            raise IllegalTransition(src, to)
    elif (src, to) not in _ALLOWED_TASK_TRANSITIONS:
        raise IllegalTransition(src, to)

Agent Backend Registry (verbatim from enums.py)

class AgentRole(StrEnum):
    WORKER = "WORKER"
    REVIEWER = "REVIEWER"
    ORCHESTRATOR = "ORCHESTRATOR"

CLAUDE_CODE_BACKEND: Final = "claude-code"
CODEX_BACKEND: Final = "codex"
GEMINI_CLI_BACKEND: Final = "gemini-cli"
KIMI_CLI_BACKEND: Final = "kimi-cli"
OPENCODE_BACKEND: Final = "opencode"
GITHUB_COPILOT_BACKEND: Final = "github-copilot"

TaskStatus and SessionStatus Enums (verbatim from enums.py)

class TaskStatus(StrEnum):
    BACKLOG = "BACKLOG"
    IN_PROGRESS = "IN_PROGRESS"
    REVIEW = "REVIEW"
    DONE = "DONE"

class SessionStatus(StrEnum):
    PENDING = "PENDING"
    RUNNING = "RUNNING"
    COMPLETED = "COMPLETED"
    FAILED = "FAILED"
    CANCELLED = "CANCELLED"

TaskType Classification Enum (verbatim from enums.py)

class TaskType(StrEnum):
    CODE_IMPLEMENTATION = "code_implementation"
    BUG_FIX = "bug_fix"
    REFACTORING = "refactoring"
    DOCUMENTATION = "documentation"
    ARCHITECTURE = "architecture"
    DESIGN = "design"
    ANALYSIS = "analysis"
    TESTING = "testing"
    DEPLOYMENT = "deployment"
    INVESTIGATION = "investigation"
    OPTIMIZATION = "optimization"
    UNKNOWN = "unknown"

MCP Server Registration (verbatim from server.json)

{
  "name": "io.github.kagan-sh/kagan",
  "title": "Kagan",
  "version": "0.11.4-beta.1",
  "packages": [{
    "registryType": "pypi",
    "identifier": "kagan",
    "runtimeHint": "uvx",
    "transport": { "type": "stdio" },
    "environmentVariables": [
      {"name": "KAGAN_DB_PATH", "description": "Custom path for Kagan database file"}
    ]
  }]
}

Prompt Resolution (3-layer)

From CLAUDE.md: src/kagan/core/_prompts.py

Layer 1: dotfile (~/.kagan/) → user-level prompt customizations
Layer 2: defaults + behavioral → system defaults with agent behavior rules
Layer 3: additional instructions → task-specific additions from task description

Interactive Launcher Backends (verbatim)

_IDE_BACKENDS: frozenset[str] = frozenset(
    {"vscode", "cursor", "windsurf", "kiro", "antigravity"}
)
09

Uniqueness

Kagan — Uniqueness and Positioning

Differs from Seeds

Kagan is the only framework in this batch or the seeds that makes human review a structural property rather than a configuration option. Stoneforge's Steward merges automatically. MartinLoop's verifier gates can pass without human involvement. GreatCTO's gates are enforced by Beads items that a sufficiently determined operator could bypass. Kagan's is_review_approved() check is in the state machine code — bypassing it requires modifying the source.

Versus claude-flow (parallel agent swarm): claude-flow aims for maximum automation. Kagan explicitly de-automates the merge step.

Versus superset (parallel fan-out with 100+ agents): Superset doesn't enforce a merge gate — operators choose to use PRs or not. Kagan enforces it.

Versus taskmaster-ai (task decomposition): Taskmaster tracks tasks but doesn't execute them or manage agent sessions. Kagan manages the full execution lifecycle.

Distinctive Features

  1. Hardcoded human review gate — the only framework reviewed where REVIEW → DONE is structurally impossible without human approval. Enforced in Python source, not configuration.

  2. 14 agent backends — the widest agent backend support in the batch. Most frameworks support 1-3 agents. Kagan supports Claude Code, Codex, Gemini CLI, OpenCode, Kimi CLI, GitHub Copilot, Goose, OpenHands, Auggie, Amp, Docker cagent, Stakpak, Mistral Vibe, VT Code — via ACP streaming protocol.

  3. Textual TUI — the only framework using Textual as primary UI. All others use web dashboards or CLI-only. Textual provides a terminal-native Kanban board with proper keyboard navigation.

  4. Three-surface architecture — TUI + Web + VS Code extension, all sharing state via SSE. Operators can switch surfaces without losing state.

  5. State outside project repo — ~/.local/share/kagan/ stores all state. The project repo is never written to by kagan itself. This is the cleanest isolation of the frameworks reviewed.

  6. kagan attach — the ability to interrupt a managed (background) agent run and join the session interactively is a unique escape hatch. Most frameworks are all-or-nothing.

  7. AgentRole enum (WORKER/REVIEWER/ORCHESTRATOR) suggests a multi-agent design direction: an orchestrator agent managing worker agents, with a reviewer agent running review sessions. This architecture is not fully realized in current releases but is explicitly in the codebase.

Observable Failure Modes

  1. Single review gate bottleneck: With the mandatory human gate, throughput is bounded by operator availability. A queue of 20 REVIEW tasks requires 20 human approvals.

  2. No automated merge path: Teams that want zero-touch deployment for low-risk changes (e.g., dependency bumps, doc updates) cannot use kagan without manual intervention.

  3. 88 stars: Reasonable for a TUI-based tool, but smaller community than web-first frameworks. TUI adoption requires terminal proficiency.

  4. Beta status: v0.11.4-beta.1 — the API and state machine may have breaking changes in upcoming releases.

  5. ACP dependency: Full streaming integration requires ACP-capable backends. Non-ACP backends run in detached mode with less observability.

04

Workflow

Kagan — Workflow

Task Lifecycle

[Create Task]
    │
    ↓ BACKLOG
    │
    ├── Managed run: kagan assigns agent, spawns in worktree
    │
    ↓ IN_PROGRESS (agent working in git worktree)
    │
    ├── Agent finishes → transition_task(task, REVIEW)
    │   OR
    ├── Agent cancelled → transition_task(task, BACKLOG)
    │
    ↓ REVIEW
    │
    ├── Operator reads diff, checks acceptance criteria
    │
    ├── Approve → is_review_approved() → transition_task(task, DONE) → merge fires
    │   OR
    ├── Reject → transition_task(task, IN_PROGRESS) [requeue]
    │   OR
    └── Requeue → transition_task(task, BACKLOG)
    
    ↓ DONE (merged to main)

CRITICAL: REVIEW → DONE Gate

The REVIEW → DONE transition is the only non-automatable transition in the system.

From transitions.py source:

REVIEW → DONE  # merge — requires passing review gate

is_review_approved() is called in transition_task() for the REVIEW → DONE path. There is no --skip-review flag, no force_approve=True parameter, no agent role that bypasses this check.

Session Lifecycle

For each task, the agent runs in a "Session":

PENDING → RUNNING → COMPLETED  (happy path)
PENDING → FAILED
PENDING → CANCELLED
RUNNING → FAILED
RUNNING → CANCELLED

Sessions map to: PENDING/RUNNING = task IN_PROGRESS; COMPLETED = task moves to REVIEW.

Managed vs Interactive Runs

Managed Run (background agent)

# TUI assigns agent, spawns in worktree, manages lifecycle
kagan  # TUI: select task → press run

Interactive Attach

kagan attach  # Interrupt managed run for interactive session

Opens a tmux/IDE session in the task's worktree where operator and agent collaborate directly.

Git Worktree Isolation

Each task gets its own git worktree:

  • Location: ~/.local/share/kagan/worktrees/<task-id>/
  • Branch: created by kagan, tracked in kagan.db
  • Cleanup: worktree removed after task reaches DONE (merge) or is cancelled

The working copy is never touched by agents — all agent work happens in the isolated worktree.

Phase Table

Phase State Who Acts Artifact
Task creation BACKLOG Operator Task record in kagan.db
Agent start IN_PROGRESS Kagan + Agent Git worktree + session record
Agent working IN_PROGRESS Agent File changes in worktree
Agent complete → REVIEW Kagan Session COMPLETED, diff ready
Human review REVIEW Operator Diff inspection, acceptance check
Approve → DONE Operator only Merge to main, worktree cleanup

Doctor Preflight

kagan doctor

Checks: Python version, uv available, git available, agent backend on PATH, MCP config valid, DB migration state.

06

Memory Context

Kagan — Memory and Context

Primary State Store

SQLite (kagan.db) with Alembic migrations.

Location: ~/.local/share/kagan/kagan.db

Note: ALL state is stored OUTSIDE the project repo. Kagan explicitly avoids polluting the working copy.

Tables (inferred from models.py + CLAUDE.md)

Table Contents
Tasks Task records (title, status, description, type, priority, project_id)
Sessions Agent session records (backend, status, started_at, ended_at, agent_role)
Projects Project records (linked to repos)
Reviews Review verdicts (acceptance criteria pass/fail)
Events Agent lifecycle events (agent_started, agent_finished, agent_stopped)
Audit Task audit trail (status transitions with actor + timestamp)

Checkpoints

_checkpoints.py — session checkpoints for resumability. If an agent session is interrupted, kagan can resume from the last checkpoint.

Context Compaction Handling

_compaction.py — kagan handles context compaction events from agent backends. When an ACP-streaming agent signals context compaction, kagan can inject a context summary to maintain continuity.

Cross-Session Persistence

All task state, session history, and review verdicts persist across kagan restarts. SQLite database is the durable store.

Agent Context

Each agent receives context via:

  1. Task description (from task record in DB)
  2. .mcp.json written to the worktree at session start (kagan writes this to configure the agent's MCP access)
  3. 3-layer prompt resolution (dotfile → behavioral defaults → task-specific)

Git Worktrees

Worktrees stored at: ~/.local/share/kagan/worktrees/<task-id>/

Each worktree is an isolated git worktree on a dedicated branch. The main working copy is never modified. Worktrees are cleaned up after DONE or CANCELLED.

Cross-Agent Memory

No dedicated cross-agent memory mechanism. Kagan is not a multi-agent system — it runs one agent per task. Cross-task context is implicit via the shared codebase (since all worktrees branch from the same repo).

Audit Trail

_audit.py — records every task status transition with:

  • Actor (by parameter, defaults to "system")
  • Timestamp (UTC)
  • From status / To status
  • Task ID

Stored in SQLite (not an append-only external log file).

07

Orchestration

Kagan — Orchestration

Pattern

Serial task queue with mandatory human merge gate. Kagan queues tasks and assigns one agent per task. It is NOT a parallel multi-agent system — each task runs independently in its own worktree, but there is no agent-to-agent coordination.

Orchestration pattern: single-agent-per-task (queued serial, not hierarchical)

Agent Assignment

The TUI operator selects a task from BACKLOG and triggers a run. Kagan:

  1. Creates a git worktree for the task
  2. Writes .mcp.json to the worktree
  3. Spawns the configured agent backend (default: claude-code)
  4. Monitors the ACP stream (if backend supports it)
  5. Transitions task to REVIEW when session COMPLETED

Multi-Agent Capability

The MCP server supports 3 role modes (WORKER/REVIEWER/ORCHESTRATOR), suggesting multi-agent use is intended but not yet the primary design:

kagan mcp --role WORKER       # Worker agent: execute tasks
kagan mcp --role REVIEWER     # Reviewer agent: review completed work
kagan mcp --role ORCHESTRATOR # Orchestrator agent: manage board

An ORCHESTRATOR agent could theoretically assign WORKER agents and a REVIEWER agent could run the review gate — but the current design's REVIEW → DONE gate still requires human approval (the is_review_approved() check runs regardless of who calls transition_task).

Concurrent Agents

Multiple tasks can be IN_PROGRESS simultaneously. Each has its own worktree and session. There is no coordination between concurrent agents — they work on different tasks in different branches.

Approval Gate (The Core Differentiator)

One mandatory human gate: REVIEW → DONE transition.

Enforced in transition_task() via _has_passing_review():

  • Calls is_review_approved(task_id, engine)
  • If acceptance criteria not yet passed → raises IllegalTransition
  • No bypass parameter, no force flag, no agent role that bypasses this

This is structurally enforced at the state machine layer, not at the UI layer. Even if an operator creates an MCP tool call to transition_task(task, DONE), it will raise IllegalTransition if the review gate hasn't passed.

Isolation Mechanism

Git worktrees: one per task. The main working copy is never touched. Worktrees are at ~/.local/share/kagan/worktrees/<task-id>/.

Consensus Mechanism

None. Single human reviewer per task. No quorum, no multi-reviewer protocol.

Audit Trail

SQLite audit records for every status transition (_audit.py). Not JSONL, not append-only external file — stored in the SQLite DB with actor, timestamp, from/to status.

Prompt Chaining

No prompt chaining between tasks. Each task's agent is initialized fresh with:

  1. Task description from DB
  2. Worktree context (existing code)
  3. 3-layer prompt resolution (dotfile → behavioral → task-specific)
08

Ui Cli Surface

Kagan — UI and CLI Surface

Primary Surface: Textual TUI

Detail Value
Framework Textual (Python)
Launch kagan or kg
Screens Kanban board, task detail, settings
Widgets Kanban columns (BACKLOG/IN_PROGRESS/REVIEW/DONE), task cards, diff viewer

The TUI is the primary operator interface. All other surfaces (web, VS Code) are optional companions that share the same state via the API server.

Web Dashboard

Detail Value
Launch kagan web
Tech React 19 + jotai + Tailwind CSS 4
Access Browser (local or remote)
State Same SQLite DB via API server + SSE
Use case Remote access or second monitor while TUI is primary

VS Code Extension (kagan.kagan-vscode)

Detail Value
Marketplace VS Marketplace + Open VSX
Extension ID kagan.kagan-vscode
Features Sidebar board panel, @kagan chat participant, SCM integration, review interface
State Same API server via SSE

@kagan Chat Participant

Allows task creation and management via VS Code chat (@kagan create task: fix auth bug).

API Server

Detail Value
Framework Starlette + FastMCP
Launch kagan serve
Protocol REST + SSE (Server-Sent Events)
State Shared SQLite DB

All companion surfaces (web, VS Code) connect to the API server. The TUI can run in-process or connect to a remote server.

MCP Server

Detail Value
Launch kagan mcp
Protocol stdio (MCP 2025-12-11)
Role modes WORKER, REVIEWER, ORCHESTRATOR
Registry glama.ai/mcp/servers/kagan-sh/kagan
Claude Code install claude mcp add --transport stdio kagan -- uvx kagan mcp

CLI Reference

kagan           # Launch TUI
kagan web       # Launch web dashboard
kagan serve     # Start API server
kagan mcp       # Start MCP server (stdio)
kagan mcp --role WORKER       # Worker role
kagan mcp --role REVIEWER     # Reviewer role
kagan mcp --role ORCHESTRATOR # Orchestrator role
kagan doctor    # Preflight checks
kagan attach    # Attach to managed run interactively
kagan chat      # CLI chat REPL
kagan update    # Update kagan
kagan reset     # Reset state

Interactive Launchers

From task view in TUI, operator can launch an interactive session:

# tmux session at worktree
# vscode / cursor / windsurf / kiro / antigravity — IDE at worktree
# nvim — Neovim at worktree

CLAUDE.md

Present at repo root. Key for agent contributors:

  • src/kagan/core/_transitions.py — state machine (all status mutations here)
  • src/kagan/core/_agent.py — AGENT_BACKENDS registry
  • alembic -c alembic.ini revision --autogenerate — DB migration
  • Wire protocol change: src/kagan/server/responses.py → generates TypeScript types

Related frameworks

same archetype · same primary tool · same memory type

CodeMachine CLI ★ 2.5k
A16 Cross-vendor router

JavaScript-DSL workflow orchestration engine that captures repeatable AI coding agent workflows with tracks, condition groups,…

Codexia ★ 690
A16 Cross-vendor router

Tauri desktop app providing visual control plane, task scheduler, git worktree manager, and headless REST API for Codex CLI +…

oh-my-claudecode (Yeachan-Heo) ★ 35k
A16 Cross-vendor router

Zero-learning-curve teams-first multi-agent orchestration for Claude Code with autopilot (6-phase lifecycle), ralph (PRD-driven…

Paseo ★ 6.8k
A16 Cross-vendor router

Multi-provider AI coding agent orchestration daemon with cross-device access (phone/desktop/CLI) and git worktree isolation.

CCG Workflow ★ 5.4k
A16 Cross-vendor router

Routes Claude + Codex + Gemini to task-appropriate collaboration strategies (direct-fix through full-collaborate) with hook-based…

CCS (Claude Code Switch) ★ 2.4k
A16 Cross-vendor router

Routes Claude Code tasks to the optimal AI agent (Codex, Factory Droid, Ollama, Claude) based on configurable cost/capability…