CoProgrammer: multi-agent coding coordination

Teamwork for coding agents.

Shared tasks, conflict checks and durable handoffs across Git worktrees and multiple AI coding windows. Project setup supports Codex, Claude Code, Copilot, OpenClaw and WorkBuddy; agent harnesses can use the CLI or MCP.

简体中文 · Try it · Two-window walkthrough · Connect your client · Releases

Is this useful for your workflow? · Native checks and harness automation

The problem

Codex is changing an API. Claude is updating its callers. Both need to know who owns the files, when the upstream task is finished, and what happened before a window restarted. Separate Git branches keep edits apart; the collaboration still needs shared state.

CoProgrammer records who owns a task, which paths it covers, what blocks it, and what the next window needs to know. Your coding tools write the code; CoProgrammer coordinates their work through a local CLI and MCP server.

Try the preview

Requires Python 3.10+ and Git 2.36+. Use an active Python virtual environment. There are no runtime Python dependencies or model keys needed for the demo.

python -m pip install --pre --upgrade coprogrammer
coprogrammer demo

The demo creates two real Git worktrees, runs task claims, dependency and overlap checks, sends a handoff, acknowledges it and completes the tasks. It checks each result and cleans up the temporary project. No coding client or model is launched.

An excerpt from an actual run:

[passed] Create two Git worktrees: Two branches share one repository and one Manager event log.
[passed] Block unfinished dependencies: Claude cannot claim documentation until the API task is finished.
[passed] Reject overlapping work: A different worktree cannot claim src/api.py while Codex holds src/**.

What the demo checks →

Use it in your project

The start and status entry points require 0.3.0a2+. Start in a committed Git checkout on a named branch. Each coding window should use its own Git worktree. Add .coprogrammer/ to your project's .gitignore to keep local runtime state out of commits.

# In the worktree used by Codex
coprogrammer start --client codex --session codex-api --task api-v2
coprogrammer status --session codex-api

# In the separate worktree used by Claude Code
coprogrammer start --client claude --session claude-ui --task api-v2
coprogrammer status --session claude-ui

start registers this window and previews client setup. It does not launch a coding tool or install configuration. Add --dry-run to preview registration; use --resume to explicitly refresh the same registered window after a break. Status reads never refresh sessions. Default session freshness lasts five minutes.

In the Codex worktree, create a scoped task and inspect the next action:

coprogrammer manager task create --session codex-api --id api-v2   --title 'Update the API' --pattern 'src/api/**' --client codex
coprogrammer status --session codex-api
coprogrammer manager task claim --session codex-api --id api-v2

Claims return an ownership token. Use it with the existing guard and finish commands; the two-window walkthrough covers dependency setup, messages, receipts and completion. Status distinguishes repository-wide readiness from work eligible for the selected window.

Connect Codex, Claude Code or Copilot

Preview the project-local Skills, Markdown guidance and MCP configuration:

coprogrammer setup --client codex --include-content

Review the output, then explicitly create missing files:

coprogrammer setup --client codex --apply

Use claude or copilot for those clients. Existing project instructions are preserved; differing Skills or MCP configuration are reported as conflicts. Reload the client and follow its normal project/MCP trust flow. Generated configuration alone does not establish a connection.

After upgrading the package or moving Python/project paths, preview updates to unchanged generated files with coprogrammer setup --client codex --upgrade; add --apply to write them. Customized files continue to report conflicts. Update an installed project.

MCP exposes the same local workflows. workspace_status provides the combined status view; task_dispatch previews eligible tasks. The packaged plugin contains six Skills, and the CLI serves twelve read-only Markdown resources. Client setup · Plugin installation

What else can it do?

Less manual coordination (0.3.0a3+)

Choose a Skill, MCP or full installation using setup --edition skills, --edition mcp or --edition full. They share the same six Skills and scheduler.

coprogrammer worker step --session codex-api --apply combines activity, inbox/decision checks, task selection and scope guarding. It renews valid owned work or atomically claims eligible work. Pending messages stop work until receipt is explicitly handled. Completion can send durable handoffs to selected windows using worker finish --notify <window-id>; identical retries reuse messages.

GLM/DeepSeek-backed Claude Code windows register with --client claude and --provider glm or --provider deepseek. Task filters match the host or declared provider; labels do not configure credentials or establish a model connection. MCP equivalents are worker_step and worker_finish, called by the participating agent. Installation editions and automatic workflow →

Bring your own agent harness (0.3.0a4+)

OpenClaw can load workspace Skills; WorkBuddy can import a Skill/MCP kit. Generic agent harnesses can import MCP or call the CLI at work boundaries. All use the existing task queue, scope guards and durable local inbox.

coprogrammer setup --client openclaw --edition full --include-content
coprogrammer setup --client workbuddy --edition full --include-content
coprogrammer setup --client harness --edition mcp --include-content

Review your chosen plan, then add --apply. Import profiles explain the required client activation; generated files do not establish a connection. Grok is also available for explicit advisory reviews via review --provider grok --model MODEL. Runtime adapters, activation steps and Grok guide →

How it fits

Use CoProgrammer when you already run coding agents and need shared ownership, communication and review evidence across their worktrees. It complements your existing coding tools and GitHub review process.

gstack provides opinionated development and review workflows; Beads provides persistent agent work tracking; Gas Town manages multi-agent workspaces and orchestration. CoProgrammer focuses on local task ownership, path coordination, durable handoffs and inspectable integration artifacts through a small Python CLI/MCP package. Comparison and design choices →

Local worktrees share a Manager. Independent clones have separate Managers: portable handoffs compare context and do not transfer a global lease. Path leases are cooperative checks, not filesystem permissions. Check records are unauthenticated local evidence. PR approval and merging follow your project's normal rules. The demo does not establish native client or live provider connectivity.

Contribute or get help

Report a reproducible problem · Propose an integration · Contributor guide

Good first contributions include a small client setup example, a clearer error message or a regression for a real worktree conflict. Include the command, version, expected result and actual result; remove private code and credentials. If CoProgrammer helps your team, a star helps others discover it.

For source development:

git clone https://github.com/QIU-Guanzong/CoProgrammer.git
cd CoProgrammer
python -m pip install -e .
python -m unittest discover -s tests

MIT license. Preview software; feedback and concrete bug reports are welcome.