automission

Give it a goal. An agent team autonomously collaborates to deliver results.

Decentralized (no orchestrator), no human-in-the-loop.

Features

Goal in, results out — describe what you want; Planner generates an acceptance checklist with dependencies, agents do the rest
Multi-agent collaboration — agents work in parallel on independent groups, coordinate via shared git + SQLite
Multi-backend — agents, Planner, and Critic all support Claude Code, Codex CLI, and Gemini CLI — mix and match freely
Docker-first — all execution runs inside containers for isolation and reproducibility
Daemon mode — --detach to start in background, attach to reconnect, stop/resume to control
Safety rails — circuit breakers on cost, time, and iterations; 3-step stall detection auto-recovers stuck agents
Detailed mission log — structured mission.log covers the full pipeline (Plan → Agent → Verification) with per-phase timing; raw agent output saved to agent_outputs/ for deep debugging

Quick Start

1. Install

pip install automission

Requires Docker at runtime — all agent execution and verification runs inside containers.

2. Setup

automission init

Interactive setup walks you through:

Agent backend — choose claude, codex, or gemini, then pick auth method (API key or OAuth)
Planner backend — choose independently, then pick auth method
Verifier backend — defaults to planner settings, or configure separately
Docker image — checks Docker availability and pulls the agent image

This creates ~/.automission/config.toml:

[defaults]
backend = "claude"
model = "claude-sonnet-4-6"

[planner]
backend = "claude"
model = "claude-sonnet-4-6"

[verifier]
backend = "claude"
model = "claude-sonnet-4-6"

[keys]
# Set your API keys here or via environment variables
# anthropic = "sk-ant-..."    # or ANTHROPIC_API_KEY
# codex = "sk-..."            # or CODEX_API_KEY
# gemini = "..."              # or GEMINI_API_KEY

Manual setup (without init)

# Set the API key for your chosen backend
export ANTHROPIC_API_KEY=sk-ant-...   # for Claude (default)
export CODEX_API_KEY=sk-...           # for Codex
export GEMINI_API_KEY=...             # for Gemini

3. Run

automission run --goal "Build a TODO API with auth"

Planner auto-generates an acceptance checklist with dependencies. Review it, confirm, and agents start working.

More options

# Choose model
automission run --goal "..." --model opus

# Multi-agent, choose backend
automission run --goal "..." --agents 3 --backend codex

# Use a different Planner backend
automission run --goal "..." --planner-backend gemini --planner-model gemini-2.5-pro

# Auto-approve Planner output (skip Y/n/edit prompt)
automission run --goal "..." -y

# Skip Planner — provide your own acceptance criteria
automission run --goal "..." --no-planner --acceptance acceptance.md --verify verify.sh

# Goal from file
automission run --goal-file mission-brief.md

# Start in background
automission run --goal "..." --detach

Key flags:

