Aria's Agent Fleet

Autonomous multi-agent AI engineering team — runs locally on Ollama or on Claude Code, Cursor, Codex, and Kimi.

An autonomous, project-agnostic multi-agent engineering organisation led by Aria. Drop it into any repository and you get 30 named AI agents, 20 governance rules, 12 reusable skills, a live command-centre dashboard, a persistent knowledge graph, an autonomous pipeline, and a full control plane.

Default mode: fully local. The fleet runs on Ollama with whatever models you have pulled. Claude CLI handles all tool execution (bash, file read/write, web fetch, MCP) while Ollama does the inference — no cloud API key required. Switch to cloud models any time with aria --cloud.

Who is this for?

• Engineering teams who want an AI agent fleet that ships features end-to-end without manual prompt engineering per task
• Solo developers who want a full autonomous AI engineering team — frontend, backend, QA, security, SEO, and release — in a single drop-in package
• Privacy-conscious teams who need everything running locally on their own hardware
• AI-native startups looking for a production-ready multi-agent orchestration system with governance, cost control, and human approval gates built in
• Platform engineers evaluating LLM orchestration frameworks across Ollama, Claude Code, Codex, or Kimi

In 60 seconds

You type one command: aria "your goal". Aria turns it into a planned, reviewed, evidence-backed result.

• Aria (the orchestrator) triages your request into a single testable task, reads the code graph for the impact radius, assembles the minimum squad, picks the right model per role, then launches and coordinates the team to completion. She never writes production code, never lets an agent approve its own work, and brokers every permission.
• The agents are 29 specialists (architecture, frontend, backend, data, QA, security, release, SEO, docs…). Each owns one area, runs in its own session, warm-starts with a context brief, works under a scope lock, and ends with a completion report and a ready signal.
• The backend is Ollama — all inference stays on your machine. Claude CLI provides the tool infrastructure (bash, file ops, MCP servers).

aria "add permission-aware saved filters to the boards module"

Getting started

Prerequisites (install once)

Ollama — local model server

brew install ollama          # macOS
ollama serve                 # start the daemon
ollama pull qwen3.6          # or any model: llama3.2, deepseek-r1, qwen2.5-coder…

Claude CLI — tool executor (bash, file ops, MCP)

npm install -g @anthropic-ai/claude-code
claude login                 # browser OAuth — no API key needed

PyYAML — only third-party Python dependency

pip install pyyaml

Setup — one command

npx aria-fleet

That's it. The installer handles everything:

| Step | What it does | |---|---| | 1 | Installs Homebrew (if missing) | | 2 | Installs + starts Ollama, pulls a model if you have none | | 3 | Installs Claude CLI, prompts claude login if needed | | 4 | Installs Python + PyYAML | | 5 | Copies fleet files into your current directory | | 6 | Detects your models and configures tier routing | | 7 | Symlinks aria to /usr/local/bin/aria |

After it finishes, open a new terminal and run:

aria "your first task"

ollama-routing.yaml is gitignored — each user runs the installer once for their own machine and model set.

How it works

aria "task"
  │
  ├─ checks Ollama is running
  ├─ loads .project/config/ollama-routing.yaml  (your model assignments)
  ├─ creates task workspace
  │
  └─ claude -p "<aria prompt>" --model qwen3.6:latest
       │
       ├─ ANTHROPIC_BASE_URL=http://localhost:11434
       │   (Ollama speaks the Anthropic Messages API natively — no proxy needed)
       │
       ├─ Claude CLI tools fire locally: Bash, Read, Write, MCP…
       └─ Ollama does all inference

Ollama 0.3+ natively implements the Anthropic Messages API at /v1/messages, including tool use. No translation layer or proxy is required.

Model routing

On first run ollama_setup.py detects your local models, scores them by capability, and asks how to assign them to role tiers:

Found 4 model(s).

  [1] deepseek-r1:14b    9.1 GB   reasoning model → deep
  [2] qwen2.5-coder:7b   4.7 GB   coding model 7b → code
  [3] llama3.2:latest    2.0 GB   4b / 2.0 GB → fast
  [4] phi4:latest        2.3 GB   unknown size → balanced

  [1] One model for everything
  [2] Map models to tiers  (recommended)

