{"id":47704568,"url":"https://github.com/codance-ai/automission","last_synced_at":"2026-04-02T17:51:07.799Z","repository":{"id":347649237,"uuid":"1194768112","full_name":"codance-ai/automission","owner":"codance-ai","description":"Give it a goal. An agent team autonomously collaborates to deliver results.","archived":false,"fork":false,"pushed_at":"2026-03-28T20:55:48.000Z","size":215,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-28T21:25:25.388Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codance-ai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-28T19:37:01.000Z","updated_at":"2026-03-28T20:55:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/codance-ai/automission","commit_stats":null,"previous_names":["codance-ai/automission"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/codance-ai/automission","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codance-ai%2Fautomission","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codance-ai%2Fautomission/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codance-ai%2Fautomission/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codance-ai%2Fautomission/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codance-ai","download_url":"https://codeload.github.com/codance-ai/automission/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codance-ai%2Fautomission/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31312744,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-02T17:51:02.957Z","updated_at":"2026-04-02T17:51:07.787Z","avatar_url":"https://github.com/codance-ai.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# automission\n\n[![PyPI](https://img.shields.io/pypi/v/automission)](https://pypi.org/project/automission/)\n[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n[![CI](https://github.com/codance-ai/automission/actions/workflows/ci.yml/badge.svg)](https://github.com/codance-ai/automission/actions/workflows/ci.yml)\n\nGive it a goal. An agent team autonomously collaborates to deliver results.\n\nDecentralized (no orchestrator), no human-in-the-loop.\n\n## Features\n\n- **Goal in, results out** — describe what you want; Planner generates an acceptance checklist with dependencies, agents do the rest\n- **Multi-agent collaboration** — agents work in parallel on independent groups, coordinate via shared git + SQLite\n- **Multi-backend** — agents, Planner, and Critic all support Claude Code, Codex CLI, and Gemini CLI — mix and match freely\n- **Docker-first** — all execution runs inside containers for isolation and reproducibility\n- **Daemon mode** — `--detach` to start in background, `attach` to reconnect, `stop`/`resume` to control\n- **Safety rails** — circuit breakers on cost, time, and iterations; 3-step stall detection auto-recovers stuck agents\n- **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\n\n## Quick Start\n\n### 1. Install\n\n```bash\npip install automission\n```\n\nRequires [Docker](https://docs.docker.com/get-docker/) at runtime — all agent execution and verification runs inside containers.\n\n### 2. Setup\n\n```bash\nautomission init\n```\n\nInteractive setup walks you through:\n\n1. **Agent backend** — choose `claude`, `codex`, or `gemini`, then pick auth method (API key or OAuth)\n2. **Planner backend** — choose independently, then pick auth method\n3. **Verifier backend** — defaults to planner settings, or configure separately\n4. **Docker image** — checks Docker availability and pulls the agent image\n\nThis creates `~/.automission/config.toml`:\n\n```toml\n[defaults]\nbackend = \"claude\"\nmodel = \"claude-sonnet-4-6\"\n\n[planner]\nbackend = \"claude\"\nmodel = \"claude-sonnet-4-6\"\n\n[verifier]\nbackend = \"claude\"\nmodel = \"claude-sonnet-4-6\"\n\n[keys]\n# Set your API keys here or via environment variables\n# anthropic = \"sk-ant-...\"    # or ANTHROPIC_API_KEY\n# codex = \"sk-...\"            # or CODEX_API_KEY\n# gemini = \"...\"              # or GEMINI_API_KEY\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eManual setup (without init)\u003c/summary\u003e\n\n```bash\n# Set the API key for your chosen backend\nexport ANTHROPIC_API_KEY=sk-ant-...   # for Claude (default)\nexport CODEX_API_KEY=sk-...           # for Codex\nexport GEMINI_API_KEY=...             # for Gemini\n```\n\n\u003c/details\u003e\n\n### 3. Run\n\n```bash\nautomission run --goal \"Build a TODO API with auth\"\n```\n\nPlanner auto-generates an acceptance checklist with dependencies. Review it, confirm, and agents start working.\n\n\u003cdetails\u003e\n\u003csummary\u003eMore options\u003c/summary\u003e\n\n```bash\n# Choose model\nautomission run --goal \"...\" --model opus\n\n# Multi-agent, choose backend\nautomission run --goal \"...\" --agents 3 --backend codex\n\n# Use a different Planner backend\nautomission run --goal \"...\" --planner-backend gemini --planner-model gemini-2.5-pro\n\n# Auto-approve Planner output (skip Y/n/edit prompt)\nautomission run --goal \"...\" -y\n\n# Skip Planner — provide your own acceptance criteria\nautomission run --goal \"...\" --no-planner --acceptance acceptance.md --verify verify.sh\n\n# Goal from file\nautomission run --goal-file mission-brief.md\n\n# Start in background\nautomission run --goal \"...\" --detach\n```\n\n**Key flags:**\n\n| Flag | Default | Description |\n|------|---------|-------------|\n| `--backend` | `claude` | Agent backend: `claude`, `codex`, `gemini` |\n| `--model` | `sonnet` | Model for agent execution ([#38](https://github.com/codance-ai/automission/issues/38)) |\n| `--planner-backend` | `claude` | Backend for Planner/Critic |\n| `--planner-model` | `claude-sonnet-4-6` | Model for Planner |\n| `--agents` | `2` | Number of parallel agents |\n| `-y` | — | Auto-approve Planner output |\n| `--no-planner` | — | Skip Planner (requires `--acceptance`) |\n| `--max-cost` | `10.0` | Max total cost in USD |\n| `--timeout` | `3600` | Max wall-clock seconds |\n| `--api-key` | — | API key override (skips env/config lookup) |\n| `--detach` | — | Start mission and return immediately |\n\n\u003c/details\u003e\n\n### 4. Monitor \u0026 Control\n\n```bash\nautomission status              # mission overview\nautomission logs -f             # stream attempt logs\nautomission attach \u003cmission-id\u003e # reconnect to a running mission\nautomission stop                # stop most recent running mission\nautomission stop \u003cmission-id\u003e   # stop a specific mission\nautomission resume \u003cmission-id\u003e # resume a stopped or crashed mission\nautomission list                # list all missions\n```\n\nAfter 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.\n\n## How It Works\n\n1. **You give a goal** — one sentence or a detailed spec\n2. **Planner** expands it into an acceptance checklist with dependencies\n3. **Agents** work the frontier — groups whose dependencies are satisfied\n4. **Each attempt**: agent reads mission context + receives dynamic feedback from last verification\n5. **Verifier** checks: `verify.sh` gates pass/fail, LLM critic provides structured feedback\n6. **Atomic merge**: verified work lands on main safely (staging ref + regression check)\n7. **Loop continues** until all acceptance groups pass or circuit breakers trigger\n\n## Architecture\n\n![automission architecture](docs/assets/architecture.png)\n\n\u003cdetails\u003e\n\u003csummary\u003eText version\u003c/summary\u003e\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│                        automission CLI                          │\n│  automission run --goal \"Build a TODO API with auth\" --agents 2 │\n└──────────────────────────────┬──────────────────────────────────┘\n                               │\n                               ▼\n┌─────────────────────────────────────────────────────────────────┐\n│                      Orchestration Layer                        │\n│                                                                 │\n│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌───────────────┐  │\n│  │ Planner  │  │ Verifier │  │ Circuit  │  │    Stall      │  │\n│  │ (CLI)    │  │ Gate +   │  │ Breakers │  │  Detection    │  │\n│  │          │  │ Critic   │  │          │  │  (3-step)     │  │\n│  └──────────┘  └──────────┘  └──────────┘  └───────────────┘  │\n│                                                                 │\n│  ┌──────────────────────────────────────────────────────────┐  │\n│  │              Acceptance Checklist (Frontier)              │  │\n│  │  [✓ auth] [✓ db] [→ api_endpoints] [○ validation]       │  │\n│  │                    ↑ current frontier                     │  │\n│  └──────────────────────────────────────────────────────────┘  │\n│                                                                 │\n│  ┌──────────────────────────────────────────────────────────┐  │\n│  │        Structured Output Backend (Planner/Critic)        │  │\n│  │  claude -p --json-schema │ codex exec │ gemini -p        │  │\n│  └──────────────────────────────────────────────────────────┘  │\n└──────────────────────────────┬──────────────────────────────────┘\n                               │\n              ┌────────────────┼────────────────┐\n              ▼                                  ▼\n┌───────────────────────────┐      ┌───────────────────────────┐\n│     Docker: Agent 1       │      │     Docker: Agent 2       │\n│                           │      │                           │\n│  ┌─────────────────────┐  │      │  ┌─────────────────────┐  │\n│  │  claude -p --model   │  │      │  │  claude -p --model   │  │\n│  │  codex exec          │  │      │  │  codex exec          │  │\n│  │  gemini -p           │  │      │  │  gemini -p           │  │\n│  └─────────────────────┘  │      │  └─────────────────────┘  │\n│                           │      │                           │\n│  Git Worktree:            │      │  Git Worktree:            │\n│  branch agent-1-work      │      │  branch agent-2-work      │\n└─────────────┬─────────────┘      └─────────────┬─────────────┘\n              │                                  │\n              └──────────┬───────────────────────┘\n                         ▼\n┌─────────────────────────────────────────────────────────────────┐\n│                       Shared State                              │\n│                                                                 │\n│  ┌──────────┐  ┌──────────────┐  ┌──────────────────────────┐  │\n│  │   Git    │  │   SQLite     │  │     Workspace Files      │  │\n│  │  (main)  │  │  (ledger)    │  │  MISSION.md              │  │\n│  │          │  │  - attempts  │  │  ACCEPTANCE.md            │  │\n│  │  atomic  │  │  - claims    │  │  AUTOMISSION.md           │  │\n│  │  merge   │  │  - groups    │  │  verify.sh                │  │\n│  │  lock    │  │  - metrics   │  │  skills/                  │  │\n│  └──────────┘  └──────────────┘  └──────────────────────────┘  │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n\u003c/details\u003e\n\n## Authentication\n\nAPI key lookup order (first match wins):\n\n1. `--api-key` flag (per-command override)\n2. Environment variable (`ANTHROPIC_API_KEY`, `CODEX_API_KEY`, `GEMINI_API_KEY`)\n3. `~/.automission/config.toml` under `[keys]`\n\n| Backend | Env Var | Config Key |\n|---------|---------|------------|\n| claude | `ANTHROPIC_API_KEY` | `keys.anthropic` |\n| codex | `CODEX_API_KEY` | `keys.codex` |\n| gemini | `GEMINI_API_KEY` | `keys.gemini` |\n\n**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.\n\n## Key Design Decisions\n\n| Decision | What | Why |\n|----------|------|-----|\n| No orchestrator | Agents coordinate via shared state (git + SQLite), not a central LLM | Fault tolerant, no single point of failure |\n| Multi-backend | Claude, Codex, Gemini behind a common protocol | Not locked to one vendor; use the best model for the job |\n| Docker-first | All LLM calls and verify.sh run inside containers | Isolation, reproducibility, secure API key handling |\n| CLI-based Planner/Critic | Planner and Critic call LLM via CLI (`--json-schema`), not SDK | Unified auth (API key or OAuth), no SDK dependency |\n| Gate + Critic | verify.sh decides pass/fail; LLM analyzes why and suggests next steps | Objective gate + actionable feedback |\n| Acceptance checklist | Criteria with dependencies form a DAG; agents work the frontier | Parallel when possible, sequential when needed |\n| Atomic merge | Staging ref + regression verify + fast-forward | Bad merge never poisons main |\n| Fresh session per attempt | Each attempt is a new agent session | Resumable, reproducible, no context pollution |\n| Attempt contract | Auto-derived focus for each attempt | Directed improvement, not blind retry |\n\n## Documentation\n\n| Doc | Content |\n|-----|---------|\n| [Vision](docs/vision.md) | Strategy, principles, design decisions |\n| [Acceptance Checklist](docs/specs/acceptance-graph.md) | Dependency model, frontier computation |\n| [Agent Loop](docs/specs/agent-loop.md) | Loop pseudocode, contracts, stall detection |\n| [Planner](docs/specs/planner.md) | Goal → acceptance checklist generation |\n| [Verifier](docs/specs/verifier.md) | Gate/Critic architecture, VerifierResult schema |\n| [Merge Protocol](docs/specs/merge-protocol.md) | Atomic merge, claims, file overlap rule |\n| [Agent Backend](docs/specs/agent-backend.md) | Backend protocol, AUTOMISSION.md, skill vendoring |\n| [CLI](docs/specs/cli.md) | Commands, configuration, workspace management |\n| [Milestone Acceptance](docs/specs/milestone-acceptance.md) | Milestone acceptance criteria and test fixtures |\n\n## Inspired By\n\n- [Autoresearch](https://github.com/karpathy/autoresearch) — the loop is the product\n- [Anthropic C Compiler](https://www.anthropic.com/engineering/building-c-compiler) — 16 agents, no orchestrator, shared git\n- [Anthropic Harness Design](https://www.anthropic.com/engineering/harness-design-long-running-apps) — Generator/Evaluator separation, evaluation criteria steer quality\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodance-ai%2Fautomission","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodance-ai%2Fautomission","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodance-ai%2Fautomission/lists"}