协同AI工作流

Install

curl -fsSL https://raw.githubusercontent.com/AndrewDryga/coop/main/install.sh | sh

Downloads the prebuilt coop binary for your OS/arch into ~/.local/bin — no Go, no clone. If a container runtime is present, the installer also builds the sandbox image and runs coop doctor; otherwise do that once yourself:

coop build && coop doctor

Requirements: a container runtime — Apple container (macOS 26+), Docker, or Podman, auto-detected. coop itself is a single static binary with no other dependencies.

Staying current: coop update self-updates the binary and rebuilds the box image fresh, pulling the latest agent CLIs and ACP adapters (they ship features often) plus a newer base. (Re-running the install one-liner still works.)

<details><summary><b>Other ways to install</b></summary>

go install github.com/AndrewDryga/coop@latest                              # with Go
git clone https://github.com/AndrewDryga/coop && cd coop && make install   # from source

<details><summary><b>Verifying a download</b></summary>

install.sh verifies automatically: when cosign is on your PATH it checks checksums.txt's keyless Sigstore signature (so the checksum file itself is trusted, not just internally consistent) and aborts on failure; otherwise it compares the archive's SHA-256 and prints that the signature was not verified. To verify by hand, set VER and ASSET for your platform — e.g. VER=v0.1.0 ASSET=coop_0.1.0_darwin_arm64.tar.gz:

```bash base="https://github.com/AndrewDryga/coop/releases/download/$VER" curl -fsSLO "$base/$ASSET" curl -fsSLO "$base/checksums.txt" curl -fsSLO "$base/checksums.txt.bundle"

^ installs the binary, and (if a runtime is present) builds the box + runs coop doctor

cd ~/code/your-repo # 1. any git repo coop doctor # 2. prove isolation holds (builds the box first if needed) coop login claude # 3. authenticate once (token persists; paste-code, no browser needed) coop claude # 4. a sandboxed agent, brakes off, your secrets shadowed coop fork feature claude # 5. or hand off a branch: agent works in a throwaway clone… coop fork review feature # …you review the diff… coop fork merge feature # …and land it (rebased onto your branch, signed if you sign) ```

If coop doctor says the image isn't built, run coop build once. Stuck on any step? See Troubleshooting.

`Dockerfile.agent` — a per-project image

coop init --stack asdf   # writes an asdf Dockerfile.agent (from .tool-versions)
coop build               # builds it, tagged coop-<repo-name> — its own image

