Usage Guide

Complete reference for using Amelia in your projects.

For installation, see the Getting Started guide.

Project Setup

Create a profile using the CLI:

bash

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

# Or create a CLI-based profile (claude or codex)
amelia config profile create work \
  --driver claude \
  --tracker jira \
  --activate

Configuration

Amelia uses profile-based configuration managed through the CLI or dashboard. See the Configuration Reference for profile setup, driver options, server settings, and environment variables.

CLI Reference

Workflow Commands

These commands require the Amelia server to be running (amelia dev or amelia server).

`amelia start <ISSUE_ID>`

Start a new workflow for an issue in the current worktree.

bash

# Start workflow for GitHub issue #123
amelia start 123

# Start workflow with specific profile
amelia start 123 --profile work

Options:

--profile, -p - Profile name (see amelia config profile list)

The command auto-detects your git worktree and creates a workflow via the API server.

`amelia status`

Show status of active workflows.

bash

# Show workflow in current worktree
amelia status

# Show all workflows across all worktrees
amelia status --all

Options:

--all, -a - Show workflows from all worktrees

`amelia approve`

Approve the workflow plan in the current worktree.

bash

amelia approve

Use this after reviewing the Architect's generated plan. The workflow will proceed to the Developer phase.

`amelia reject <REASON>`

Reject the workflow plan with feedback.

bash

amelia reject "Please add error handling for the API calls"

The Architect will replan based on your feedback.

`amelia cancel`

Cancel the active workflow in the current worktree.

bash

# With confirmation prompt
amelia cancel

# Skip confirmation
amelia cancel --force

Options:

--force, -f - Skip confirmation prompt

Queue Workflow Commands

Queue workflows for later execution or to review plans before starting.

`amelia start <ISSUE_ID> --queue`

Queue a workflow without starting execution.

bash

# Queue workflow without starting
amelia start ISSUE-123 --queue

# Queue and generate plan for review
amelia start ISSUE-123 --queue --plan

Options:

--queue, -q - Queue workflow in pending state without starting
--plan - Run Architect to generate plan while queued (requires --queue)
--profile, -p - Profile name (see amelia config profile list)

The workflow will be created in pending state. Use amelia run to start execution.

`amelia run <WORKFLOW_ID>`

Start a pending workflow.

bash

# Start a specific pending workflow
amelia run abc-123-def

# Start all pending workflows
amelia run --all

# Start pending workflows for specific worktree
amelia run --all --worktree /path/to/repo

Options:

--all, -a - Start all pending workflows
--worktree, -w - Filter by worktree path (use with --all)

Queue Workflow Lifecycle

Queue - Workflow created in pending state, not executing
Plan (optional) - Architect runs while workflow remains queued
Start - Workflow transitions to in_progress and begins execution
Complete - Normal completion flow

Use Cases

Review before committing - Review Architect plans before spending compute on execution
Batch processing - Queue multiple issues for later processing
Managed concurrency - Queue work during active workflow execution

Server Commands

`amelia dev`

Start the development environment (API server + dashboard).

bash

# Default: localhost:8420
amelia dev

# Custom port
amelia dev --port 9000

# Server only (no dashboard)
amelia dev --no-dashboard

# Bind to all interfaces (for network access)
amelia dev --bind-all

Options:

--port, -p - Server port (default: 8420)
--no-dashboard - Skip starting the dashboard
--bind-all - Bind to 0.0.0.0 (exposes to network)

The dashboard is served from bundled static files at localhost:8420. For frontend development with hot module replacement (HMR), run pnpm dev in dashboard/ separately.

`amelia server`

Start the API server only (no dashboard dev server).

bash

# Default: localhost:8420
amelia server

# Custom port and host
amelia server --port 9000 --bind-all

# With auto-reload for development
amelia server --reload

Options:

--port, -p - Port to listen on
--bind-all - Bind to all interfaces (0.0.0.0)
--reload - Enable auto-reload for development

Local Commands (No Server Required)

`amelia plan <ISSUE_ID>`

Generate a plan without executing it. Calls the Architect directly without going through the server.

bash

# Generate plan for issue
amelia plan 123

# With specific profile
amelia plan 123 --profile home

Options:

--profile, -p - Profile name (see amelia config profile list)

Saves the plan to a markdown file in docs/plans/ for review before execution.

