From zero to a working AI engineering team in under 5 minutes.
- opencode installed and authenticated
- Node.js >= 20
- A terminal (wezterm recommended for lane sessions; any terminal works for setup)
Note: armada currently generates teams for opencode. Support for Claude Code and Codex is on the roadmap — same team, different runtime.
npm install -g @rafamacalaba/armada # or: bun add -g @rafamacalaba/armada
armada --version # confirm the binary works
armada doctor # environment health checkarmada doctor verifies everything: opencode presence, provider authentication, model
availability, and background subagent dispatch. Run it after every install or upgrade.
The fastest path — interactive questionnaire picks a starter, fills vars, scaffolds the team:
armada new my-app
cd my-app
opencode # boots into the Commodorearmada new already runs armada init, so the team is ready the moment it finishes — do not
run armada init again. In a non-TTY (scripted) context it defaults to the blank template.
Skip the questionnaire with the flags (--blank, --config ./vars.json, --yes) or use an
external Cookiecutter template with --template <url|path>.
Six first-party categories ship today:
| Category | Stack |
|---|---|
blank |
(empty) |
web-app |
TypeScript + Vite + React |
ml-training |
Python 3 |
research-paper |
LaTeX |
api-service |
TypeScript + Express |
cli-tool |
TypeScript + commander |
Already have a codebase? armada detects your stack and scaffolds the team around it.
cd your-repo
armada init # interactive: detects stack, picks budget, scaffolds
opencode # boots into the CommodoreDeclarative alternative (skip the questionnaire):
armada init --stack nextjs-fastapi --budget balanced --yesFully autonomous (no permission prompts, agents run without asking):
armada init --yes --yoloarmada writes its own files and never clobbers yours:
| File | Written if... |
|---|---|
.opencode/agent/<role>.md |
Always (armada-owned, re-writable) |
.opencode/commands/*.md |
Always (armada-owned) |
armada/armada.yaml |
Always (the manifest, source of truth) |
armada/REQUIREMENTS.md |
Only if absent |
opencode.json |
Only if absent |
AGENTS.md |
Only if absent |
If opencode.json or AGENTS.md already exist, armada respects them and only writes the
keys it owns.
opencode # boots into the Commodore (orchestrator)As the Admiral (user), you command the fleet through the Commodore. The Commodore is the only agent you ever talk to — it plans, delegates, and gates, but never writes code itself.
Type your feature request in plain language:
"Add a /settings page where users can update their display name and email."
The Commodore reads the contract (armada/REQUIREMENTS.md). If it's blank, it does not
start building. Instead, it co-writes the contract with you:
- Asks one question at a time — scope, users, auth, data model, pages
- Drafts phases with success criteria
- Iterates until you explicitly approve
No implementation starts without your approval.
Once you approve, the Commodore:
- Dispatches backend-dev (Galleon) and frontend-dev (Clipper) as parallel background subagents
- Reviews their evidence (diffs, test output, screenshots)
- Sends QA (Corvette) for end-to-end tests
- Sends the adversary (Xebec) on a hostile review pass
- Gates every phase on passing success criteria
You'll see the dispatches and evidence in the opencode TUI. The Commodore comes back to you (the Admiral) only for judgment calls — ambiguous decisions, permission overrides, or contract changes.
Session crashed? No problem:
opencode # boots into the orchestrator
# It reads armada/state/active.json and reports:
# "Resume: feature X, phase 2, evidence in, next action Y."Or from the CLI:
armada resume # drift list + resume line
armada status # where the fleet is right nowEach feature is its own contract + state file. For true parallel isolation, use git worktrees:
armada voyage settings # creates worktree + boots lane (single entry point)
armada fleet # dashboard: one row per active laneFeatures in separate worktrees cannot collide. Features in the same checkout rely on the disjoint-files rule (each phase writes its own files).
The old two-command flow (armada feature new <name> --worktree + armada voyage sandbox/<name>) is now a single command: armada voyage <name>. The feature new, feature list, and feature close commands print deprecation warnings and delegate to their voyage equivalents. They will be removed in v2.0.
Background voyages run inside dedicated tmux sessions ("ships"). As the Admiral, you are never locked out of an active run:
armada voyage settings # boots and auto-attaches terminal
tmux attach -t voyage-settings # attach to any session manually from any shellWhile attached:
- Watch the Commodore dispatch specialists and run quality gates live
- Answer clarifying questions or approve contract adjustments on the fly
- Detach cleanly (
Ctrl+BthenD) at any time — the voyage continues running safely in the background
armada status # active feature, phase, next action
armada status --json # machine-readable
armada fleet # cross-lane dashboard (all active lanes)
armada doctor # environment health check
armada resume # drift report after a crashnpm install -g @rafamacalaba/armada@latest
armada init --from-armada armada/armada.yaml # re-scaffold from manifest
armada doctor # verifyThe re-scaffold merges armada-owned keys into opencode.json surgically — every other key
survives byte-for-byte.
armada uninstall # removes armada-owned files only
armada uninstall --all # also removes generated AGENTS.md, opencode.json, contract
armada uninstall --dry-run # preview what would be removed- Operator Manual — the CLI in detail, full flag table, model catalog
- Architecture — how armada works under the hood
- Why armada? — the full narrative: problem, solution, proof