The mapping is saved to .project/config/ollama-routing.yaml. Reconfigure at any time:

aria --setup          # re-run model routing setup
aria --models         # show current tier → model assignments
aria --plan           # full per-role model plan (all 30 agents)

| Tier | Used for | Typical model | |---|---|---| | deep | orchestration, architecture, security | largest reasoning model | | code | backend, platform, database | coding specialist | | qa | QA strategy, visual analysis | capable general model | | balanced | frontend, docs, product | mid-size general model | | research | long-context reading | fast model | | fast | bulk tasks, iteration | small fast model | | utility | trivial edits, unit tests | smallest model |

aria command reference

aria "implement the login page"     # create task + start Aria on Ollama
aria TASK-1001 "my feature"         # create task with explicit ID
aria TASK-1783927231                # resume an existing task
aria                                # interactive prompt

aria --cloud "implement login"      # use Anthropic cloud models instead
aria --runtime ollama "task"        # raw Ollama CLI (text only, no tool calls)
aria --setup                        # reconfigure model routing
aria --models                       # show model → tier assignments
aria --plan                         # full per-role model plan
aria --status                       # fleet status

Runtimes

The same fleet works on any harness. The default is claude-ollama — Claude CLI tools with Ollama inference.

| Runtime | LLM backend | Tool calls | Set up | |---|---|---|---| | claude-ollama (default) | Ollama (local) | ✅ full Claude CLI tools | python3 scripts/ollama_setup.py | | claude-code | Anthropic cloud | ✅ full Claude CLI tools | claude login + optional python3 scripts/claude_setup.py | | ollama | Ollama (local) | text only | python3 scripts/ollama_setup.py | | cursor | Cursor models | Cursor native | scripts/setup_model_routing.sh | | codex | OpenAI | Codex native | OPENAI_API_KEY | | kimi | Moonshot | Kimi native | MOONSHOT_API_KEY | | manual | — | — | prints prompt + model to paste |

Switch runtime for a single run:

aria --cloud "task"                         # Anthropic cloud
aria --runtime ollama "task"                # raw Ollama CLI
PROJECT_RUNTIME=codex ./fleet run TASK-1001 backend-lead

Model economy. Each role has a capability tier (model-routing.yaml → profile_tiers). For the active runtime the orchestrator picks the cheapest model whose tiers cover that role (providers.yaml). Flagship deep models handle orchestration, architecture, and security — everything else uses smaller, cheaper models.

Documentation

• How Aria thinks and works
• How the agents work
• What Aria's Fleet can do
• What goes to which model and why
• Docs index · Constitution (AGENTS.md) · Install

Architecture at a glance

The loop Aria runs for every request — you only touch the two ends (aria … and approvals):

flowchart LR
  U["You: aria goal"] --> A["Aria<br/>orchestrator"]
  A --> T["triage<br/>one testable task"]
  T --> I["impact radius<br/>from code graph"]
  I --> P["model plan<br/>cheapest capable per role"]
  P --> O["orchestration plan<br/>squad, gates, worktrees"]
  O --> L["launch squad"]
  L --> G{"gates<br/>QA · security · migration"}
  G -->|pass| R["release recommendation"]
  G -->|block| E["escalation"]
  E --> A
  R --> U

The fleet is hub-and-spoke — the user talks only to Aria; Aria summons the specialists:

flowchart TB
  U["You"] -->|"aria only"| ARIA["Aria — orchestrator"]
  ARIA --> STR["Strategy<br/>Vera · Sage · Mnemo"]
  ARIA --> ARCH["Architecture<br/>Atlas · Cipher · Nexus · Canvas"]
  ARIA --> IMPL["Implementation<br/>Nova · Forge · Bedrock · Shift<br/>Bridge · Anchor · Blaze · Pixel · Lumis · Apex"]
  ARIA --> QA["Quality<br/>Scout · Rover · Prism · Lens"]
  ARIA --> REL["Release & Security<br/>Shield · Helm"]
  ARIA --> GROW["Growth & Docs<br/>Beacon · Trace · Quill · Pulse · Signal · Scribe"]

Each spoke runs in its own session (write-capable agents in their own git worktree), on the cheapest capable model for your runtime.

Shortcuts: ./fleet and make

Every common action has a short form. ./fleet help lists them.