A repo with its own Dockerfile.agent gets its own image tag, so projects never collide, and every coop, coop loop, coop fork, coop acp in that repo uses it. The scaffolded one is the asdf image — it bakes in the exact .tool-versions toolchain (versions live there, not in the Dockerfile). For anything more exotic, hand-write a Dockerfile.agent (see the box contract below). When the agent needs a new system package, add it to the RUN line and coop build again — the dependency graduates into the image instead of being installed each run. If you change Dockerfile.agent or .tool-versions but forget to rebuild, coop notices on the next run and reminds you to coop build (it records the image's inputs at build time).

<details><summary><b>The box contract (build any base)</b></summary>

An image is a valid agent box when:

1. It runs as a non-root user — Claude Code refuses --dangerously-skip-permissions as root.
2. That user's home is /home/node — the agents/ auth mounts land at $HOME/.claude, $HOME/.codex, $HOME/.gemini. (Different base? Set COOP_HOME_IN_BOX=/home/<user>.)
3. claude, codex, gemini are on PATH (so it needs Node) — plus the ACP adapters if you want coop acp.
4. git config --system --add safe.directory '*' — git works on the host-owned bind mount (which lives at the repo's real path, not a fixed /workspace).

coop sets the working directory itself, so no WORKDIR is required. A skeleton:

FROM <your-language-base>
RUN <install your toolchain> \
 && npm install -g @anthropic-ai/claude-code@latest @openai/codex@latest @google/gemini-cli@latest \
      @agentclientprotocol/claude-agent-acp@latest @agentclientprotocol/codex-acp@latest \
 && git config --system --add safe.directory '*' \
 && id -u node >/dev/null 2>&1 || useradd -m -u 1000 -s /bin/bash node
USER node

(If the base lacks Node, install it first — the asdf template uses NodeSource.) </details>

<details><summary><b>Reusing an existing devcontainer</b></summary>

If a repo already has a .devcontainer/, reuse its image as your base and add the agent layer on top:

```dockerfile FROM your-devcontainer-image # the team's source of truth for the env RUN npm install -g @anthropic-ai/claude-code@latest @openai/codex@latest @google/gemini-cli@latest \ @agentclientprotocol/claude-agent-acp@latest @agentclientprotocol/codex-acp@latest \ && git config --system --add safe.directory '*' USER <the devcontainer's non-root user>

Quickstart

cd ~/code/some-repo

coop claude           # sandboxed Claude — no permission prompts, secrets shadowed
coop codex            # same box, Codex instead
coop gemini           # ...or Gemini
coop fusion           # a council: one model leads, the other two advise, then it synthesizes
coop shell            # a shell in the box, to look around
coop run -- npm test  # run any command in the box

Point it at a repo and go. Each agent launches with its own "don't stop to ask" flags (--dangerously-skip-permissions, --dangerously-bypass-approvals-and-sandbox, --yolo), all inside the same sandbox. The worst an off-the-rails agent can do is trash one repo you can restore from git.

Anything after the agent name is passed through to it, on top of those flags — so coop claude --continue resumes Claude's last session, still sandboxed. (Codex is the exception: its -p is --profile, not a prompt, so run a one-shot prompt with coop codex exec "…" and use -p only to pick a profile.)

Agents & config

One box, three agents. Each reads its config and credentials from ~/.config/coop/agents/<name>/, mounted into the box at ~/.claude, ~/.codex, and ~/.gemini. That directory lives outside any repo, so credentials never land in git — edit those files on the host and they take effect in the box. Only the active profile is mounted, so a running agent sees just the account it's using, not the whole vault.

Each run mounts only the launched agent's credentials: coop claude mounts ~/.claude (and that agent's API key from the env file), never the Codex or Gemini ones. The exceptions are the modes where the lead is explicitly told to call its peers — coop fusion and coop <agent> --consult (and forks) — which also mount the authenticated peers so they can be consulted read-only. Raw runs (coop run, coop shell) and maintenance runs (the merge gate, coop doctor) mount no agent credentials at all. coop login <agent> mounts only the agent being signed in.

Blast radius. That profile dir is mounted read-write — the agent must write its session history, and OAuth refresh rewrites the token in place. So a prompt-injected agent can (a) read its own credentials and try to exfiltrate them — set COOP_EGRESS=none to cut the box off the network — and (b) write config its CLI auto-loads next launch (e.g. a settings.json hook), which then runs in future boxes for that profile. (b) stays inside the container — not a host escape — but it's a durable foothold. A fuller fix (copy credentials into an ephemeral in-box location, persist nothing host-side) is planned; for now, COOP_EGRESS=none covers the exfil half.

`.tool-versions` — zero config

If your repo pins versions in a .tool-versions (asdf), the base box provisions that toolchain at runtime — resolved from the working dir up the tree, or ~/.tool-versions — and caches it in a shared volume. So a repo with just a .tool-versions (no Dockerfile.agent, no scaffolding) gets its toolchain with zero setup:

cd ~/code/phoenix-app   # has a .tool-versions
coop claude             # provisions elixir/erlang/node/… from it, then runs the agent

The first install of a new toolchain can be slow (e.g. Erlang compiles), then it's reused across runs and repos. Set COOP_NO_ASDF=1 (in agents/env) to skip provisioning from .tool-versions; coop still repairs a stale persisted Node shim when needed so the agent CLIs keep running. For a baked, fully-reproducible image instead, coop init --stack asdf scaffolds an asdf Dockerfile.agent that installs the same .tool-versions at build time.

Configuration

Set via environment variables, or ~/.config/coop/coop.conf (KEY=VALUE lines, same names — the environment wins over the file). Toggles default on; set 0/false to turn them off.

Box & runtime

The resource/privilege caps (COOP_PIDS / COOP_MEMORY / COOP_CPUS / COOP_NO_NEW_PRIVILEGES) apply on docker and podman; Apple's container CLI differs, so they're skipped there for now. On docker/podman the box also runs with all Linux capabilities dropped (--cap-drop ALL) — the agent workloads need none, and it keeps root-in-container (a repo Dockerfile.agent that does USER root) from holding CAP_DAC_OVERRIDE / CAP_NET_RAW / CAP_MKNOD and friends.

Agents & config

Forks & loop

Command-valued settings — COOP_GATE, COOP_LOOP_CMD, COOP_RUN_ARGS, and the COOP_<AGENT>_CMD overrides — are split into argv with shell quoting (single/double quotes group, \ escapes), but no shell runs them (no globbing or $VAR). So quotes group as you'd expect — COOP_GATE='bash -lc "make check && make lint"' is three args, not five — but a bare &&/|/$VAR is a literal argument: wrap those in bash -lc "…". (COOP_REVIEW_CMD is the exception — it is run via sh -c.)

Command reference

Every command runs against the repo in your current directory. -h/--help works on any of them.

Run an agent

Forks — hand off work like a PR (details)

Run unattended (details)

Set up & maintain

1. checksums.txt is signed by the release workflow (keyless Sigstore):

cosign verify-blob checksums.txt \ --bundle checksums.txt.bundle \ --certificate-identity-regexp '^https://github.com/AndrewDryga/coop/' \ --certificate-oidc-issuer https://token.actions.githubusercontent.com

VS Code

git config --global diff.tool vscode git config --global difftool.vscode.cmd 'code --wait --diff "$LOCAL" "$REMOTE"'

Troubleshooting