CoProgrammer

Teamwork for coding agents.

Shared tasks, file boundaries and durable handoffs for Codex, Claude Code and GitHub Copilot working in the same Git repository.

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

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.

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?

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.