./fleet status                              # agents, skills, tools, runtime, API keys
./fleet plan --runtime claude-ollama        # per-role model + relative cost
./fleet orchestrate TASK-1001 "Title"       # start Aria
./fleet run TASK-1001 backend-lead          # launch one agent
./fleet next TASK-1001                      # advance the pipeline
./fleet cost TASK-1001                      # recorded spend for a task
./fleet setup-ollama                        # configure Ollama model routing
./fleet setup-claude                        # configure Claude cloud routing
./fleet test                                # end-to-end self-test
# make equivalents: make status | make plan | make run TASK=.. AGENT=.. | make cost TASK=..

Run from the IDE or the CLI

The same agents run in two interchangeable modes controlled by PROJECT_AGENT_MODE:

| | PROJECT_AGENT_MODE=ide (default) | PROJECT_AGENT_MODE=cli | |---|---|---| | Where it runs | You open the session in your IDE | Headless via the CLI | | What the scripts do | Print the opening prompt + model + worktree to open | Launch claude -p … for you | | Best for | Hands-on, reviewing as you go | Automation, CI/CD, running the whole squad unattended |

# Kick off the orchestrator (Aria) for a task
scripts/start_orchestrator.sh TASK-1001 "Your task title"
PROJECT_AGENT_MODE=cli scripts/start_orchestrator.sh TASK-1001

# Launch any single agent
scripts/launch_agent.sh TASK-1001 backend-lead
PROJECT_AGENT_MODE=cli scripts/launch_agent.sh TASK-1001 backend-lead

# Advance the whole pipeline
PROJECT_AGENT_MODE=cli scripts/run_next_agents.sh TASK-1001

Aria — the Chief Orchestrator

Name: Aria | Slug: aria | Model: deep tier (your largest local model, or Opus on cloud)

Aria is the single coordination layer. She does not write production code. Her job is to turn a task packet into a running execution graph and keep it moving.

What Aria does on session start

1. python3 scripts/build_code_graph.py --incremental   ← refresh code graph
2. bash scripts/launch_dashboard.sh --no-scan           ← start command centre
3. Check .project/tasks/pending-triage.signal             ← pick up auto-generated tasks
4. Check all escalation.md files                        ← acknowledge and route
5. bash scripts/run_next_agents.sh <TASK-ID>            ← advance blocked pipelines

How Aria plans a task

Task packet → triage.md → orchestration-plan.md → worktree assignments → warm_start each agent

Before assigning any implementation work, Aria reads the code graph to produce an impact radius — which files, APIs, and tests will be affected — so agents never guess what will break.

Aria's control plane

python3 scripts/aria_control.py --task TASK-1001 --list
python3 scripts/aria_control.py --task TASK-1001 --agent forge \
  --message "Use FilterChip from src/components/ui/ — don't build your own"
python3 scripts/aria_control.py --task TASK-1001 --agent nova \
  --pause --reason "Human decision pending"
python3 scripts/aria_control.py --task TASK-1001 --all \
  --stop --reason "Production incident"

Agent roster

30 agents across 7 functional groups. Every agent has a unique name, a model tier, a readonly flag, and (for browser-capable agents) a browser_access level.

Orchestration & strategy

| Name | Slug | Tier | R/W | Browser | |---|---|---|---|---| | Aria | aria | deep | read | read_only | | Vera | portfolio-product-director | deep | read | — | | Sage | human-liaison | balanced | read | — | | Mnemo | memory-keeper | balanced | write | — |

Sage structures every human decision into one question with 2–4 options. Before raising a request, Sage checks Mnemo's decision memory — if a similar decision was made before, it presents the precedent rather than a fresh question.

Mnemo maintains the persistent knowledge graph at .project/knowledge/. After every completed task it extracts facts, decisions, and patterns. Before every new task it writes per-agent context briefs so agents start with pre-loaded context instead of reading the entire codebase.

Architecture

| Name | Slug | Tier | R/W | |---|---|---|---| | Atlas | chief-solution-architect | deep | read | | Cipher | identity-rbac-architect | deep | read | | Nexus | data-architect | deep | read | | Canvas | ux-design-architect | deep | read |

All architecture agents are readonly: true — they produce plans, ADRs, and contracts; they never touch production code.

