llm-collab
by ain-soph
README.md
# llm-collab
Local coordination for Claude Code, Google Antigravity and OpenAI Codex. All three MCP clients can share a task ID, recover a handoff, and inspect a decision. The coordinator can run a bounded discussion, assign implementation to separate Git checkouts, and preserve progress when a provider reports a quota failure.
This project connects to an independently installed [local-agent-bridge](https://github.com/normcrandall/local-agent-bridge). Compatibility was verified with Bridge commit `c0f9486ecce2570bb14a806a238f12201621df14`. Install and configure Bridge and the provider CLIs using their respective instructions.
## Configure
Use Node.js 22 or later and Git on macOS or Linux. Clone this repository, then install its locked dependencies and copy the configuration template.
```sh
npm ci --ignore-scripts
cp config.example.json config.json
node bin/llm-collab.mjs --config config.json --check
```
Edit `config.json` before running the check. Relative paths are resolved from the directory containing that file.
| Setting | Purpose |
| --- | --- |
| `bridgeRoot` | External Bridge installation with its own dependencies installed |
| `workspace` | Standalone Git checkout used for local collaboration. It needs an `origin`, which may be a local bare repository |
| `stateDirectory` | Writable local task, quota and handoff state. Use a short absolute path if the platform limits Unix socket path length |
| `providers` | CLI names on PATH or explicit paths for Claude Code, Antigravity and Codex |
| `productionRoot` | Optional deployment root for reading `logs/health/STATUS` |
Register the same stdio command in all three clients. Use the absolute Node.js, launcher and config paths in client configurations.
```sh
codex mcp add llm-collab -- /path/to/node /path/to/llm-collab/bin/llm-collab.mjs --config /path/to/config.json
claude mcp add --scope user --transport stdio llm-collab -- /path/to/node /path/to/llm-collab/bin/llm-collab.mjs --config /path/to/config.json
agy mcp add llm-collab -- /path/to/node /path/to/llm-collab/bin/llm-collab.mjs --config /path/to/config.json
```
## Work together
- Use `workspace_status` for the active checkout and `team_status` for quota observations and coordinator priority. Among providers with confirmed availability, the order is Claude Code, Antigravity, then Codex.
- Use `start_collaboration` in review mode for discussion. For an implementation phase, use work mode with a writer and an optional `taskBranch` for a private checkout. Give independent tasks different branch names.
- Use `list_collaborations` and `get_collaboration` from any client to find a task and its latest handoff. `continue_collaboration` uses that same task ID.
- A reversible technical decision can be put to a vote. Each participant emits a line such as `VOTE: {"choice":"A","reason":"The benchmark is reproducible."}`. `tally_team_vote` records a decision when one option gets at least two votes and a majority. The receipt includes dissent and a rollback route.
- When a known usage window reaches 3% remaining, the launcher blocks additional delegated turns for that provider. At a safe stopping point, use `save_team_handoff` to save the summary, next step, and individual subagent notes. Existing interactive sessions follow their own workspace’s checkpoint instructions. A Bridge installation with compatible quota collectors can report Codex and Claude percentages. Antigravity reaches the fallback path on confirmed provider failure.
The repository ships the coordinator and config template. The external Bridge checkout, credentials, local state, transcripts, and development workspaces are installed or created on each host. Keep local configuration and runtime data outside commits. Publishing and production operations run through the host’s established authorization and deployment process.
Run `npm test` for local vote and handoff checks.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues