opencode-kanban

A Rust terminal kanban board for managing Git worktrees and OpenCode tmux sessions.

Why this exists

Before creating this tool, I used Agent of Empires — which is also a cool project with a similar purpose. However, I found its session management quite barebone as projects grew more complex. I was also inspired by VibeKanban. So you can think of this tool as a combination of both - managing your tasks in a kanban without leaving your favorate terminal environment.

What makes this different: I'm building this exclusively for opencode users. This lets me integrate deeply with opencode's API and offer unique features:

1. Stable session running state detection
2. Session TODO list with progress tracking
3. Running subagents and their TODO summaries (when applicable)
4. And more to come 🚀

Prerequisites

• Unix shell
• tmux installed and available on PATH (required)
• opencode installed and available on PATH (recommended for attach/resume workflows)

Quickstart (2 minutes)

1. Verify runtime tools:

bash tmux -V opencode --version

1. Start the app:

bash npx @qrafty-ai/opencode-kanban

1. In the UI:
2. Press n to create a task
3. Press Enter on a task to attach
4. Press ? for built-in help
5. Press q to quit
6. In the attached tmux session:
7. Press <prefix>+O for help overlay
8. Press <prefix>+K to return to kanban session

If you start outside tmux, opencode-kanban auto-creates or auto-attaches to a tmux session named opencode-kanban.

Installation

npm

npm install -g @qrafty-ai/opencode-kanban

AUR (Arch Linux)

yay -S opencode-kanban
# or
paru -S opencode-kanban

Build from source

cargo build --release
./target/release/opencode-kanban

First run

• Launch default project:

bash opencode-kanban

• Launch a named project:

bash opencode-kanban --project my-project

• Start with a theme preset:

bash opencode-kanban --theme default opencode-kanban --theme light opencode-kanban --theme high-contrast opencode-kanban --theme mono opencode-kanban --theme custom

Each project uses its own SQLite file and board state.

Core workflows

Start a new task

1. Press n to open the new-task dialog.
2. Pick a repository and enter task details.
3. Press Enter to create.
4. Press Enter on the task card to attach to its tmux/OpenCode session.

Organize work on the board

• Move focus with h/l and select with j/k.
• Reorder/move task with H/J/K/L.
• Archive selected task with a.
• Open archive view with A.

Track Task Progress

• Press v to toggle between detail/kanban view
• Check detail view for session running state in depth

Keybindings cheat sheet

• Ctrl-p: switch project
• n: new task
• Enter: attach selected task
• h/j/k/l: navigate board
• H/J/K/L: move task
• a: archive selected task
• A: open archive view
• ?: help overlay
• q: quit

For full, current bindings, use the in-app help overlay (?).

Configuration

• Settings file: ~/.config/opencode-kanban/settings.toml
• Project databases (Linux default): ~/.local/share/opencode-kanban/*.sqlite

The app creates config/data files on demand.

Additional top-level notification settings:

• notification_backend: tmux | system | both | none
• notification_display_duration_ms: 500..=30000
• completion_sound: none | beep (defaults to none)
• completion_sound_volume_percent: 0..=100 (defaults to 100; 0 skips audio init and playback)

Example:

notification_backend = "both"
notification_display_duration_ms = 3000
completion_sound = "beep"
completion_sound_volume_percent = 40

Theme configuration options

Theme values live in ~/.config/opencode-kanban/settings.toml.

Top-level option:

• theme: default | light | high-contrast | mono | custom

When theme = "custom", configure semantic tokens with these sections:

• [custom_theme]
• inherit: default | light | high-contrast | mono
• [custom_theme.base]
• canvas, surface, text, text_muted, header, accent, danger
• [custom_theme.interactive]
• focus, selected_bg, selected_border, border
• [custom_theme.status]
• running, waiting, idle, dead, broken, unavailable
• [custom_theme.tile]
• repo, branch, todo
• [custom_theme.category]
• primary, secondary, tertiary, success, warning, danger
• [custom_theme.dialog]
• surface, input_bg, button_bg, button_fg

Example:

theme = "custom"

[custom_theme]
inherit = "light"

[custom_theme.base]
canvas = "#E2E7EE"
surface = "#ECF1F7"
text = "#222A3A"
text_muted = "#4E596D"
header = "#2F66BF"
accent = "#0E7490"
danger = "#B02E24"

[custom_theme.interactive]
focus = "#2F66BF"
selected_bg = "#D6DFED"
selected_border = "#477ACD"
border = "#A5B2C6"

[custom_theme.status]
running = "#278449"
waiting = "#AB781A"
idle = "#5D687A"
dead = "#B02E24"
broken = "#B02E24"
unavailable = "#B02E24"

[custom_theme.tile]
repo = "#086678"
branch = "#926614"
todo = "#4E596D"

[custom_theme.category]
primary = "#2F66BF"
secondary = "#AB501F"
tertiary = "#6949AB"
success = "#278449"
warning = "#AB781A"
danger = "#B02E24"

[custom_theme.dialog]
surface = "#ECF1F7"
input_bg = "#E0E6EF"
button_bg = "#CDD8E7"
button_fg = "#FFFFFF"

• Accepted color format: #RRGGBB (hex only).

Troubleshooting

• tmux is required but not available:
• Install tmux and confirm tmux -V works in the same shell.
• OpenCode binary not found:
• Install OpenCode and confirm opencode --version works.
• Mouse scroll/click not working well in tmux:
• Run tmux set -g mouse on.

Local development

cargo test
cargo clippy -- -D warnings
cargo build --release

Maintainers

Release and publisher setup docs are in docs/releasing.md.

License

MIT