Implementation

| Name | Slug | Tier | R/W | Browser | |---|---|---|---|---| | Nova | frontend-lead | deep | write | — | | Lumis | elite-frontend-experience | deep | write | read_only | | Apex | elite-homepage-design | deep | write | read_only | | Pixel | frontend-worker | balanced | write | — | | Forge | backend-lead | code | write | — | | Bedrock | platform-engineer | code | write | — | | Shift | database-migration-engineer | code | write | — | | Bridge | integration-manager | code | write | — | | Anchor | infrastructure-sre | code | write | read_only | | Blaze | performance-engineer | code | write | — |

QA

| Name | Slug | Tier | R/W | Browser | |---|---|---|---|---| | Scout | qa-lead | qa | read | — | | Rover | browser-exploration-qa | fast | read | full | | Prism | rbac-persona-qa | qa | read | — | | Lens | visual-accessibility-qa | qa | read | — |

Rover has full browser access — it can navigate, click, fill forms, run JS, and capture screenshots. Follows the recursive exploration protocol with hard termination criteria: depth 8, 150 page states, 45 minutes, or Scout's coverage-sufficient signal.

Release & security

| Name | Slug | Tier | R/W | |---|---|---|---| | Shield | security-reviewer | deep | read | | Helm | release-manager | code | read |

SEO, content & research

| Name | Slug | Tier | R/W | Browser | |---|---|---|---|---| | Beacon | seo-director | balanced | read | — | | Trace | technical-seo | code | write | read_only | | Quill | content-strategist | balanced | read | — | | Pulse | market-researcher | research | read | read_only | | Signal | ai-visibility | research | read | read_only | | Scribe | documentation-agent | balanced | write | — |

Product/domain agents (add your own)

No product-specific agents are bundled — this package is project-agnostic. Add a readonly: true product-<domain> agent under .cursor/agents/ for each product area, register it in model-routing.yaml, and the engineering team builds against those specs.

Agent permissions

| Role group | Repo | Code | Merge | Deploy | |---|---|---|---|---| | aria | read | deny | deny | deny | | architects | read | deny | deny | deny | | product agents | read | deny | deny | deny | | implementation agents | scoped write | — | deny | deny | | qa agents | read | deny | deny | deny | | security reviewer | read | deny | deny | deny | | integration manager | branch write | — | PR only | deny | | release manager | read | — | human-approved | deny | | human owner | admin | allow | allow | allow |

Mandatory human approval is required for: auth changes, RBAC/tenant changes, financial actions, destructive bulk operations, production data migrations, and production deployment.

The 20 rules

Rules in .cursor/rules/ are injected into agent context. alwaysApply: true rules load in every session.

| # | File | Always | Purpose | |---|---|---|---| | 00 | constitution | ✅ | Non-negotiable engineering principles | | 01 | orchestration | — | Task decomposition, handoffs, escalation protocol | | 02 | architecture-boundaries | — | Service boundaries and contract rules | | 03 | security-rbac | ✅ | Authorization requirements for all code | | 05 | testing-evidence | — | Test and evidence requirements | | 06 | ui-design-system | — | Design token and component rules | | 07 | api-backend | — | API and backend conventions | | 08 | database-migrations | — | Safe migration protocol | | 10 | seo-public-web | — | SEO and public page requirements | | 11 | documentation | — | Documentation standards | | 12 | release-gate | — | Release readiness checklist | | 13 | cost-and-context | — | Multi-model cost control, 3-strike escalation | | 14 | knowledge-graph | — | Mnemo context brief loading protocol | | 15 | task-decomposition | — | 150-line limit, subtask protocol | | 16 | browser-use | — | Playwright MCP safety and usage | | 17 | agent-resilience | ✅ | Warm-start, scope lock, checkpoints, heartbeat | | 18 | collaboration | ✅ | Hub-and-spoke vs peer consultation | | 19 | control-plane | ✅ | Control signal polling protocol | | 20 | fleet-governance | ✅ | Aria sole contact, permission brokering, capability gaps, script-first, token economy | | 21 | runtime-and-model-economy | ✅ | Run on any runtime; cheapest capable model per role; token economy |

Skills

