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.