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 of seven 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 validator agent screens each plan before it reaches you, no code is written until you approve, and failed runs resume from their last checkpoint.

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 typed graph interrupt 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. 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 to Postgres — driver-reported, or computed from a model pricing table auto-refreshed from OpenRouter's models API. The usage API serves totals, per-model breakdowns, and daily trends.
  • Per-agent driver routing, not just model names. Each of the seven roles — architect, developer, reviewer, task reviewer, evaluator, brainstormer, and plan validator — selects its own driver and model: 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 — all in one profile. An Oracle agent is also available for ad-hoc consultation.
  • Every run is a trajectory. Each invocation is recorded verbatim, with no truncation or summarization, as an ATIF (Agent Trajectory Interchange Format) file, so 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
  • CLI + 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"

    The CLI prints ✓ Workflow started with a workflow ID, and the run appears in the dashboard.

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