convez.ai
AgenteAutomaçãoIntermediário
rguiu

Armada

rguiu/armada

Gerenciamento de frota para agentes de código com dashboard web e sessões persistentes

Ver no GitHub
BomPluginScore · de 0 a 100

Orquestrador de agentes de código IA com painel de controle em tempo real. Spawna workers paralelos em nós tmux, delega tarefas via API e monitora status com logs de atividade por step. Suporta OpenCode, Claude Code e agentes bash com notificações, kill/delete em lote e limpeza em cascata.

Instalação

$npx convez-ai rguiu/armada

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
9
Forks
0
Acompanhando
1
Saúde
42%
Último commit
há 5 dias
Versão
—
Issues abertas
3
Contribuidores
3

Casos de uso

  • Orquestrar múltiplos agentes de IA para tarefas de coding paralelas
  • Monitorar status de agentes remotamente via web dashboard
  • Manter sessões persistentes e reconectar de qualquer dispositivo

Veredito

Ferramenta madura e bem arquitetada para quem precisa coordenar agentes de código em escala. Dashboard responsivo e integração nativa com Claude Code/OpenCode tornam viável supervisão distribuída de workflows de IA, embora exija infraestrutura tmux e Python 3.10+.

README

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

   █████╗ ██████╗ ███╗   ███╗ █████╗ ██████╗  █████╗
  ██╔══██╗██╔══██╗████╗ ████║██╔══██╗██╔══██╗██╔══██╗
  ███████║██████╔╝██╔████╔██║███████║██║  ██║███████║
  ██╔══██║██╔══██╗██║╚██╔╝██║██╔══██║██║  ██║██╔══██║
  ██║  ██║██║  ██║██║ ╚═╝ ██║██║  ██║██████╔╝██║  ██║
  ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝     ╚═╝╚═╝  ╚═╝╚═════╝ ╚═╝  ╚═╝

Live supervision for your coding agents. Real-time status, persistent sessions, any device.

PyPI Test PyPI Python License

What is Armada?

Start a Claude Code or OpenCode agent on your laptop, close it, and pick up where you left off — from any device on your network.

Armada gives you fleet management for coding agents: persistent tmux sessions, a web dashboard, and real-time status visibility. Know instantly which agents are working, waiting for approval, or stuck.

  • Agent status — every agent reports idle, active, pending, or error. See which agents are blocked or waiting for input at a glance.
  • Persistent sessions — built on tmux: reconnect, multiplex, survive disconnects. No custom runtime to maintain.
  • Web dashboard — manage agents from your browser, phone, or tablet. Scan the QR code to open on other devices.
  • Delegation — agents can spawn child workers, delegate tasks, and run in parallel.
  • One command — armada starts the server and opens the dashboard.

Installation

Prerequisites: Python 3.10+, tmux, and either OpenCode or Claude Code installed on your PATH.

pip install armada-ai
armada setup                # install agent skills for OpenCode and Claude Code

armada is now available. You can also install from source or run via Docker — see below.

docker build -t armada .
docker run -d -p 9100:9100 --name armada armada
git clone https://github.com/rguiu/armada.git
cd armada
bash install.sh

Quick Start

armada                     # start server + open dashboard

Open http://127.0.0.1:9100.

  1. Register a project — sidebar Projects → + Add. Give it an ID, name, and directory path.
  2. Create a node — click + Node, pick a project, choose an agent type (OpenCode, Claude Code, or Bash), optionally add an initial prompt.
  3. Attach — select the node and click Attach. Opens in iTerm2 (macOS) for full TUI, or in-browser via xterm.js.
  4. Monitor — the dashboard updates every 10 seconds. See status, activity logs, and task history.
  5. Connect other devices — scan the QR code in the sidebar to open the dashboard on your phone or tablet.

Dashboard

Agent Types: Claude Code vs OpenCode

Armada supports both Claude Code and OpenCode as first-class agents. Each integrates differently:

OpenCode

OpenCode is an open-source AI coding agent. Armada's OpenCode integration uses:

  • Plugin system — an armada-pending plugin hooks into OpenCode's event loop (tool start/stop, permission requests, step completion). Agents automatically report active, idle, or pending status to Armada.
  • Skills — armada-node and armada-worker skill files teach agents how to report status, spawn children, and send results.

To use OpenCode: install it, make sure opencode is on your PATH, and run armada setup. When creating a node, select "opencode" as the agent type.

Claude Code

Claude Code is Anthropic's official CLI agent. Armada's Claude Code integration uses:

  • Hook system — four shell hooks (claude-pre-tool.sh, claude-post-tool.sh, claude-stop.sh, claude-permission.sh) fire on tool use, idle transitions, and permission requests. These curl the Armada API to report status.
  • Skills — the same skill files are installed to ~/.claude/skills/ and auto-activate when ARMADA_NODE_NAME is set.

