convez.ai
AgenteAutomaçãoIntermediário
oh-namgyu

Agent Workboard

oh-namgyu/agent-workboard

Coordena múltiplos agentes IA em um único codebase sem conflitos

Ver no GitHub
InicialPluginScore · de 0 a 100

Sistema de controle de concorrência para múltiplos agentes de IA editando o mesmo repositório. Funciona como um quadro de reserva com REST API, dashboard em tempo real e hooks de enforcement para Claude Code, bloqueando edições conflitantes antes que aconteçam.

Instalação

$npx convez-ai oh-namgyu/agent-workboard

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
57%
Último commit
há 2 dias
Versão
v0.2.1
Issues abertas
0
Contribuidores
1

Casos de uso

  • Executar Claude Code + Codex + Gemini simultaneamente no mesmo repo
  • Prevenir sobrescrita acidental de arquivos por agentes concorrentes
  • Monitorar sessões ativas de IA em tempo real e gerenciar liberações

Veredito

Solução prática e bem pensada para um problema real de coordinação multi-agente. A combinação de hooks de enforcement + TTL de limpeza + dashboard torna a abordagem robusta. Recomendado para quem está escalando automação com múltiplos agentes IA.

README

A tradução para o português deste README ainda está na fila.

agent-workboard

🇰🇷 한국어 README

A claim board that keeps multiple AI coding agents — Claude Code, Codex CLI, Gemini CLI, or any tool that can run a shell command — from clobbering each other in the same codebase.

Agents claim a project (or a path glob) before editing, release it when done, and a live dashboard shows who is working where. For Claude Code, an included PreToolUse hook turns the convention into enforcement: edits to a resource claimed by another agent are blocked with the holder's name before they happen.

dashboard

Why

Running two or three coding agents on one machine is normal now. Running them in the same repository is how you get silently overwritten files, dirty-tree races, and "where did my change go". File locks don't help — agents hold no file handles between turns. What works is a session-level protocol: check in before you edit, check out when you leave — with a board everyone can see, a TTL reaper for crashed sessions, and hooks that enforce it where possible.

Quick start

git clone https://github.com/oh-namgyu/agent-workboard && cd agent-workboard
npm install

# 1. start the board (loopback only, port 5054)
npx . serve

# 2. open the dashboard
open http://127.0.0.1:5054

# 3. wire up Claude Code in any project (hooks + /claim /release /board commands)
cd ~/code/my-app && node /path/to/agent-workboard/src/cli.js install-claude

From then on, every Claude Code session in my-app claims the project on start, releases on end, and refuses to edit anything actively claimed by another agent.

How it works

Claude Code ── PreToolUse hook ──┐                       ┌─ SQLite (~/.agent-workboard/)
Codex CLI ──── AGENTS.md rules ──┼──> workboard CLI ──> REST server :5054
Gemini CLI ─── GEMINI.md rules ──┘                       ├─ TTL reaper (stale claims)
You ────────── dashboard (force release, live view) <────┘

Conflict rules — a claim blocks another agent when:

Your actionBlocked by
claim/edit in project my-appanother agent's active claim on my-app
edit src/api/users.jsanother agent's path claim whose glob matches (e.g. src/api/**)

Same-agent re-claims are idempotent (they refresh the heartbeat). Claims with no heartbeat for the TTL (default 30 min) are flagged stale; after 2× TTL the reaper auto-releases them.

CLI

workboard serve [--port N] [--host H] [--db FILE] [--ttl MINUTES]
workboard claim <resource> [--agent NAME] [--note TEXT] [--kind project|path]
workboard release <resource> [--agent NAME] | --id ID
workboard list [--json]
workboard check [--resource R] [--path FILE] [--agent NAME]    # exit 2 = blocked
workboard watch [--interval SECONDS]
workboard install-claude [--project DIR]

With no <resource>, claim/release/check use the current directory name — run them from the project root. Identity comes from --agent or WORKBOARD_AGENT.

REST API

MethodPathDescription
GET/api/claimsactive claims (with stale flags) + recent history
POST/api/claims{agent, resource, kind?, note?} → 201, or 409 + conflicts
POST/api/claims/:id/heartbeatkeep a long-running claim fresh
POST/api/claims/:id/release{by?} → release
GET/api/check?agent=&resource=&path=conflict probe → {allowed, conflicts}
GET/api/eventsSSE stream (update on every change)

Agent integrations

  • Claude Code — workboard install-claude writes into the project's .claude/settings.local.json and .claude/commands/ (idempotent):
    • PreToolUse (Edit/Write/MultiEdit/NotebookEdit): blocks edits on conflicting claims, exit 2 with the holder's name so the agent coordinates instead of retrying
    • SessionStart / SessionEnd: automatic check-in / check-out
    • /claim, /release, /board slash commands
  • Codex CLI — copy integrations/AGENTS-snippet.md into your AGENTS.md
  • Gemini CLI — copy integrations/GEMINI-snippet.md into your GEMINI.md
  • Anything else — it's a CLI and a REST API; if your agent can run a shell command, it can participate

Hooks fail open: a down board never bricks an agent session. See docs/PATTERNS.md for claim granularity, TTL tuning, and human-override patterns.

Configuration

EnvDefault
WORKBOARD_PORT5054server port
WORKBOARD_HOST127.0.0.1bind address (see SECURITY.md before widening)
WORKBOARD_DB~/.agent-workboard/workboard.dbSQLite file
WORKBOARD_TTL_MIN30minutes until a claim is stale (auto-release at 2×)
WORKBOARD_URLhttp://127.0.0.1:5054server URL used by CLI/hooks
WORKBOARD_AGENTagent (claude in hooks)agent identity

Docker

docker compose up -d   # board on 127.0.0.1:5054, db persisted in a volume

Development

npm test   # unit + HTTP lifecycle + CLI e2e (two simulated agents colliding)

MIT — see LICENSE. Security model and reporting: SECURITY.md.

Ver o original no GitHub

Bom para

Relacionados