convez.ai
AgenteAutomaçãoIntermediário
Kaiukov

cmux-todo-board

Kaiukov/claude-code-cmux-todo-plugin

Sincronize GitHub Issues → quadro local → lista de tarefas Claude → cmux

Ver no GitHub
InicialPluginScore · de 0 a 100

Plugin 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-plugin

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
v1.2.0
Issues abertas
9
Contribuidores
1

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

SkillDescription
/board-onboardRun FIRST in a clean session — switch into orchestrator mode and load all board + cmux operating instructions.
/board-onboard-liteCompact orchestrator bootstrap for token-constrained sessions. Full rules at plugins/cmux-todo-board/docs/ORCHESTRATOR.md.
/cmux-agent-workflows-liteCompact delegation reference for cmux agent orchestration — script catalog, delegation cycle. Full reference at plugins/cmux-todo-board/skills/cmux-agent-workflows/SKILL.md.
/board-initInitialize a repo with canonical board status labels. Run once per repo before board-pull.
/board-create-issueTurn a raw task description into a structured GitHub issue and create it.
/board-add-taskAdd 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-pullFetch 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-syncWrite ONE issue's status back to GitHub by swapping its canonical label. Idempotent, preserves non-canonical labels.
/board-releaseBump SemVer versions, create git tags, and publish GitHub Releases with opt-in network safety gates.
/board-planMirror ready tasks into Claude's built-in task list (cap: 5).
/board-run-readyDispatch ready tasks to cmux panes for parallel execution. Generates compact .task-spec.md with forbidden_reads guard.
/boardShow 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:

VariableDefaultDescription
LIMIT_WARN_AT80Percentage threshold for WARN notification
LIMIT_CRIT_AT95Percentage threshold for CRIT notification
LIMIT_DATA_FILE.tasks/limit-monitor.jsonState 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 ready tasks are dispatched. blocked and needs-info are skipped.

Files

PathRole
.claude-plugin/plugin.jsonPlugin manifest
plugins/cmux-todo-board/bin/board-initBash: create/normalize canonical labels
plugins/cmux-todo-board/bin/board-pullBash: fetch issues via gh (--with-body for full body)
plugins/cmux-todo-board/bin/board-renderPython: generate board.json + TODO.md
plugins/cmux-todo-board/bin/board-render-bodyBash: on-demand full-body retrieval for a single issue
plugins/cmux-todo-board/bin/board-statusBash: compact board state for the orchestrator (counts + next ready)
plugins/cmux-todo-board/bin/board-nextBash: return next actionable task for a given status
plugins/cmux-todo-board/bin/limit-monitorBash: weekly Claude Code limit monitor (status line command)
plugins/cmux-todo-board/skills/*/SKILL.mdSkill definitions
hooks/hooks.jsonSessionStart board summary
plugins/cmux-todo-board/docs/state-model.mdState mapping across representations
plugins/cmux-todo-board/docs/file-roles.mdRoles of generated files
plugins/cmux-todo-board/docs/ORCHESTRATOR.mdFull orchestrator operating rules (referenced by board-onboard-lite)
plugins/cmux-todo-board/tests/Self-contained render tests
.tasks/board.jsonGenerated: local board cache
.tasks/issues.jsonGenerated: fetched GitHub issues
.tasks/issues/<n>.mdPer-issue body cache for workers (not committed; .tasks/ is gitignored)
TODO.mdGenerated: read-only task board
Ver o original no GitHub

Bom para

Relacionados