┌─────────────────────────────┐
 │        agentboard           │
 │  collaborative kanban tui   │
 └─────────────────────────────┘

Real-time collaborative Kanban board for AI coding agents. Terminal-native. Agent-agnostic.

Prerequisites

Prerequisite	Version	Purpose
tmux	3.0+	Agent session management
gh CLI	2.0+	GitHub authentication
AI CLI tool	any	Claude Code, Cursor, Antigravity, etc.

Note: tmux is only required for spawning work agents. The TUI and task enrichment work without tmux.

Platform: macOS and Linux are fully supported. Windows requires WSL.

Installation

Quick install (recommended)

curl -fsSL https://raw.githubusercontent.com/markx3/agentboard/main/install.sh | bash

Or if you prefer to inspect the script first:

curl -fsSL https://raw.githubusercontent.com/markx3/agentboard/main/install.sh -o install.sh
less install.sh
bash install.sh

Other methods

# Via go install (requires Go 1.25+)
go install github.com/markx3/agentboard/cmd/agentboard@latest

# Or build from source
git clone https://github.com/markx3/agentboard.git
cd agentboard
go build -o agentboard ./cmd/agentboard

Quick Start

Starting a new project

agentboard init    # creates .agentboard/ directory
agentboard         # launch TUI (becomes peer-leader)

Joining an existing board

agentboard                         # auto-discovers via .agentboard/server.json
agentboard --connect host:port     # manual connection

Features

• Collaborative Kanban board in the terminal
• Real-time sync via WebSocket (peer-leader model)
• Agent-agnostic — works with any AI CLI tool
• Agent lifecycle management — spawn, monitor, and kill agents via tmux
• Task enrichment — opt-in AI enrichment adds description and context to new tasks
• AI proposal inbox — agents propose new tasks; review and accept/dismiss via s
• CLI-first design — TUI for interactive use, subcommands for scripting
• SQLite-backed local persistence
• Git worktree isolation per task
• Ngrok tunnel — expose your board to remote collaborators with serve --tunnel
• AI enrichment — automatic task analysis with suggestions and dependency tracking
• Task search — fuzzy search across the board with /
• Board mode toggle — switch views with tab

Key Bindings

Key	Action
h / l (or arrows)	Previous / next column
j / k (or arrows)	Next / previous task
o	New task
enter	Open task detail
m	Move task right
M	Move task left
x	Delete task
a	Spawn agent
A	Kill agent
v	View agent session
E	Toggle task enrichment on/off
s	Review AI proposals
/	Search tasks
tab	Toggle Agent / Detail mode
?	Help
q	Quit
esc	Close overlay / cancel

Supported Agents

Agent	Command	Status
Claude Code	claude	Supported
Cursor CLI	cursor	Supported
Antigravity	antigravity	Supported
Custom	Detected via PATH	Configurable

CLI Reference

Root command

