# 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

```bash
pip install claude-agentboard
```

Requires Python 3.10+.

## Quick start

```bash
# 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:

```bash
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:
   ```bash
   git clone https://github.com/YOUR_USERNAME/agentboard.git
   cd agentboard
   ```
3. Install in development mode:
   ```bash
   pip install -e .
   ```
4. Initialize a test board:
   ```bash
   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