`amelia review --local`

Review uncommitted changes in the current repository.

bash

# Review local changes
amelia review --local

# With specific profile
amelia review --local --profile work

Options:

--local, -l - Review local uncommitted changes (required)
--profile, -p - Profile name (see amelia config profile list)

Runs the Reviewer agent on your git diff output.

REST API Reference

Base URL: http://localhost:8420/api

API documentation available at: http://localhost:8420/api/docs

Workflows

Create Workflow

bash

POST /api/workflows

bash

curl -X POST http://localhost:8420/api/workflows \
  -H "Content-Type: application/json" \
  -d '{
    "issue_id": "123",
    "worktree_path": "/path/to/your/project",
    "worktree_name": "my-project",
    "profile": "dev"
  }'

Request Body:

Field	Type	Required	Description
`issue_id`	string	Yes	Issue identifier (alphanumeric, dashes, underscores)
`worktree_path`	string	Yes	Absolute path to worktree directory
`worktree_name`	string	No	Custom worktree display name
`profile`	string	No	Profile name from settings
`driver`	string	No	Driver override (e.g., `api`)
`start`	boolean	No	Start workflow immediately (default: true). Set to false to queue.
`plan_now`	boolean	No	Run Architect when queuing (requires `start: false`).

Response: 201 Created

json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "message": "Workflow created for issue 123"
}

Behavior Matrix:

`start`	`plan_now`	Result
`true` (default)	ignored	Immediate execution
`false`	`false`	Queue only (pending state)
`false`	`true`	Queue and generate plan

List Workflows

bash

GET /api/workflows

bash

# List all workflows
curl http://localhost:8420/api/workflows

# Filter by status
curl "http://localhost:8420/api/workflows?status=in_progress"

# Filter by worktree
curl "http://localhost:8420/api/workflows?worktree=/path/to/project"

# Pagination
curl "http://localhost:8420/api/workflows?limit=10&cursor=abc123"

Query Parameters:

Parameter	Type	Description
`status`	string	Filter by status: `pending`, `in_progress`, `blocked`, `completed`, `failed`, `cancelled`
`worktree`	string	Filter by worktree path
`limit`	int	Max results per page (1-100, default: 20)
`cursor`	string	Pagination cursor from previous response

Response: 200 OK

json

{
  "workflows": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "issue_id": "123",
      "worktree_name": "my-project",
      "status": "in_progress",
      "started_at": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 1,
  "cursor": null,
  "has_more": false
}

List Active Workflows

bash

GET /api/workflows/active

bash

# All active workflows
curl http://localhost:8420/api/workflows/active

# Active in specific worktree
curl "http://localhost:8420/api/workflows/active?worktree=/path/to/project"

Returns workflows in pending, in_progress, or blocked status.

Get Workflow Details

bash

GET /api/workflows/{workflow_id}

bash

curl http://localhost:8420/api/workflows/550e8400-e29b-41d4-a716-446655440000

Response: 200 OK

json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "issue_id": "123",
  "worktree_path": "/path/to/project",
  "worktree_name": "my-project",
  "status": "blocked",
  "started_at": "2025-01-15T10:30:00Z",
  "completed_at": null,
  "failure_reason": null,
  "plan": null,
  "token_usage": null,
  "recent_events": []
}

Approve Workflow

bash

POST /api/workflows/{workflow_id}/approve

bash

curl -X POST http://localhost:8420/api/workflows/550e8400-e29b-41d4-a716-446655440000/approve

Approves a workflow that is blocked waiting for plan approval.

Response: 200 OK

json

{
  "status": "approved",
  "workflow_id": "550e8400-e29b-41d4-a716-446655440000"
}

Reject Workflow

bash

POST /api/workflows/{workflow_id}/reject

bash

curl -X POST http://localhost:8420/api/workflows/550e8400-e29b-41d4-a716-446655440000/reject \
  -H "Content-Type: application/json" \
  -d '{"feedback": "Please add unit tests for the new functions"}'

Request Body:

Field	Type	Required	Description
`feedback`	string	Yes	Rejection reason for the Architect

Response: 200 OK

json

{
  "status": "rejected",
  "workflow_id": "550e8400-e29b-41d4-a716-446655440000"
}

Cancel Workflow

bash

