armada-ai 0.3.5

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

Persistent sessions and live supervision for coding agents.

What is Armada?

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

Each agent runs in its own session and maintains state across reconnects, restarts, and devices. You can start agents from your laptop, disconnect and reconnect later, monitor execution in real time, and manage multiple agents at once.

Key Features

• Persistent agent sessions — every agent runs inside a tmux session and survives disconnects. No custom runtime.
• Live status tracking — see which agents are active, idle, pending, or error in real time.
• Web + terminal control — manage agents via the dashboard or armada watch.
• Multi-agent workflows — spawn workers and coordinate execution across a tree of agents.
• Message system — structured communication between nodes with event-driven delivery.
• MCP integration — agents interact with Armada through typed MCP tools instead of raw API calls.

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

pip install --index-url https://pypi.org/simple/ fastapi uvicorn websockets qrcode mcp 'tomli>=1.0'
pip install --index-url https://test.pypi.org/simple/ --no-deps armada-ai
armada setup

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 the agent session in iTerm2 (macOS) for full TUI, or xterm.js in-browser.
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.

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

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

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

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