agentboard [--connect <host:port|wss://url>]

Launches the TUI. Use --connect to connect to a specific server instead of auto-discovering. Accepts both host:port and wss:// URLs (for ngrok tunnels).

Subcommands

Command	Description	Key Flags
init	Initialize project config	--
serve	Start dedicated server (no TUI)	--port/-p (default: random), --bind (default: 127.0.0.1), --tunnel
status	Show board summary	--json (includes agents and enrichments)
task list	List tasks	--status, --assignee, --search, --json
task create	Create a new task	--title (required), --description, --enrich
task move <id> <column>	Move task to column	--
task get <id>	Get task details	--json
task update <id>	Update task fields	--title, --description, --assignee, --branch, --pr-url, --add-dep, --remove-dep
task comment <id>	Add a comment to a task	--author, --body
task delete <id>	Delete a task	--
task claim <id>	Claim a task	--user
task unclaim <id>	Unclaim a task	--
task update <id>	Update task fields	--title, --description, --assignee, --branch, --pr-url, --add-dep, --remove-dep
task comment <id>	Add a comment to a task	--author (required), --body (required)
task block <id> <blocker-id>	Mark task as blocked by another	--
task unblock <id> <blocker-id>	Remove a dependency	--
task suggest	Propose a new task (AI inbox)	--title (required), --description
task suggestions	List suggestions	--status (pending/accepted/dismissed)
task suggestion accept <id>	Accept a suggestion	--
task suggestion dismiss <id>	Dismiss a suggestion	--
agent start <task-id>	Spawn an agent for a task	--
agent kill <task-id>	Kill a running agent	--
agent status <task-id> <msg>	Report agent activity	--json
agent request-reset <task-id>	Request fresh context for agent's next stage	--

Valid columns for task move: backlog, brainstorm, planning, in_progress, review, done

Task enrichment

Enrichment runs Claude Code in one-shot (--print) mode to add context to a task — it scans git history, lists open tasks, then updates the description and leaves a comment.

Enrichment is opt-in. New tasks are not enriched by default.

# Opt in at creation
agentboard task create --title "My task" --enrich

# Toggle in TUI: press E on any task (pending ↔ skipped)
# A task set to "pending" will be picked up by the next poll tick (~2.5s)

The enrichment status is shown in the task detail view (Enrich: pending / enriching / done / error / skipped).

AI proposal inbox

Agents (or scripts) can propose new tasks without creating them directly:

agentboard task suggest --title "Refactor auth layer" --description "..."

Proposals appear in the TUI's suggestion inbox. Press s to review, then accept or dismiss each one. Accepted proposals become real tasks.

agentboard status --json

Machine-readable board summary — useful for agents deciding what to work on next:

agentboard status --json

Returns task counts by column, active agents, and enrichment activity.

Task IDs accept short prefixes (first 8 chars shown in task list).

Ngrok tunnel

To share your board with remote collaborators:

# Leader: expose the board via ngrok
NGROK_AUTHTOKEN=<token> agentboard serve --tunnel
# → prints: agentboard --connect wss://abc123.ngrok.io

# Peer: connect from anywhere
agentboard --connect wss://abc123.ngrok.io

Configuration

Running agentboard init creates:

.agentboard/
  config.toml    # project config (commit this)
  .gitignore     # auto-generated (ignores server.json, worktrees/)
  board.db       # SQLite database (auto-created on first run)
  server.json    # ephemeral peer discovery (gitignored)

Default config.toml:

[project]
name = ""

[agent]
preferred = "claude"

[worktree]
copy_files = [".env", ".env.local"]
init_script = ""

Architecture

graph TB
    subgraph "agentboard binary"
        TUI[TUI - Bubble Tea]
        CLI[CLI Subcommands]
        BS[Board Service]
        DB[(SQLite)]
        WS[WebSocket Sync]
        AG[Agent Manager]
        TM[tmux Sessions]
    end

    TUI --> BS
    CLI --> BS
    BS --> DB
    BS <--> WS
    TUI --> AG
    AG --> TM

    WS <-->|peer-leader model| WS2[Other Peers]

Loading

How It Works

Agentboard uses a peer-leader model for collaboration. The first instance to start becomes the leader and runs a WebSocket server. Other instances connect as peers and sync in real time.

When you close the TUI, your agents keep running in their tmux sessions. Relaunch agentboard to reconnect and resume where you left off.

The TUI and CLI subcommands share the same binary and the same SQLite database. You can use agentboard task list in scripts while the TUI is running — they operate on the same data.

Dependencies

Library	Purpose
Bubble Tea	Terminal UI framework
Bubbles	TUI components
Lip Gloss	Terminal styling
Cobra	CLI framework
gorilla/websocket	WebSocket communication
modernc.org/sqlite	Pure-Go SQLite driver
google/uuid	UUID generation
ngrok/ngrok-go	Ngrok tunnel integration

Roadmap

Current status: v0.2.0 — MVP plus enrichment, tunneling, and full agent CLI.

Planned:

• Homebrew distribution
• Enhanced agent detection

Contributing

# Build from source
git clone https://github.com/markx3/agentboard.git
cd agentboard
go build -o agentboard ./cmd/agentboard

# Run tests
go test ./...

The project follows standard Go conventions with an internal/ package layout. See the Architecture section for an overview.

Acknowledgements

Inspired by agtx — a terminal-native AI agent orchestration tool.

License

MIT