| Skill | Purpose | |---|---| | ticket-triage | Classify a task, identify affected products, assemble minimum squad | | agent-handoff | Structured handoff with scope, evidence, and next owner | | architecture-plan | Architecture review with ADR, contracts, failure modes | | api-development | API implementation checklist (auth, idempotency, tests, docs) | | browser-exploration | Recursive QA with termination criteria | | database-migration | Safe migration (expand-migrate-contract) | | market-research | Competitor and market analysis framework | | rbac-review | RBAC matrix review — 20 personas × 11 dimensions | | release-validation | Gate-by-gate release readiness verification | | security-review | Threat model, authorization review, findings disposition | | seo-audit | Crawlability, metadata, structured data, performance | | ui-development | Frontend checklist (tokens, a11y, permission states) |

Scripts

# Ollama + Claude CLI setup
python3 scripts/ollama_setup.py             # configure model routing (interactive)
python3 scripts/ollama_setup.py --auto      # auto-assign, no prompts
python3 scripts/ollama_setup.py --show      # print current routing
python3 scripts/claude_setup.py             # configure Claude cloud routing (optional)

# The aria command (after symlinking to PATH)
aria "task title"                           # create task + start Aria on Ollama
aria --cloud "task title"                   # use Anthropic cloud models
aria --setup                                # reconfigure model routing
aria --models                               # show tier → model assignments
aria --plan                                 # full per-role model plan

# Task management
python3 scripts/new_task.py TASK-1001 "Title"       # create task workspace
python3 scripts/task_status.py                       # view all task statuses
python3 scripts/validate_agent_package.py            # validate all config files

# Agent lifecycle
bash scripts/start_orchestrator.sh TASK-1001 "Title"        # kick off Aria
bash scripts/launch_agent.sh TASK-1001 backend-lead         # launch one agent
bash scripts/warm_start_agent.sh TASK-1001 backend-lead     # prepare + print opening prompt
bash scripts/create_agent_worktree.sh TASK-1001 backend-lead  # isolated git worktree
bash scripts/run_next_agents.sh TASK-1001                   # advance pipeline

# Runtime & model economy
bash scripts/detect_runtime.sh                           # active runtime
python3 scripts/fleet_status.py                          # whole-fleet status
python3 scripts/plan_models.py --runtime claude-ollama   # per-role model + cost
python3 scripts/select_model.py backend-lead --explain   # one role's model + why
bash scripts/sync_runtime.sh claude-code                 # materialise fleet into a layout

# Fleet governance (rule 20)
python3 scripts/new_agent.py <slug> --name N --model PROFILE --role "..." [--write]
python3 scripts/new_skill.py <slug> --description "..."
python3 scripts/add_tool.py <name> --command CMD --args "..."
bash scripts/request_permission.sh TASK-1001 backend-lead "<perm>" "<reason>"
python3 scripts/aria_permissions.py --task TASK-1001 --list
python3 scripts/aria_permissions.py --task TASK-1001 --grant <id> --note "..."

# Dashboard
bash scripts/launch_dashboard.sh
python3 scripts/build_code_graph.py
python3 scripts/build_code_graph.py --incremental
python3 scripts/build_code_graph.py --watch

# Aria control plane
python3 scripts/aria_control.py --task TASK-1001 --list
python3 scripts/aria_control.py --task TASK-1001 --agent forge --message "..."
python3 scripts/aria_control.py --task TASK-1001 --agent nova --pause --reason "..."
python3 scripts/aria_control.py --task TASK-1001 --all --stop --reason "..."

# Autonomy
python3 scripts/event_router.py --payload '{"type":"ci_failure",...}'
bash scripts/post_deploy_monitor.sh TASK-1001 30
python3 scripts/detect_contract_drift.py --ci
python3 scripts/calibrate_triggers.py

# Cost ledger
PROJECT_RECORD_COST=true PROJECT_AGENT_MODE=cli ./fleet run TASK-1001 backend-lead
python3 scripts/cost_report.py --task TASK-1001
python3 scripts/cost_report.py --all

# Git hooks
bash scripts/install_hooks.sh

Dashboard

Start with bash scripts/launch_dashboard.sh. Opens at .project/dashboard/index.html, polls the API on :7432 every 10 seconds.

Tab 1 — Orchestration: Aria as a glowing hub with active agents arranged around it. Agent cards show name, model, status, runtime, and token count.