POST /api/workflows/{workflow_id}/cancel

bash

curl -X POST http://localhost:8420/api/workflows/550e8400-e29b-41d4-a716-446655440000/cancel

Response: 200 OK

json

{
  "status": "cancelled",
  "workflow_id": "550e8400-e29b-41d4-a716-446655440000"
}

Start Workflow

bash

POST /api/workflows/{workflow_id}/start

bash

curl -X POST http://localhost:8420/api/workflows/550e8400-e29b-41d4-a716-446655440000/start

Starts a pending workflow. Returns 409 if workflow is not in pending state.

Response: 200 OK

json

{
  "status": "started",
  "workflow_id": "550e8400-e29b-41d4-a716-446655440000"
}

Start Batch

bash

POST /api/workflows/start-batch

bash

curl -X POST http://localhost:8420/api/workflows/start-batch \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_ids": ["uuid-1", "uuid-2"]
  }'

Start multiple pending workflows at once.

Request Body:

Field	Type	Required	Description
`workflow_ids`	array	No	Specific workflow IDs to start. If null, starts all pending.
`worktree_path`	string	No	Filter by worktree path (when starting all pending).

Response: 200 OK

json

{
  "started": ["uuid-1", "uuid-2"],
  "errors": {
    "uuid-3": "Workflow not found"
  }
}

Health Checks

Liveness Probe

bash

GET /api/health/live

bash

curl http://localhost:8420/api/health/live

Response: 200 OK

json

{"status": "alive"}

Readiness Probe

bash

GET /api/health/ready

bash

curl http://localhost:8420/api/health/ready

Response: 200 OK

json

{"status": "ready"}

Detailed Health

bash

GET /api/health

bash

curl http://localhost:8420/api/health

Response: 200 OK

json

{
  "status": "healthy",
  "version": "0.1.0",
  "uptime_seconds": 3600.5,
  "active_workflows": 2,
  "websocket_connections": 1,
  "memory_mb": 128.5,
  "cpu_percent": 2.3,
  "database": {
    "status": "healthy",
    "mode": "wal"
  }
}

WebSocket Events

WebSocket /api/ws/events

Connect for real-time workflow updates.

javascript

const ws = new WebSocket('ws://localhost:8420/api/ws/events');

// Subscribe to specific workflow
ws.send(JSON.stringify({ type: 'subscribe', workflow_id: 'uuid' }));

// Subscribe to all workflows
ws.send(JSON.stringify({ type: 'subscribe_all' }));

// Unsubscribe
ws.send(JSON.stringify({ type: 'unsubscribe', workflow_id: 'uuid' }));

// Handle events
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.type === 'event') {
    console.log('Workflow event:', data.payload);
  } else if (data.type === 'ping') {
    ws.send(JSON.stringify({ type: 'pong' }));
  }
};

Query Parameters:

Parameter	Type	Description
`since`	string	Event ID for backfill on reconnect

Server Messages:

{"type": "event", "payload": WorkflowEvent} - Workflow event
{"type": "ping"} - Heartbeat (respond with pong)
{"type": "backfill_complete", "count": 15} - Replay complete
{"type": "backfill_expired", "message": "..."} - Event too old

Error Responses

All errors follow this format:

json

{
  "code": "ERROR_CODE",
  "error": "Human-readable message",
  "details": { ... }
}

HTTP Status	Code	Description
400	`INVALID_WORKTREE`	Worktree path is invalid
400	`VALIDATION_ERROR`	Request validation failed
404	`NOT_FOUND`	Workflow not found
409	`WORKFLOW_CONFLICT`	Worktree already has active workflow
422	`INVALID_STATE`	Workflow not in expected state
429	`CONCURRENCY_LIMIT`	Too many concurrent workflows
500	`INTERNAL_ERROR`	Server error

Example Workflows

Basic Issue Implementation

bash

# 1. Start the server
amelia dev

# 2. In another terminal, navigate to your project
cd /path/to/your/project

# 3. Start a workflow for an issue
amelia start ISSUE-123

# 4. Wait for the Architect to generate a plan
#    The workflow will be blocked, waiting for approval

# 5. Review the plan in the dashboard (http://localhost:8420)
#    Or check status:
amelia status

# 6. Approve or reject the plan
amelia approve
# or
amelia reject "Please break task 3 into smaller steps"

