Amelia is multi-agent orchestration for software development with human-in-the-loop approval gates, defense-in-depth security, and end-to-end observability.
Warning
This project is under active development. APIs and configuration may change between releases. See the Roadmap for planned changes.
- Python 3.12+
- uv - Python package manager (install guide)
- Git
- LLM access - one of:
- OpenRouter API key (for
apidriver) - Claude CLI (for
claudedriver) - Codex CLI (for
codexdriver)
- OpenRouter API key (for
Note
Model selection matters. The api driver requires models with reliable tool-calling capabilities. See Troubleshooting for details.
# 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.
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 devIn another terminal:
cd my-app
amelia start --task "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.
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 123You can also configure profiles in the dashboard at localhost:8420/settings. See Configuration for all options including Jira integration and per-agent model settings.
# 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 devNote
Run commands from your project root—agents can't help with code they can't see. Configuration is stored in ~/.amelia/amelia.db and shared across all projects.
Amelia orchestrates three specialized agents through a LangGraph state machine:
Issue → Architect (plan) → Human Approval → Developer (execute) ↔ Reviewer (review) → Done
- Architect — reads the issue 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
You approve the Architect's plan before any code is written. The design follows 12-Factor Agents principles for reliable LLM-powered software.
See Architecture and Concepts for details.
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 --task "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 Usage Guide for the complete CLI reference.
Configuration is stored in SQLite (~/.amelia/amelia.db) and managed via CLI (amelia config) or the dashboard at localhost:8420/settings.
See Configuration Reference for profile setup, server settings, and Jira integration.
For full documentation, visit existential-birds.github.io/amelia.
Amelia is licensed under the Apache License 2.0, a permissive open-source license that allows free use, modification, and distribution.