# Kagan

Kagan is a Claude Code MCP server orchestrating autonomous development tasks through kanban flows and isolated git worktrees. Isolates agent edits without touching your main directory.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 5 repo stars
- Author: kagan-sh
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/kagan-sh/kagan
- Updated: 2026-11-17
- Security check: automated, 2026-11-17 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/mcp/kagan

## What it does

Kagan runs an AI-assisted development workspace with thread orchestration and kanban mechanics. When pointed at a git repository, each workflow thread operates inside a dedicated `git worktree`. Your primary project folder remains untouched throughout the session. Security boundaries prevent agents from deleting threads, and plugins stay inactive until approved manually.

Telemetry is absent, and the software functions without requiring user accounts. Application state lives locally in `~/.kagan` on macOS and Linux, or `%USERPROFILE%\.kagan` on Windows. Background update checks stay disabled until turned on by the user.

Running the MCP entry point with `uvx` depends on valid API keys in `KAGAN_OPENAI_API_KEY` and `KAGAN_ANTHROPIC_API_KEY`, plus a configured `KAGAN_DB_PATH`. Kagan can also be installed as a standalone desktop binary named `kg` via Homebrew, prebuilt binaries, or Rust source compilation.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `KAGAN_OPENAI_API_KEY`, `KAGAN_ANTHROPIC_API_KEY`, `KAGAN_DB_PATH` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env KAGAN_OPENAI_API_KEY=<KAGAN_OPENAI_API_KEY> --env KAGAN_ANTHROPIC_API_KEY=<KAGAN_ANTHROPIC_API_KEY> --env KAGAN_DB_PATH=<KAGAN_DB_PATH> --transport stdio kagan -- uvx kagan
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from kagan <command>

### Codex

**Platform CLI**
```bash
codex mcp add kagan --env KAGAN_OPENAI_API_KEY=<KAGAN_OPENAI_API_KEY> --env KAGAN_ANTHROPIC_API_KEY=<KAGAN_ANTHROPIC_API_KEY> --env KAGAN_DB_PATH=<KAGAN_DB_PATH> -- uvx kagan
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from kagan <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "kagan": {
            "command": "uvx",
            "args": [
                "kagan"
            ],
            "env": {
                "KAGAN_OPENAI_API_KEY": "<KAGAN_OPENAI_API_KEY>",
                "KAGAN_ANTHROPIC_API_KEY": "<KAGAN_ANTHROPIC_API_KEY>",
                "KAGAN_DB_PATH": "<KAGAN_DB_PATH>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from kagan <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "kagan": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "kagan"
            ],
            "env": {
                "KAGAN_OPENAI_API_KEY": "<KAGAN_OPENAI_API_KEY>",
                "KAGAN_ANTHROPIC_API_KEY": "<KAGAN_ANTHROPIC_API_KEY>",
                "KAGAN_DB_PATH": "<KAGAN_DB_PATH>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from kagan <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e KAGAN_OPENAI_API_KEY=<KAGAN_OPENAI_API_KEY> -e KAGAN_ANTHROPIC_API_KEY=<KAGAN_ANTHROPIC_API_KEY> -e KAGAN_DB_PATH=<KAGAN_DB_PATH> kagan uvx kagan
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from kagan <command>

## When to use it
- isolate agent modifications into dedicated git worktrees
- track AI coding jobs via structured kanban threads
- restrict unapproved tool executions during agent runs
- keep workspace state stored locally without telemetry

## Example prompts
- List all active task threads from Kagan
- Start a new development thread in a separate git worktree
- Check file modifications across Kagan project branches

## Similar
- [paseo-handoff](https://affpapa.org/en/nevibecode/skills/paseo-handoff.md) — skill · 5600 installs
- [yylo](https://affpapa.org/en/nevibecode/plugins/yylo.md) — plugin · ★ 1596 repo stars
- [board](https://affpapa.org/en/nevibecode/plugins/board.md) — plugin · ★ 1596 repo stars
- [orchestrate](https://affpapa.org/en/nevibecode/skills/hyperb1iss-orchestrate.md) — skill · 669 installs
- [Fjord](https://affpapa.org/en/nevibecode/mcp/fjord.md) — MCP server · ★ 5 repo stars
- [om-auto-create-pr](https://affpapa.org/en/nevibecode/skills/om-auto-create-pr.md) — skill · 4700 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
