cmux-todo-board
Kaiukov/claude-code-cmux-todo-plugin
Sincronize GitHub Issues → quadro local → lista de tarefas Claude → cmux
Ver no GitHubPlugin para Claude Code que sincroniza issues do GitHub com um quadro de tarefas local, espelha tarefas prontas para a lista built-in do Claude e despacha trabalho através de panes cmux. Permite orquestração de fluxo de trabalho integrando GitHub Issues, TODO.md e boards JSON em um único sistema de tarefas.
Instalação
npx convez-ai Kaiukov/claude-code-cmux-todo-plugin1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Orquestrar fluxo de trabalho de desenvolvimento com issues do GitHub
- Espelhar tarefas prontas para a lista de tarefas built-in do Claude
- Automatizar despacho de tarefas em múltiplos panes cmux
- Revisar e planejar trabalho entre GitHub e ambiente local
Veredito

MVP funcional para sincronização unidirecional (GitHub → local → tarefas). Solução prática para times que usam GitHub Issues e precisam orquestração em Claude Code, mas sincronização de volta para GitHub ainda é trabalho futuro. Instalação via marketplace GitHub é robusta.
README
A tradução para o português deste README ainda está na fila.
cmux-todo-board
Claude Code plugin that bridges GitHub Issues into a local task board, mirrors ready tasks into Claude's built-in task list, and dispatches work through cmux panes.
Status: MVP (one-directional: GitHub Issues → local board → task list).
Sync-back to GitHub is future work. Installation is designed to source the marketplace
from GitHub so /plugin marketplace update pulls the latest main.
Installation
Via /plugin (recommended)
Run these inside Claude Code, from your project folder:
/plugin marketplace add Kaiukov/claude-code-cmux-todo-plugin
/plugin install cmux-todo-board@kaiukov-tools
The skills then appear as /board-init, /board-pull, etc. in that project.
Update later with /plugin marketplace update kaiukov-tools.
Updating
Plugins never auto-update silently — update is always a manual command. When the marketplace is registered from GitHub, run these inside Claude Code:
/plugin marketplace update kaiukov-tools
/reload-plugins
This re-reads the latest main from GitHub and reloads skills and hooks.
Via local dir (development / fallback)
git clone https://github.com/Kaiukov/claude-code-cmux-todo-plugin
claude --plugin-dir ./claude-code-cmux-todo-plugin # or /reload-plugins if running
Troubleshooting
ERR_STREAM_PREMATURE_CLOSE during marketplace add
This is a known upstream race in Claude Code's plugin manager when it streams
git child-process stdio. The repo itself is public and reachable over both SSH
and HTTPS — the same git clone command succeeds when run by hand. The plugin
manager always passes --recurse-submodules --shallow-submodules; this repo
has no .gitmodules, so submodule flags are a guaranteed no-op and are not the
cause.
Workaround A — retry (transient): The stdio race sometimes clears on retry.
Run /plugin marketplace add Kaiukov/claude-code-cmux-todo-plugin again.
Workaround B — local-directory fallback (always works):
git clone https://github.com/Kaiukov/claude-code-cmux-todo-plugin
Then inside Claude Code register the checkout as a Directory source:
/plugin marketplace add ./claude-code-cmux-todo-plugin # Source: Directory
Update later with:
git -C ./claude-code-cmux-todo-plugin pull
Then inside Claude Code:
/plugin marketplace update kaiukov-tools
/reload-plugins
The GitHub-sourced path is the intended primary flow; the local-directory path is the developer fallback when the upstream race surfaces.
Quick start
Run from your project folder, once the plugin is installed:
/board-init --repo owner/repo # 1. run ONCE per repo — create canonical labels
/board-pull --repo owner/repo # 2. fetch issues → .tasks/board.json + TODO.md
/board-plan # 3. mirror `ready` issues into Claude's task list
/board-run-ready # 4. dispatch ready tasks into cmux panes
Label your issues with ready (or the other canonical statuses) so board-pull
picks them up. Review TODO.md between steps 2 and 3 to see everything grouped
by status.
Skills
| Skill | Description |
|---|---|
/board-onboard | Run FIRST in a clean session — switch into orchestrator mode and load all board + cmux operating instructions. |
/board-onboard-lite | Compact orchestrator bootstrap for token-constrained sessions. Full rules at plugins/cmux-todo-board/docs/ORCHESTRATOR.md. |
/cmux-agent-workflows-lite | Compact delegation reference for cmux agent orchestration — script catalog, delegation cycle. Full reference at plugins/cmux-todo-board/skills/cmux-agent-workflows/SKILL.md. |
/board-init | Initialize a repo with canonical board status labels. Run once per repo before board-pull. |
/board-create-issue | Turn a raw task description into a structured GitHub issue and create it. |
/board-add-task | Add a local task without a GitHub issue. Local tasks live in .tasks/local.json and never touch GitHub. Local task status can be updated via board-add --set <id> --status <status>. |
/board-pull | Fetch GitHub issues and render the local board. Supports --strategy all-open (default, one API call + local filter) and --strategy labels (per-label queries unioned). Use --with-body to include body text. |
/board-sync | Write ONE issue's status back to GitHub by swapping its canonical label. Idempotent, preserves non-canonical labels. |
/board-release | Bump SemVer versions, create git tags, and publish GitHub Releases with opt-in network safety gates. |
/board-plan | Mirror ready tasks into Claude's built-in task list (cap: 5). |
/board-run-ready | Dispatch ready tasks to cmux panes for parallel execution. Generates compact .task-spec.md with forbidden_reads guard. |
/board | Show the board flow and operating rules. |
Workflow
GitHub Issues --board-pull--> .tasks/board.json --board-plan--> Claude task list
|
v
board-run-ready --> cmux panes
GitHub labels are the source of truth for status; board.json is a local cache
and TODO.md is a read-only render. The board is bidirectional — board-sync
writes status back to GitHub labels. See Quick start for the
command sequence.
Limit monitor
plugins/cmux-todo-board/bin/limit-monitor parses the Claude Code status line rate_limits.seven_day
field and persists state to .tasks/limit-monitor.json. Register it as a status
line command in ~/.claude/settings.json so it receives rate_limits on stdin:
{
"statusLine": {
"type": "command",
"command": "bash plugins/cmux-todo-board/bin/limit-monitor"
}
}
Environment variables:
| Variable | Default | Description |
|---|---|---|
LIMIT_WARN_AT | 80 | Percentage threshold for WARN notification |
LIMIT_CRIT_AT | 95 | Percentage threshold for CRIT notification |
LIMIT_DATA_FILE | .tasks/limit-monitor.json | State persistence path |
On CRIT threshold breach it calls cmux notify (once per week max dedup).
Degrades gracefully when stdin has no rate_limits data.
Verification
# Run the board-render tests
bash plugins/cmux-todo-board/tests/test_board_render.sh
# Run the union/dedup logic tests
bash plugins/cmux-todo-board/tests/test_board_pull_union.sh
# Run the label-swap logic tests
bash plugins/cmux-todo-board/tests/test_board_sync.sh
# Validate plugin structure (if claude CLI available)
claude plugin validate .
Scope
- MVP (Phase 1): Pull issues → render board → plan → dispatch. Sync back via
board-sync. - Only
readytasks are dispatched.blockedandneeds-infoare skipped.
Files
| Path | Role |
|---|---|
.claude-plugin/plugin.json | Plugin manifest |
plugins/cmux-todo-board/bin/board-init | Bash: create/normalize canonical labels |
plugins/cmux-todo-board/bin/board-pull | Bash: fetch issues via gh (--with-body for full body) |
plugins/cmux-todo-board/bin/board-render | Python: generate board.json + TODO.md |
plugins/cmux-todo-board/bin/board-render-body | Bash: on-demand full-body retrieval for a single issue |
plugins/cmux-todo-board/bin/board-status | Bash: compact board state for the orchestrator (counts + next ready) |
plugins/cmux-todo-board/bin/board-next | Bash: return next actionable task for a given status |
plugins/cmux-todo-board/bin/limit-monitor | Bash: weekly Claude Code limit monitor (status line command) |
plugins/cmux-todo-board/skills/*/SKILL.md | Skill definitions |
hooks/hooks.json | SessionStart board summary |
plugins/cmux-todo-board/docs/state-model.md | State mapping across representations |
plugins/cmux-todo-board/docs/file-roles.md | Roles of generated files |
plugins/cmux-todo-board/docs/ORCHESTRATOR.md | Full orchestrator operating rules (referenced by board-onboard-lite) |
plugins/cmux-todo-board/tests/ | Self-contained render tests |
.tasks/board.json | Generated: local board cache |
.tasks/issues.json | Generated: fetched GitHub issues |
.tasks/issues/<n>.md | Per-issue body cache for workers (not committed; .tasks/ is gitignored) |
TODO.md | Generated: read-only task board |