# Quickstart — agent-kanban in 5 minutes

End-to-end path: clone → run → AI agent picks up an Approved task on its own.
If you don't need AI, skip Part 2 and use it as a regular kanban board.

## Part 1 — Basic kanban (2 minutes)

### Requirements

- Python 3.12+
- macOS / Linux (Windows — via WSL2)
- A browser for the UI

### Install uv (once, ~5 sec)

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh   # or: brew install uv
```

### Clone + run

```bash
git clone https://github.com/<user>/agent-kanban.git
cd agent-kanban
uv run python -m kanban_ui     # auto-creates .venv, installs deps, runs
# open http://localhost:7777
```

That's it — one command from clone to a running UI on `localhost:7777`. `uv` creates `.venv/`, installs the dependencies from `pyproject.toml` (cached after the first run), and starts the server.

<details>
<summary>Legacy pip / venv path (no uv)</summary>

```bash
python3.12 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python -m kanban_ui
```

`requirements.txt` is kept in sync with `pyproject.toml`. The pip path is supported indefinitely — uv is just the faster default.

</details>

A `default` project shows up in the sidebar with an empty board and 9 columns.
Hit `+ Task` (or press `n`) and create your first card.

### macOS auto-start (optional)

```bash
bash scripts/install_launchd.sh install
# kanban now starts on login; status: scripts/install_launchd.sh status
```

Logs: `~/Library/Logs/agent-kanban/{stdout,stderr}.log`.

---

## Part 2 — AI agent picks up tasks itself (3 minutes)

The flow: you drag a card from "Backlog" to "Approved", and **Claude Code**
(or any other agent) automatically:
1. Claims the task (`approved → analyst`),
2. Posts a plan as a comment,
3. Moves it to `in_progress` and implements,
4. Moves it to `testing` with a comment "ready for review".

All you have to do is review the result and click "Accept".

### Step 1 — create a kanban project and bind it to your code directory

In the UI:
- `+ New project` → name, slug (e.g. `myproj`).
- "Choose…" button in the "Project directory" field → native Finder dialog.
  Pick the directory of your Claude Code project (e.g. `~/code/myproj`).

### Step 2 — connect the kanban MCP server to the project

Leave "Connect Claude Code" ticked in the project dialog, or run:

```bash
.venv/bin/python -m kanban_mcp.connect ~/code/myproj --project myproj
```

Either way you get a `.mcp.json` at the root of the code directory (other
MCP servers in it are kept) and a "Kanban board" block in its `CLAUDE.md`
with the workflow rules for agents. The generated entry looks like this:

```jsonc
{
  "mcpServers": {
    "agent-kanban": {
      "type": "stdio",
      "command": "/abs/path/to/agent-kanban/.venv/bin/python",
      "args":    ["-m", "kanban_mcp"],
      "cwd":     "/abs/path/to/agent-kanban",
      "env": {
        "PYTHONPATH": "/abs/path/to/agent-kanban",
        "KANBAN_DB":  "/abs/path/to/agent-kanban/tasks.db",
        "KANBAN_PROJECT_ID": "myproj",
        "KANBAN_ACTOR": "claude"
      }
    }
  }
}
```

Heads up if you write it by hand: `PYTHONPATH` is required — without it
Claude ignores `cwd` and won't find the `kanban_mcp` module.

Verify the connection:
```bash
claude mcp list
# should show: agent-kanban: ... ✓ Connected
```

### Step 3 — log into Claude CLI (one-time)

```bash
claude auth login --claudeai
```

A browser opens with OAuth. After you finish, the `C` button in the kanban
topbar turns orange and tooltips read "Claude CLI: logged in".

### Step 4 — add an auto-launch rule

Create `kanban_data/rules.json`:

```json
{
  "rules": [
    {
      "name": "Auto-launch Claude on approved",
      "enabled": true,
      "trigger": {
        "type": "task_moved",
        "to_status": "approved",
        "project_id": "myproj"
      },
      "action": {
        "type": "run_command",
        "cmd": "/abs/path/to/agent-kanban/examples/agent-launcher/launch-claude.sh",
        "args": ["{task_id}", "{project_id}"],
        "log_file": "/Users/<you>/Library/Logs/agent-kanban/launcher.log",
        "max_concurrent": 1,
        "max_runs": 3
      }
    }
  ]
}
```

`max_concurrent: 1` — one agent at a time; more cards dragged to Approved
wait in a queue. `max_runs: 3` — a card that keeps coming back is blocked
after three launches instead of burning your usage limit overnight.
The launcher passes the kanban MCP server to `claude` itself
(`--mcp-config`), so the name in your `.mcp.json` does not matter.
Hot-reload by mtime — no server restart needed.

### Step 5 — try it

1. Create a task with a clear description (`+ Task` or `n`):
   - Title: "Add /api/health endpoint"
   - Description: `GET /api/health → 200 {"status":"ok","ts":...}`
   - Acceptance: `curl localhost:7777/api/health returns 200`
2. Drag it to **Approved** (or press space on the card).
3. Within a few seconds the card shows `▶ agent` and Claude moves it to `analyst`. A minute or two later → `testing`.
4. Run folder with the prompt, the agent's output and the launcher log: `~/Library/Logs/agent-kanban/runs/T-XXX/`.
5. If something goes wrong (no login, timeout, the agent quit halfway), the card lands in **Blocked** with the reason in its history.

---

## What's next

- [`README.md`](README.md) — features, env vars, project layout
- [`docs/USECASES.md`](docs/USECASES.md) — 11 scenarios (solo dev, team Slack, legacy import, multi-project, ...)
- [`docs/INTEGRATION.md`](docs/INTEGRATION.md) — Claude Code, Cline, opencode, Open WebUI, any function-calling LLM
- [`examples/agent-launcher/`](examples/agent-launcher/) — launcher scripts for Claude Code and other agents
- [`examples/llm-tool-calling/`](examples/llm-tool-calling/) — Python demos for OpenAI SDK / Ollama / curl
- Slack/Telegram/generic webhooks — `kanban_data/webhooks.json`, see [INTEGRATION.md](docs/INTEGRATION.md#outbound-webhooks-slack--telegram--generic)
- OpenAPI 3.1: [`docs/openapi.yaml`](docs/openapi.yaml), live `/docs`

## Troubleshooting

| Symptom | Where to look |
|---|---|
| `claude mcp list` → `Failed to connect` | re-run `python -m kanban_mcp.connect <dir> --project <id>`; by hand: `PYTHONPATH` in `.mcp.json` must point at the agent-kanban root |
| Card went to **Blocked** with `launcher: …` | the comment says why (not logged in, timeout, agent left the card behind); details in `~/Library/Logs/agent-kanban/runs/T-XXX/` |
| Card sits in Approved, nothing runs | ⏸ in the top bar is amber → automation is paused; otherwise see `rules.last_errors` in `/api/automation/status` |
| Agent: "'done' is reserved for a human" | by design — agents stop at `testing`; see `KANBAN_MCP_HUMAN_ONLY` |
| `C` button in topbar is grey | not logged in — clicking it kicks off the OAuth flow in your browser |
| Drag-drop works but webhooks are silent | check the syntax of `kanban_data/webhooks.json`; status: `/api/automation/status.webhooks` |
| Board feels slow, DB is large | `python -m kanban_store.maintenance doctor` |

All event logs and errors are exposed at `GET /api/automation/status` (JSON).

## License

MIT — see [LICENSE](LICENSE).