Tab 2 — Memory: Mnemo's knowledge graph. Past decisions Sage recorded, learned patterns from completion reports.

Tab 3 — Code Graph: D3.js force-directed spider web of the codebase. Blue = file, green = function, orange = API route, red = API call, purple = component.

Persistent memory and code graph

Mnemo maintains .project/knowledge/ — readable by any agent, no tooling required.

.project/knowledge/
├── graph.yaml                        ← knowledge graph index
├── platform/shared-capabilities.md  ← authoritative shared service descriptions
├── agents/context-briefs/            ← per-agent pre-loaded context (one per task)
├── agents/learned-patterns.md        ← recurring patterns from completion reports
├── tasks/decisions/                  ← past human decisions (Sage reuses these)
└── code-graph/graph.json             ← live code dependency graph

build_code_graph.py maps the full codebase — file imports, function definitions, API routes, outbound API calls — for TypeScript, JavaScript, Python, and Go. Aria reads this before every orchestration plan and produces an impact radius so agents know exactly what will break before they change anything.

Autonomous pipeline

Event-driven tasks — CI failures, CVEs, error spikes, latency breaches auto-generate task packets via event_router.py.

Pipeline advancement — run_next_agents.sh reads the dependency graph and starts agents whose dependencies are satisfied, without Aria actively polling.

Post-deploy monitoring — post_deploy_monitor.sh watches error rates and latency against SLO baselines for 30 minutes. Sustained breach auto-creates a rollback task.

Auto-approval tiers — docs, test additions, and patch bumps self-approve. Auth, finance, RBAC, and production deploy always require human approval.

Docker stack

docker/agent-supervisor.yml adds four services to your Docker Compose stack:

agent-task-db      — SQLite state store (WAL mode, safe for concurrent agents)
agent-supervisor   — pipeline launcher (polls every 30 seconds)
agent-mnemo        — memory sidecar (watches for completion reports via inotify)
agent-event-relay  — webhook receiver on :9876 → event_router.py

docker-compose -f docker-compose.yml -f docker/agent-supervisor.yml up

Configuration reference

| File | Purpose | |---|---| | .project/config/ollama-routing.yaml | Ollama tier → model assignments (gitignored, generated by ollama_setup.py) | | .project/config/claude-routing.yaml | Claude cloud tier overrides (gitignored, generated by claude_setup.py) | | .project/config/model-routing.yaml | Model profiles, role assignments, fallbacks | | .project/config/providers.yaml | Provider model catalog (Anthropic, OpenAI, Moonshot, Ollama) | | .project/config/runtimes.yaml | Runtime adapters and command templates | | .project/config/agent-permissions.yaml | Per-role permissions | | .project/config/quality-gates.yaml | 16-stage lifecycle and gate triggers | | .project/config/product-map.yaml | Template: your products/areas + shared capabilities | | .project/config/qa-personas.yaml | 20 personas, 11 test dimensions | | .project/config/browser-access-policy.yaml | Per-agent browser permissions | | .project/config/auto-approval-policy.yaml | Risk-tiered approval tiers | | .project/config/slo-baselines.yaml | Latency and error rate thresholds | | .project/config/event-triggers.yaml | External signals → auto tasks | | .project/config/docker-environment.yaml | Container env vars and observability |

Non-negotiable rules

1. Never weaken tenant isolation or authorization to make a feature easier.
2. Any AI or automation feature may only perform actions the authenticated user is authorized to perform.
3. UI visibility is not authorization — every backend operation enforces permissions independently.
4. No production code merges without reproducible tests and evidence.
5. No agent approves its own implementation, security remediation, or release.
6. Every schema migration requires forward validation, rollback, and data-impact notes.
7. Public pages require SEO, accessibility, analytics, and performance checks.
8. Cross-cutting behaviour uses shared services — never feature-local duplicates.
9. Feature behaviour is documented in acceptance criteria before implementation begins.
10. Agents declare uncertainty and never invent repository facts, credentials, or test results.

Aria's Agent Fleet — 30 agents · 20 rules · 12 skills · 35 scripts · local-first on Ollama · ./fleet + make · cost ledger · runs on Ollama · Claude Code · Cursor · Codex · Kimi