Agentboard

A bidirectional kanban board for AI agents and humans. Both sides read and write the same .agentboard/board.json file, with a live web UI that syncs in real-time.

No database, no external services, just a JSON file.

Install

pip install claude-agentboard

Requires Python 3.10+.

Quick start

# Initialize a board in your project
cd your-project
agentboard init

# Open the web UI (default: http://127.0.0.1:5555)
agentboard

The board file lives at .agentboard/board.json. Add it to version control or .gitignore, your call.

How it works

Human (browser)  <-->  board.json  <-->  AI agent (filesystem)

• The agent reads and writes .agentboard/board.json directly
• The web server polls the file every second and pushes changes to the browser via SSE
• User changes in the UI are posted back to the server, which writes to the same file
• Tasks can be assigned to human or agent for clear ownership

CLI

Command	Description
agentboard	Start the web UI (default)
agentboard init	Create .agentboard/board.json in the current directory
agentboard status	Print task counts per column
agentboard add "title"	Add a task

Options for agentboard add

• --column: backlog (default), todo, in_progress, done
• --tag: feature, bug, chore, docs, test, design
• --priority: high, medium, low
• --assign: human, agent

Options for agentboard serve

• --host: Host to bind to (default: 127.0.0.1)
• --port: Port to bind to (default: 5555, auto-increments if taken)
• --no-open: Don't open browser automatically

Claude Code Integration

Copy the skill file to make Claude Code aware of the board:

mkdir -p ~/.claude/skills/agentboard
cp skill/SKILL.md ~/.claude/skills/agentboard/SKILL.md

The skill teaches the agent to:

• Read the board before writing to avoid overwriting user changes
• Move tasks through columns as it works (backlog -> in_progress -> done)
• Pick up tasks assigned to agent by the user
• Assign tasks back to human when manual action is needed (reviews, decisions, testing)

Web UI Features

• Drag and drop cards between columns
• Double-click cards to edit title, description, tag, priority, and assignment
• Add tasks via the input at the bottom of the Backlog column
• Live updates when the agent modifies the board file
• Connection status indicator
• Light/dark mode

Board Schema

Tasks have these fields:

Field	Type	Description
id	string	Unique identifier (e.g., t_a1b2c3d4)
title	string	Short imperative description
description	string	Optional longer description
tag	string	feature, bug, chore, docs, test, design
priority	string	high, medium, low, or null
assigned_to	string	human, agent, or null
column	string	backlog, todo, in_progress, done
created_by	string	agent or user

Contributing

Contributions are welcome. Here's how to get started:

1. Fork the repository
2. Clone your fork:

   git clone https://github.com/YOUR_USERNAME/agentboard.git
   cd agentboard

3. Install in development mode:

   pip install -e .

4. Initialize a test board:

   agentboard init --project test
   agentboard

5. Make your changes and test them
6. Submit a pull request

Guidelines

• Keep the core simple. The whole point is a JSON file, not a database.
• The web UI is a single HTML file with no build step. Keep it that way.
• Python 3.10+ only, no dependencies beyond click.
• Write clear commit messages.

Ideas for contributions

• Filtering and search in the UI
• Keyboard shortcuts
• Task archiving
• Export/import
• Additional agent integrations beyond Claude Code

License

MIT