armada-ai 0.3.0

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

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

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.
• MCP Server — agents interact with Armada through typed MCP tools instead of raw API calls. Agent type, project, and parent are inherited automatically.
• Task Mailbox — structured inter-node messaging with event-driven delivery. Nodes send messages, broadcast to children, and post to a shared work queue.
• 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.

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:

• MCP Server — an Armada MCP server provides 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 (tool start/stop, permission requests). Agents automatically report status to Armada.
• Skills — armada-node and armada-worker skill files teach agents orchestration and messaging patterns.

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 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 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. Status reporting uses the armada report CLI.

Which one should you use?

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

Commands

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 ┃

Agent Delegation

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 (agent type: "opencode" or "claude")
3. The orchestrator uses spawn_node("reviewer") and send_task(node_id, "review the auth module") — agent type and project are inherited automatically
4. Workers send completion messages back to the parent 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()

Skills (armada-node, armada-worker, armada-orchestrator) teach agents the full workflow including messaging patterns.

MCP Server

Armada includes an MCP (Model Context Protocol) server that exposes all operations as typed tools for AI agents. Instead of constructing curl commands, agents call tools with automatic defaults:

The MCP server is auto-configured when nodes are created. Run manually with armada mcp.

Inter-Node Messaging

Nodes communicate through a task mailbox system 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
• ACK — messages track pending → delivered → done lifecycle
• Completion notifications — workers automatically notify their parent when a task is done

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

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