agkan

A lightweight CLI & Kanban board for humans and AI coding agents to get things done together.

Features

Task Management

• Simple, intuitive CLI backed by local SQLite storage
• 7-status Kanban workflow: icebox, backlog, ready, in_progress, review, done, closed
• Create tasks from CLI arguments or Markdown files; filter by status, author, or tag
• Color-coded terminal output

Dependencies

• Parent-child relationships with tree view (task list --tree)
• Blocking relationships with automatic circular-reference detection
• Tag system for classifying and searching tasks

Kanban Board

• Local, zero-config web UI (agkan board)
• Filter and browse tasks by status, tag, or author in the browser
• Task detail panel with full task history and Claude run logs

AI Integration

• Machine-readable JSON output on key commands for scripting and automation
• Companion agkan-skills package for Claude Code
• Run Claude directly from the board, with live streaming output and run history
• agkan init installs a SessionStart hook so Claude Code loads agkan context automatically each session

Quick Start

Go from zero to a running Kanban board in five steps.

1. Install

npm install -g agkan

Requires Node.js 20+ and npm. To install the latest code directly from GitHub instead:

npm install -g https://github.com/gendosu/agkan.git

2. Initialize your project

agkan init

Created: .agkan.yml
Created: .agkan/ directory
Created: .claude/settings.local.json (added agkan SessionStart hook)

3. Create a task

agkan task add "Implement login feature" "Implement user authentication system"

✓ Task created successfully

ID: 1
Title: Implement login feature
Status: backlog
Created: 2026/7/10 15:02:48

4. List tasks

agkan task list

Found 1 task(s):

────────────────────────────────────────────────────────────────────────────────

[1] Implement login feature
  Status: backlog
  Priority: medium
  Created: 2026/7/10 15:02:48

5. Open the Kanban board

agkan board

Server is running on http://localhost:8080

Need a different port? agkan board -p 3000.

Command Cheat Sheet

Every command also accepts --help for its own usage details.

Command	Description
agkan init	Initialize .agkan.yml and the .agkan/ data directory
agkan task add <title> [body]	Create a task (--status, --author, --parent, --tag, --file, --json)
agkan task list	List tasks (--tree, --root-only, --status, --author, --tag, --json)
agkan task find <keyword>	Search tasks by title/body (--all includes done/closed)
agkan task get <id>	Show task details
agkan task update <id> <field> <value>	Update a task's status, title, body, or author
agkan task update-parent <id> <parent-id>	Set or clear (null) a task's parent
agkan task delete <id>	Delete a task
agkan task block add <id> <id2>	Mark <id> as blocking <id2>
agkan task block remove <id> <id2>	Remove a blocking relationship
agkan task block list <id>	Show what a task blocks and is blocked by
agkan task meta set <id> <key> <value>	Set a metadata value on a task (e.g. priority)
agkan task meta get <id> <key>	Get a metadata value from a task
agkan task meta list <id>	List all metadata for a task
agkan task meta delete <id> <key>	Delete a metadata value from a task
agkan task count	Count tasks by status (--status, --json)
agkan tag add <name>	Create a tag
agkan tag list	List all tags with task counts
agkan tag delete <name>	Delete a tag
agkan tag attach <task-id> <tag>	Attach a tag to a task
agkan tag detach <task-id> <tag>	Detach a tag from a task
agkan tag show <task-id>	List tags attached to a task
agkan board	Start the local Kanban board web UI
agkan ps	List currently running Claude processes
agkan config get [key]	Show resolved configuration values
agkan --help	Show all commands

For full options, JSON output formats, and worked examples, see documentation/cli-reference.md.

Claude Code Integration

agkan is designed to be driven by AI coding agents as well as humans:

• agkan-skills — Claude Code skills for automated task execution, planning, and review
• Run / Plan: each task card in the board has a "Run" button that launches claude for that task, with a dropdown to run in plan mode instead
• Stream modal: while Claude is running, a modal shows the live output stream in real time, with a "Stop" button and a header indicator for active processes
• Run Logs: the task detail panel's "Run Logs" tab keeps the full history of past Claude executions, with timestamps and output
• agkan ps: from any terminal, list which Claude processes the board currently has running and which tasks they belong to

Configuration

Customize the database location and board via a .agkan.yml file in your project root:

path: ./.agkan/data.db

board:
  port: 8080

The database path can also be overridden with the AGENT_KANBAN_DB_PATH environment variable, which takes priority over .agkan.yml.

In test mode (NODE_ENV=test), agkan automatically isolates data using .agkan-test.yml and .agkan-test/ instead, so tests never touch your real task database.

See documentation/configuration.md for the full reference, including per-project setup, model selection, and permission modes.

Task Statuses

Every task moves through one of seven statuses:

Status	Meaning
icebox	Frozen, not actively being considered
backlog	Not yet started
ready	Ready to be started
in_progress	Currently being worked on
review	Under review
done	Completed
closed	Closed

Documentation

Detailed reference material lives outside this file:

Document	Description
documentation/cli-reference.md	Full command reference, options, and JSON output formats
documentation/configuration.md	.agkan.yml reference (paths, board, models, permission mode)
documentation/project-structure.md	Repository directory layout
documentation/database-schema.md	SQLite schema reference
documentation/development.md	Technology stack, local setup, and build information
documentation/TESTING.md	Testing guide
CONTRIBUTING.md	How to contribute
CHANGELOG.md	Release history

License

ISC

Author

GENDOSU