To use Claude Code: install it via npm install -g @anthropic-ai/claude-code, make sure claude is on your PATH, and run armada setup. When creating a node, select "claude" as the agent type.

Bash

Bare shell nodes without an agent. Useful for running scripts or manual commands. Armada provides a bash wrapper (armada-bash.sh) with functions like armada_report_active, armada_spawn, and armada_kill_child.

Which one should you use?

OpenCodeClaude Code
Installpip install opencodenpm install -g @anthropic-ai/claude-code
Status reportingPlugin (TypeScript, event-driven)Shell hooks (pre/post-tool, stop)
PermissionsPermission events in pluginclaude-permission.sh hook
Cost trackingToken usage from step-finish eventsNot built in
Best forOpen-source workflows, custom pluginsAnthropic ecosystem, official support

Either works. Pick based on which agent you already have installed.

Commands

CommandDescription
armadaStart daemon + open dashboard
armada --no-browserStart server without opening browser
armada startStart daemon in background
armada stopStop the daemon
armada watchInteractive terminal dashboard (htop-style)
armada create -p <project>Create a new agent node
armada nodesList all agents in a table
armada attach <name>Attach to a node by name (iTerm2)
armada projectsList projects
armada projects add <id> <name> <path>Register a project
armada projects rm <id>Remove a project
armada setupInstall skills to user profile
armada versionPrint the Armada version
armada tokenPrint the auth token
armada token --qrPrint token as scannable QR code
armada configShow or set configuration
armada config set <key> <val>Change a config value (default_agent, port, etc.)
armada service installInstall as system service (launchd/systemd)
armada statusShow server health and agent counts
armada doctorClean up stale tmux sessions and DB state
armada --lanBind server to LAN IP (access from other devices)

CLI Watch Dashboard

armada watch is a live terminal dashboard for managing agents without a browser:

$ armada watch

 Nodes   Projects   |  3 active  1 pending  12 idle  |  23 agents

 ● HOOK20           ▣ idle   PGLease            unknown needs external_directory
 ○ HOOK18             idle   PGLease            server restarted — reconnected
 ○ H1                 idle   Armada
 ○ Armada-006         idle   Armada
 ● Armada-005         active Armada             running bash

 ⚠ Pending: HOOK20

 ┃ [↑↓]nav [enter]attach [n]ew [k]kill [d]delete [tab]projects [q]quit ┃
KeyAction
↑ ↓Navigate agent list
EnterAttach to selected node (focuses existing pane)
aSplit-attach (experimental — opens a new tmux pane for the node)
nNew node (interactive form)
kKill selected node
dDelete selected node
TabSwitch to Projects view
qQuit

Note: a (split-attach) is experimental and may not work reliably in all terminal environments. It is not shown in the bottom bar but remains available as a hidden shortcut.

Forms for creating nodes and projects use keyboard navigation: Tab/↑↓ to move between fields, ←→ to cycle options, type freely in text fields, Enter on [Save] to submit, Esc to cancel.

Agent Delegation

Agents can delegate work to child nodes using built-in skills:

Orchestrator
├── Reviewer  — reviews the code
└── Tests     — writes and runs tests
  1. Start Armada: armada
  2. Register a project and create an orchestrator node (agent type: "opencode" or "claude")
  3. The orchestrator spawns child workers, delegates tasks, and monitors results
  4. The dashboard updates in real time as each worker reports active/idle

Skills (armada-node, armada-worker, armada-orchestrator) teach agents how to spawn children, delegate work, and report results back to the dashboard.

Architecture

SQLite (WAL) + FastAPI REST server, daemonized. Each node is a tmux session — no custom agent runtime, just tmux providing persistence, reconnection, and multiplexing. Nodes report status via POST /api/report. The dashboard refreshes over a persistent WebSocket.

API Endpoints

MethodPathPurpose
GET/api/treeFull node hierarchy
POST/api/nodesCreate node
GET/api/nodes/:idNode detail + reports
DELETE/api/nodes/:idKill node + cascades to children
POST/api/nodes/:id/sendSend command to worker
POST/api/nodes/:id/attachOpen terminal attached to node
POST/api/reportAgent status report (active/idle/pending/error)
GET/POST/DELETE/api/project-labelsCRUD project directories
GET/healthHealth check (no auth)
GET/metricsPrometheus metrics
GET/api/qr?url=SVG QR code

Full API docs at http://127.0.0.1:9100/docs (FastAPI Swagger UI).

Development

python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[test]"

pytest                          # run tests
pytest --cov=armada_ai          # with coverage
ruff check armada_ai/ tests/    # lint

CI runs ruff + pytest-cov on Python 3.10–3.13 on push to main.

License

MIT

Ver o original no GitHub

Bom para

Relacionados