# 7. Monitor progress in the dashboard
#    Developer will execute code changes agentically
#    Reviewer will check changes and provide feedback

Review Local Changes

bash

# Make some code changes
git diff  # verify you have changes

# Run the reviewer
amelia review --local

# Review output for approval status and comments

Generate Plan Only (Dry Run)

bash

# Generate plan without executing (no server required)
amelia plan ISSUE-123

# Review the generated markdown file
cat docs/plans/ISSUE-123-plan.md

# If satisfied, start the full workflow
amelia start ISSUE-123

Multiple Worktrees

Use git worktrees to work on multiple issues simultaneously:

bash

# Create worktrees for different issues
git worktree add ../project-issue-123 -b feature/issue-123
git worktree add ../project-issue-456 -b feature/issue-456

# Start workflows in each
cd ../project-issue-123 && amelia start 123
cd ../project-issue-456 && amelia start 456

# Monitor all workflows
amelia status --all

CI/CD Integration

bash

# Health check before deployment
curl -f http://localhost:8420/api/health/ready || exit 1

# Create workflow via API
WORKFLOW_ID=$(curl -s -X POST http://localhost:8420/api/workflows \
  -H "Content-Type: application/json" \
  -d '{"issue_id": "'$ISSUE_ID'", "worktree_path": "'$PWD'"}' \
  | jq -r '.id')

# Poll for completion
while true; do
  STATUS=$(curl -s http://localhost:8420/api/workflows/$WORKFLOW_ID | jq -r '.status')
  case $STATUS in
    completed) echo "Success!"; break ;;
    failed|cancelled) echo "Failed!"; exit 1 ;;
    blocked) echo "Waiting for approval..."; sleep 10 ;;
    *) sleep 5 ;;
  esac
done

Environment Variables

See Configuration Reference — Environment Variable Overrides for the full list of supported variables.

Troubleshooting

See the Troubleshooting guide for solutions to common issues including server startup, workflow conflicts, driver errors, and configuration problems.

Usage Guide ​

Project Setup ​

Configuration ​

CLI Reference ​

Workflow Commands ​

amelia start <ISSUE_ID> ​

amelia status ​

amelia approve ​

amelia reject <REASON> ​

amelia cancel ​

Queue Workflow Commands ​

amelia start <ISSUE_ID> --queue ​

amelia run <WORKFLOW_ID> ​

Queue Workflow Lifecycle ​

Use Cases ​

Server Commands ​

amelia dev ​

amelia server ​

Local Commands (No Server Required) ​

amelia plan <ISSUE_ID> ​

amelia review --local ​

REST API Reference ​

Workflows ​

Create Workflow ​

List Workflows ​

List Active Workflows ​

Get Workflow Details ​

Approve Workflow ​

Reject Workflow ​

Cancel Workflow ​

Start Workflow ​

Start Batch ​

Health Checks ​

Liveness Probe ​

Readiness Probe ​

Detailed Health ​

WebSocket Events ​

Error Responses ​

Example Workflows ​

Basic Issue Implementation ​

Review Local Changes ​

Generate Plan Only (Dry Run) ​

Multiple Worktrees ​

CI/CD Integration ​

Environment Variables ​

Troubleshooting ​

Usage Guide

Project Setup

Configuration

CLI Reference

Workflow Commands

`amelia start <ISSUE_ID>`

`amelia status`

`amelia approve`

`amelia reject <REASON>`

`amelia cancel`

Queue Workflow Commands

`amelia start <ISSUE_ID> --queue`

`amelia run <WORKFLOW_ID>`

Queue Workflow Lifecycle

Use Cases

Server Commands

`amelia dev`

`amelia server`

Local Commands (No Server Required)

`amelia plan <ISSUE_ID>`

`amelia review --local`

REST API Reference

Workflows

Create Workflow

List Workflows

List Active Workflows

Get Workflow Details

Approve Workflow

Reject Workflow

Cancel Workflow

Start Workflow

Start Batch

Health Checks

Liveness Probe

Readiness Probe

Detailed Health

WebSocket Events

Error Responses

Example Workflows

Basic Issue Implementation

Review Local Changes

Generate Plan Only (Dry Run)

Multiple Worktrees

CI/CD Integration

Environment Variables

Troubleshooting