Amelia: Agentic Orchestrator

Amelia is multi-agent orchestration for software development with human-in-the-loop approval gates and end-to-end observability.

This README covers installation and the CLI reference. For the architecture, design decisions, and full capability overview — drivers, dashboard, queueing, sandbox execution, and issue-tracker integration — see the project page.

Prerequisites

• Python 3.12+
• uv - Python package manager (install guide)
• Git
• LLM access - one of:
  • OpenRouter API key (for api driver)
  • Claude CLI (for claude driver)
  • Codex CLI (for codex driver)

Note

Model selection matters. The api driver requires models with reliable tool-calling capabilities. See the documentation for details.

Quick Start

1. Install Amelia

# Install uv (Linux/macOS)
curl -LsSf https://astral.sh/uv/install.sh | sh

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

# Set your API key
export OPENROUTER_API_KEY="sk-..."

Important

For Claude Code users: install the Beagle plugin for Amelia skills and commands.

2. Run Your First Task

mkdir my-app && cd my-app
git init

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

# Start the server (opens dashboard at localhost:8420)
amelia dev

In another terminal:

cd my-app
amelia start --title "Create a Python CLI that fetches weather for a city using wttr.in"

The Architect agent creates a plan. Open the dashboard at localhost:8420 to review and approve it. Once approved, the Developer agent implements the code.

3. Use an Issue Tracker

To work from GitHub or Jira issues instead of ad-hoc tasks, create a profile with a tracker:

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

# Start a workflow for issue #123
amelia start 123

You can also configure profiles in the dashboard at localhost:8420/settings. See the documentation for all options including Jira integration and per-agent model settings.

Alternative Installation

Run from Source

# Clone the repo
git clone https://github.com/existential-birds/amelia.git
cd amelia
uv sync

# Run from your project directory
cd /path/to/your/project
/path/to/amelia/uv run amelia dev

Note

Run commands from your project root—agents can't help with code they can't see. Configuration is stored in PostgreSQL and shared across all projects.

How It Works

Amelia runs your task through specialized agents (Architect → Developer → Reviewer) on a LangGraph state machine, pausing at approval gates you control. See the project page for the full architecture and design decisions.

CLI Commands

Server

Command	Description
amelia dev	Start server + dashboard (port 8420)
amelia server	API server only

Workflows (requires server running)

Command	Description
amelia start 123	Start workflow for issue #123
amelia start --title "desc"	Run ad-hoc task without issue tracker
amelia start 123 --queue	Queue workflow for later execution
amelia run abc-123	Start a queued workflow
amelia status	Show active workflows
amelia approve	Approve the generated plan
amelia reject "feedback"	Reject with feedback
amelia cancel	Cancel active workflow

Local (no server required)

Command	Description
amelia review --local	Review uncommitted changes

See the documentation for the complete CLI reference.

Configuration

Profiles and server settings are managed via the amelia config CLI or the dashboard at localhost:8420/settings. See the project page for profile setup, per-agent model routing, and Jira integration.

License

Amelia is licensed under the Apache License 2.0.