armada-ai | Raul Guiu

armada-ai gives coding agents persistent sessions and live supervision. Agents run inside tmux windows that survive disconnects and restarts. A FastAPI server provides a REST API, web dashboard, and MCP-native skills for agent orchestration.

Architecture

Domain-driven design with clean separation:

armada_ai/
  cli.py              CLI entrypoint (armada nodes, armada serve)
  server.py           FastAPI application
  service.py          Core service layer
  domain/
    models.py         Node, ProjectLabel, StatusReport,
                      AgentStatus, AgentType — dataclasses + enums
  infrastructure/
    database.py       SQLite database layer
    db_nodes.py       Node persistence
    db_projects.py    Project persistence
    db_messages.py    Message persistence
    tmux_session.py   tmux window management
    terminal_attach.py iTerm2 attachment (macOS)
    auth_manager.py   Authentication
  mcp_server.py       MCP integration for agents
  skills/
    armada-node/      Leaf node skill
    armada-orchestrator/  Spawn and manage children
    armada-worker/    Worker skill

Stack: FastAPI + uvicorn + websockets + SQLite. pip install armada-ai. 77% test coverage minimum enforced via pytest-cov.

tmux persistence

Every agent gets its own tmux session. Sessions survive API restarts. Terminal attachment via iTerm2 on macOS or xterm.js in the browser. You can watch any agent’s terminal in real time, scroll back through its history, and debug failures that would be invisible in a process pool.

Agent skills (MCP native)

Instead of agents interacting through raw REST calls, armada ships three skills that get installed into each agent:

armada-orchestrator. Spawn child nodes, send tasks, broadcast messages, monitor the agent tree.
armada-worker. Report status, read inbox, claim tasks from the shared work queue.
armada-node. Leaf behaviors: acknowledge messages, report completion.

Agents interact with armada through typed MCP tools rather than curl commands. Skills are plain markdown instructions shipped to agents at setup.

Dual interface

CLI. armada nodes --watch shows a live terminal dashboard of the agent tree with status.
Web. FastAPI serves a dashboard at port 9100 with agent tree visualization, session inspection, and device linking via QR code.

Multi-agent tree

Agents form a parent-child tree. The orchestrator spawns planner nodes. Planners spawn workers. Workers report results back up. The shared work queue (post_to_queue / claim_from_queue) enables pull-based task distribution — idle workers claim the next available task without the orchestrator tracking who is busy.

Supported agent types: OpenCode, Claude Code, Bash, and AAP (profiler-wrapped).

Message system

Structured messages between agents: tasks, results, broadcasts, status reports. Every message persists in SQLite. Every delegation leaves an audit trail. Nodes can be killed with cascade deletion to clean up entire subtrees.

Published on PyPI: pip install armada-ai. MIT license on GitHub.