amelia

github.com/existential-birds/amelia

What it is

Amelia is multi-agent orchestration for software development, with human-in-the-loop approval gates, a per-token cost ledger, and verbatim trajectory recording. Use it when a task is too large for a single agent turn but well-defined enough to decompose: migrating a codebase, sweeping an audit across many files, or driving a constrained but lengthy job to completion. Work runs across multiple specialized agents, supervised through both a CLI and a real-time dashboard.

How it works

Amelia drives a LangGraph state machine whose core loop is three configurable agent roles:

  • Architect: reads the issue or task and produces a step-by-step implementation plan.
  • Developer: executes the plan, writing code and running commands.
  • Reviewer: reviews the Developer's changes and requests fixes if needed.

A plan validator node screens each plan before it reaches you. No code is written until you approve. Failed runs resume from their last checkpoint. For non-final tasks, a separate task reviewer role can use a different model than the final-task reviewer.

Design decisions

A few choices separate Amelia from running the same roles on a generic framework:

Approval is a state-machine edge, not a console prompt. Frameworks typically implement human-in-the-loop as an input pause in a chat loop. Amelia models it as a first-class graph interrupt: the workflow is compiled with interrupt_before=["human_approval_node"] and backed by a Postgres checkpointer. The workflow durably parks until a decision arrives: hours later, from a different client, across a server restart. Blocked workflows re-emit their approval requests when the server comes back up.

Credentials stay on the host. Docker-sandboxed agents execute behind a host-side proxy that injects API keys into outbound requests. Inside the container, a generated default-deny egress policy permits only the proxy and an explicit allowlist (Anthropic, OpenRouter, OpenAI, GitHub, npm, PyPI by default). The allowlist is applied as iptables OUTPUT rules that drop all other outbound traffic. Daytona cloud sandboxes are remote, so they receive provider credentials directly and rely on Daytona's own infrastructure for network isolation.

Cost is a ledger, not a log line. Every driver invocation persists input, output, cache-read, and cache-creation tokens plus dollar cost. Drivers report usage directly; when they do not, cost is computed from a model pricing table that auto-refreshes from OpenRouter's models API with Anthropic fallbacks. Since migration 016, per-agent detail lives in ATIF trajectory files and workflow rows hold thin aggregate columns (total cost, total tokens, total duration). The dashboard serves totals, per-model breakdowns, and daily trends.

Per-agent driver routing, not just model names. Each named agent role selects its own driver and model. The implementation graph's three core roles are typical: a frontier API model for the Architect, a CLI agent (Claude or Codex, typically subscription-priced rather than metered) for the Developer, a cheap model for review. Other configurable roles include an evaluator for review feedback triage, an oracle for ad-hoc consultation, and a brainstormer for ideation. All are defined in a single profile.

Every run is a trajectory. Each invocation is recorded verbatim, with no truncation or summarization, as an ATIF (Agent Trajectory Interchange Format) file. Each agent invocation becomes an embedded subagent trajectory within the workflow's parent trajectory file. Runs are replayable, auditable artifacts.

Capabilities

  • Multiple LLM drivers: OpenRouter, the Claude CLI, the Codex CLI, or any OpenAI-compatible endpoint, configurable per agent role.
  • Knowledge-grounded agents: ingest project docs (PDF, Markdown) into a pgvector-backed knowledge library that agents retrieve through semantic search. Embeddings use text-embedding-3-small (1536 dimensions) with an HNSW cosine index.
  • CLI and real-time dashboard: supervise workflows, review plans, and track per-model costs from the terminal or a React dashboard streaming workflow events over WebSocket.
  • Workflow queueing: queue issues, batch-generate plans, and control when execution starts.
  • Sandbox execution: run agents locally, in Docker (host-side key injection plus a generated default-deny network allowlist), or in Daytona cloud sandboxes (network isolation managed by Daytona's infrastructure).
  • Local review: run amelia review --local to review uncommitted changes without starting a workflow.
  • Issue tracker integration: work directly from GitHub or Jira issues instead of ad-hoc task descriptions.

Configuration (profiles, server settings, tracker integration) is stored in PostgreSQL and managed via the amelia config CLI or the dashboard settings page.

Install and usage

Amelia installs as a uv tool and runs as an orchestration service.

Prerequisites

  • uv installed
  • PostgreSQL (configuration, workflow checkpoints, cost ledger, knowledge library)
  • An LLM driver: an OpenRouter API key, the Claude CLI, or the Codex CLI

Steps

  1. Install the CLI:

    uv tool install git+https://github.com/existential-birds/amelia.git

  2. Create a profile that selects your driver and model, and activate it:

    amelia config profile create dev --driver api --model "minimax/minimax-m2" --activate

  3. Start the server and dashboard (opens at localhost:8420):

    amelia dev

  4. Kick off work, pointing Amelia at a tracker issue or an ad-hoc task:

    amelia start TASK-1 --title "Port the auth module to the new API"

Supervise the agents from the dashboard, approving or redirecting at each gate. Full install steps, the CLI reference, and configuration options live in the project's documentation. Companion agent skills and commands for Claude Code users are distributed through Beagle.

Source

github.com/existential-birds/amelia