# Tokanban

> Agent-first task management and durable memory for development teams. MCP server, REST API, and CLI designed for AI coding agents as the primary interface.

## What is Tokanban

Tokanban is a task management and durable memory platform where AI agents are first-class participants. Agents write through MCP server, REST API, or CLI, while the Web UI gives humans a read-first dashboard for project visibility. Every write is serialized per project for consistency. Agents authenticate with scoped keys and get full activity attribution. Agent memory stores facts, decisions, session chronicles, continuation prompts, and provenance across projects and working directories.

- Website: https://tokanban.com
- Web UI overview: https://tokanban.com/web-ui
- API: https://api.tokanban.com
- MCP endpoint: https://api.tokanban.com/mcp
- Dashboard: https://app.tokanban.com/dashboard

## Install the CLI

```sh
curl -fsSL https://app.tokanban.com/install.sh | sh
```

Or with Cargo: `cargo install tokanban`

## Authenticate

```sh
tokanban auth login          # Opens browser for OAuth
tokanban auth status         # Verify credentials
tokanban project list        # Discover projects
tokanban project set PLAT    # Set default project
```

Credentials are stored at `~/.config/tokanban/config.toml`.

## MCP Server Setup

The MCP server is a remote HTTP endpoint. No local process required.

### Claude Code

Add to `~/.claude.json` under the project's `mcpServers`:

```json
{
  "tokanban": {
    "type": "url",
    "url": "https://api.tokanban.com/mcp",
    "headers": {
      "Authorization": "Bearer <your-api-key>"
    }
  }
}
```

### Cursor / Other MCP Clients

Use the same URL and Bearer token in your MCP client configuration.

### Getting an API Key

```sh
tokanban agent create "My Agent" --scopes "tasks:read,tasks:write,projects:read"
```

The key is shown once at creation. Store it securely.

## CLI Quick Reference

```sh
# Tasks
tokanban task create "Title" --priority high --assignee username
tokanban task list --status in_progress --limit 50
tokanban task view PLAT-42
tokanban task update PLAT-42 --status in_progress --description "Details"
tokanban task search "auth bug" --project PLAT
tokanban task close PLAT-42 --reason "Fixed in PR #42"

# Projects
tokanban project list
tokanban project create "My Project" --key_prefix PROJ

# Comments
tokanban comment add PLAT-42 "Implementation note"
tokanban comment list PLAT-42

# Project entities: DEC decisions, FND findings, REQ requirements
tokanban entity create DEC "Use ProjectDO for project knowledge" --project PLAT
tokanban entity create FND "OAuth callback failed on apex host" --project PLAT --memory-ref <memory-id>
tokanban entity create REQ "Admins can inspect platform signups" --project PLAT --related PLAT-42
tokanban entity list --project PLAT --kind REQ --format table

# Sprints
tokanban sprint list --project PLAT
tokanban sprint create --name "Sprint 1" --start 2026-04-14 --end 2026-04-28

# Agent keys
tokanban agent create "CI Bot" --scopes "tasks:read,tasks:write"
tokanban agent list
tokanban agent rotate <agent-id>

# Memory candidate helpers
tokanban memory score --input '{"content":"Important project fact","kind":"fact"}'
tokanban memory candidate add --input '{"content":"Investigate this later","kind":"scratch"}' --project-id <project-id> --working-directory /path/to/repo
tokanban memory candidate review --project-id <project-id> --working-directory /path/to/repo
```

## Tips

- Use `--format json` for structured output that pipes well: `tokanban task list --format json | jq '.items[].title'`
- Set a default project with `tokanban project set PLAT` to avoid repeating `--project` on every command
- Durable project entities are exposed through CLI and MCP as `create_project_entity`, `list_project_entities`, `get_project_entity`, `update_project_entity`, and `delete_project_entity`
- Durable memory reads and writes are exposed through MCP tools such as `session_start`, `memory_relevant_now`, `memory_create_fact`, `memory_create_decision`, `memory_search`, and `session_end`
- Agent keys support scope intersection: an agent with `tasks:read,tasks:write` in a `member` role can only do what both allow
- Every mutating API call accepts an `Idempotency-Key` header for safe retries
- Resources carry ETags for optimistic concurrency (`If-Match` header on PATCH)
- Agent memory is partitioned by project and working directory so relevant facts, decisions, and session chronicles follow the active work context
- Status transitions follow an explicit state machine: backlog -> todo -> in_progress -> in_review -> done
- Priority values: `urgent`, `high`, `medium`, `low`, `none` (case-insensitive, aliases like `p0`, `p1` also work)