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

Persistent sessions and live supervision for coding agents.

Armada runs coding agents in persistent tmux sessions and lets you monitor and control them from a terminal dashboard or web UI.

Each agent runs in its own session and maintains state across reconnects, restarts, and devices.

• Persistent agent sessions — every agent runs inside a tmux session and survives disconnects
• Live status tracking — see active, idle, pending, error in real time
• Terminal + web control — manage agents via armada nodes --watch or the web dashboard
• Multi-agent workflows — spawn child workers, delegate tasks, coordinate execution
• Message system — structured communication between agents with event-driven delivery
• MCP integration — agents interact with Armada through typed tools, not curl commands

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

pip install armada-ai
armada setup                # install agent skills and MCP config

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

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 the agent session in iTerm2 (macOS) or in-browser via xterm.js.
4. Monitor — see status, activity logs, and task history in real time.
5. Connect other devices — scan the QR code in the sidebar to open the dashboard on your phone or tablet.

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

$ armada nodes --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 ┃

Armada supports Claude Code, OpenCode, and Bash as agent types.

• MCP Server — typed tools (spawn_node, send_message, report_status, etc.) directly in the agent's tool palette. Auto-configured via opencode.json.
• Plugin system — an armada-pending plugin hooks into OpenCode's event loop. Agents automatically report status.
• Skills — armada-node and armada-worker skill files teach agents orchestration and messaging patterns.

To use: install OpenCode, make sure opencode is on your PATH, run armada setup.

• Hook system — four shell hooks fire on tool use, idle transitions, and permission requests. These use the armada report CLI to report status.
• Skills — the same skill files are installed to ~/.claude/skills/ and auto-activate when ARMADA_NODE_NAME is set.

To use: install via npm install -g @anthropic-ai/claude-code, make sure claude is on your PATH, run armada setup.

Bare shell nodes without an agent. Useful for running scripts or manual commands. Armada provides a bash wrapper with status reporting functions.

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

Agents can delegate work to child nodes using MCP tools:

Orchestrator
├── Reviewer  — reviews the code
└── Tests     — writes and runs tests
                └── sends "job completed" message back to Orchestrator

1. Start Armada: armada
2. Register a project and create an orchestrator node
3. The orchestrator uses spawn_node("reviewer") and send_task(node_id, "review the auth module")
4. Workers send completion messages back via send_message(to_node_id=parent_id, payload="job completed", msg_type="result")
5. The orchestrator collects results via read_inbox() and cleans up with kill_node()

See examples/ for tested workflows: parallel feature builds, multi-project security audits, work queues, and code review pipelines.

Armada includes an MCP server that exposes operations as typed tools for AI agents:

Auto-configured when nodes are created. Run manually with armada mcp.

Nodes communicate through a task mailbox with event-driven delivery:

• Direct messages — any node can send structured messages to any other node
• Broadcast — fan-out a message to all children with one call
• Work queue — post tasks to a shared queue for any idle agent to claim
• Event-driven delivery — no polling; the server pushes messages via tmux when the recipient goes idle
• Completion notifications — workers notify their parent when a task is done

Armada uses a FastAPI server with SQLite (WAL). Each agent is backed by 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.

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

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.

MIT