Flag	Default	Description
`--backend`	`claude`	Agent backend: `claude`, `codex`, `gemini`
`--model`	`sonnet`	Model for agent execution (#38)
`--planner-backend`	`claude`	Backend for Planner/Critic
`--planner-model`	`claude-sonnet-4-6`	Model for Planner
`--agents`	`2`	Number of parallel agents
`-y`	—	Auto-approve Planner output
`--no-planner`	—	Skip Planner (requires `--acceptance`)
`--max-cost`	`10.0`	Max total cost in USD
`--timeout`	`3600`	Max wall-clock seconds
`--api-key`	—	API key override (skips env/config lookup)
`--detach`	—	Start mission and return immediately

4. Monitor & Control

automission status              # mission overview
automission logs -f             # stream attempt logs
automission attach <mission-id> # reconnect to a running mission
automission stop                # stop most recent running mission
automission stop <mission-id>   # stop a specific mission
automission resume <mission-id> # resume a stopped or crashed mission
automission list                # list all missions

After a mission completes, mission.log in the workspace contains the full execution narrative — every prompt sent, agent results, verify.sh output, critic analysis, and per-phase timing. Raw agent output (Docker stdout/stderr) is saved in agent_outputs/ for deep debugging.

How It Works

You give a goal — one sentence or a detailed spec
Planner expands it into an acceptance checklist with dependencies
Agents work the frontier — groups whose dependencies are satisfied
Each attempt: agent reads mission context + receives dynamic feedback from last verification
Verifier checks: verify.sh gates pass/fail, LLM critic provides structured feedback
Atomic merge: verified work lands on main safely (staging ref + regression check)
Loop continues until all acceptance groups pass or circuit breakers trigger

Architecture

automission architecture

Text version

┌─────────────────────────────────────────────────────────────────┐
│                        automission CLI                          │
│  automission run --goal "Build a TODO API with auth" --agents 2 │
└──────────────────────────────┬──────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Orchestration Layer                        │
│                                                                 │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌───────────────┐  │
│  │ Planner  │  │ Verifier │  │ Circuit  │  │    Stall      │  │
│  │ (CLI)    │  │ Gate +   │  │ Breakers │  │  Detection    │  │
│  │          │  │ Critic   │  │          │  │  (3-step)     │  │
│  └──────────┘  └──────────┘  └──────────┘  └───────────────┘  │
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │              Acceptance Checklist (Frontier)              │  │
│  │  [✓ auth] [✓ db] [→ api_endpoints] [○ validation]       │  │
│  │                    ↑ current frontier                     │  │
│  └──────────────────────────────────────────────────────────┘  │
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │        Structured Output Backend (Planner/Critic)        │  │
│  │  claude -p --json-schema │ codex exec │ gemini -p        │  │
│  └──────────────────────────────────────────────────────────┘  │
└──────────────────────────────┬──────────────────────────────────┘
                               │
              ┌────────────────┼────────────────┐
              ▼                                  ▼
┌───────────────────────────┐      ┌───────────────────────────┐
│     Docker: Agent 1       │      │     Docker: Agent 2       │
│                           │      │                           │
│  ┌─────────────────────┐  │      │  ┌─────────────────────┐  │
│  │  claude -p --model   │  │      │  │  claude -p --model   │  │
│  │  codex exec          │  │      │  │  codex exec          │  │
│  │  gemini -p           │  │      │  │  gemini -p           │  │
│  └─────────────────────┘  │      │  └─────────────────────┘  │
│                           │      │                           │
│  Git Worktree:            │      │  Git Worktree:            │
│  branch agent-1-work      │      │  branch agent-2-work      │
└─────────────┬─────────────┘      └─────────────┬─────────────┘
              │                                  │
              └──────────┬───────────────────────┘
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│                       Shared State                              │
│                                                                 │
│  ┌──────────┐  ┌──────────────┐  ┌──────────────────────────┐  │
│  │   Git    │  │   SQLite     │  │     Workspace Files      │  │
│  │  (main)  │  │  (ledger)    │  │  MISSION.md              │  │
│  │          │  │  - attempts  │  │  ACCEPTANCE.md            │  │
│  │  atomic  │  │  - claims    │  │  AUTOMISSION.md           │  │
│  │  merge   │  │  - groups    │  │  verify.sh                │  │
│  │  lock    │  │  - metrics   │  │  skills/                  │  │
│  └──────────┘  └──────────────┘  └──────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

Authentication

API key lookup order (first match wins):

--api-key flag (per-command override)
Environment variable (ANTHROPIC_API_KEY, CODEX_API_KEY, GEMINI_API_KEY)
~/.automission/config.toml under [keys]

Backend	Env Var	Config Key
claude	`ANTHROPIC_API_KEY`	`keys.anthropic`
codex	`CODEX_API_KEY`	`keys.codex`
gemini	`GEMINI_API_KEY`	`keys.gemini`

OAuth: Codex and Gemini support OAuth login. Run automission init and choose oauth when prompted — the CLI will trigger the OAuth flow for the selected backend and mount the token directory into Docker containers automatically.

Key Design Decisions

Decision	What	Why
No orchestrator	Agents coordinate via shared state (git + SQLite), not a central LLM	Fault tolerant, no single point of failure
Multi-backend	Claude, Codex, Gemini behind a common protocol	Not locked to one vendor; use the best model for the job
Docker-first	All LLM calls and verify.sh run inside containers	Isolation, reproducibility, secure API key handling
CLI-based Planner/Critic	Planner and Critic call LLM via CLI (`--json-schema`), not SDK	Unified auth (API key or OAuth), no SDK dependency
Gate + Critic	verify.sh decides pass/fail; LLM analyzes why and suggests next steps	Objective gate + actionable feedback
Acceptance checklist	Criteria with dependencies form a DAG; agents work the frontier	Parallel when possible, sequential when needed
Atomic merge	Staging ref + regression verify + fast-forward	Bad merge never poisons main
Fresh session per attempt	Each attempt is a new agent session	Resumable, reproducible, no context pollution
Attempt contract	Auto-derived focus for each attempt	Directed improvement, not blind retry

Documentation

Doc	Content
Vision	Strategy, principles, design decisions
Acceptance Checklist	Dependency model, frontier computation
Agent Loop	Loop pseudocode, contracts, stall detection
Planner	Goal → acceptance checklist generation
Verifier	Gate/Critic architecture, VerifierResult schema
Merge Protocol	Atomic merge, claims, file overlap rule
Agent Backend	Backend protocol, AUTOMISSION.md, skill vendoring
CLI	Commands, configuration, workspace management
Milestone Acceptance	Milestone acceptance criteria and test fixtures

Inspired By

Autoresearch — the loop is the product
Anthropic C Compiler — 16 agents, no orchestrator, shared git
Anthropic Harness Design — Generator/Evaluator separation, evaluation criteria steer quality

Metadata

Release files for automission 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for automission 0.3.0
File	Size	Uploaded	Provenance
automission-0.3.0.tar.gz	215.9 kB	Mar 31, 2026	With provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for automission 0.3.0
File	Interpreter	ABI	Platform	Reset
automission-0.3.0-py3-none-any.whl 82.6 kB Mar 31, 2026 With provenance	Python 3	none	any	Details

Total release size: 298.6 kB

Release files / automission-0.3.0.tar.gz

Download URL	automission-0.3.0.tar.gz
Size	215.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`a549c7edb8fa9c09d3ab745fffb466d2b0cd60adfe0175e7c699c82d35079984`
BLAKE2b-256 checksum How to use checksums	`3499c6b5cb9912e2431ba526cfc2115d18c5ef733f281a2eeacf3271a5f5d044`
Upload date	Mar 31, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.7`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/codance-ai/automission
Publishing commit: github.com/codance-ai/automission/tree/0abee94033c30e4a914331132080c23317be3f2a

Workflow

Publishing configuration: github.com/codance-ai/automission/blob/0abee94033c30e4a914331132080c23317be3f2a/.github/workflows/release.yml
Publishing logs: github.com/codance-ai/automission/actions/runs/23788134743/attempts/1

Artifact

Subject: automission-0.3.0.tar.gz
SHA-256 checksum: a549c7edb8fa9c09d3ab745fffb466d2b0cd60adfe0175e7c699c82d35079984 Verifying attestations

Release files / automission-0.3.0-py3-none-any.whl

Download URL	automission-0.3.0-py3-none-any.whl
Size	82.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`2360a68163aaccc74443d90f15984de6db147eaf82eed781ff037901c0e1f71d`
BLAKE2b-256 checksum How to use checksums	`595319f251ba4c9ac94b0bc565b2523437d19c91a35f2a44dabe555cbed1197e`
Upload date	Mar 31, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.7`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/codance-ai/automission
Publishing commit: github.com/codance-ai/automission/tree/0abee94033c30e4a914331132080c23317be3f2a

Workflow

Publishing configuration: github.com/codance-ai/automission/blob/0abee94033c30e4a914331132080c23317be3f2a/.github/workflows/release.yml
Publishing logs: github.com/codance-ai/automission/actions/runs/23788134743/attempts/1

Artifact

Subject: automission-0.3.0-py3-none-any.whl
SHA-256 checksum: 2360a68163aaccc74443d90f15984de6db147eaf82eed781ff037901c0e1f71d Verifying attestations

Security for automission 0.3.0

Report project as malware

Provenance

Full provenance

All 2 files in this release have been uploaded with provenance metadata.

Attestation for automission-0.3.0.tar.gz

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/codance-ai/automission
Publishing commit: github.com/codance-ai/automission/tree/0abee94033c30e4a914331132080c23317be3f2a

Workflow

Publishing configuration: github.com/codance-ai/automission/blob/0abee94033c30e4a914331132080c23317be3f2a/.github/workflows/release.yml
Publishing logs: github.com/codance-ai/automission/actions/runs/23788134743/attempts/1

Artifact

Subject: automission-0.3.0.tar.gz
SHA-256 checksum: a549c7edb8fa9c09d3ab745fffb466d2b0cd60adfe0175e7c699c82d35079984 Verifying attestations

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.