Converge
Converge is an open-source framework for coordinated, multi-repository software development using AI agents. It enables agents working across independent codebases to collaborate, agree, and ship changes through bounded negotiation, shared evidence, and human-in-the-loop governance without endless loops or unsafe automation.
Install / Use
/learn @sumanshusamarora/ConvergeREADME
Converge
Converge is a multi-repository coordination system that accepts tasks, runs bounded orchestration, escalates ambiguous decisions to HITL, and writes auditable run artifacts you can review or action.
Why Converge exists:
- keep cross-repo ownership decisions explicit
- provide a queue/worker model for repeatable orchestration runs
- produce artifacts (summary, matrix, run payload, prompt packs) for humans to execute safely
Local quickstart (SQLite)
pip install -e ".[dev]"
export SQLALCHEMY_DATABASE_URI="sqlite:///./converge.db"
export CONVERGE_QUEUE_BACKEND="db"
export OPIK_TRACK_DISABLE="true"
converge server --port 8080
# in another terminal
converge worker
Docker quickstart (Postgres + API + Worker + UI)
docker compose up --build
- API: http://localhost:8080
- UI: http://localhost:3000
- Postgres: internal-only by default (no host port published)
How Converge Works
Converge runs tasks through a queue-and-worker lifecycle: submit a task, generate plans and artifacts, optionally execute when policy allows, and escalate to HITL when human decisions are needed. This keeps automation bounded while preserving clear audit trails for every run.
See How Converge Runs for a complete explanation.
Codex planning defaults
Converge uses Codex CLI for repository planning when available and falls back automatically if a configured model is not accessible.
- Default model candidates:
gpt-5.3-codex,gpt-5,gpt-5-mini - Override model for one run:
converge coordinate --coding-agent-model gpt-5 ... - Persisted env override:
CONVERGE_CODING_AGENT_MODEL=gpt-5 - Planning control mode:
CONVERGE_CODING_AGENT_PLAN_MODE=auto|force|disable
Check what your environment will do:
converge doctor
Documentation
- Overview
- Getting Started
- CLI Reference
- How Converge Runs
- Configuration
- Tasks and HITL
- Providers and Execution
- Execution & Modes Explained
- UI
- Troubleshooting
HITL and artifacts are first-class: when Converge cannot safely decide, tasks move to HITL_REQUIRED, and every run writes files under .converge/runs/<timestamp>/.
