Skip to content
Back to search

capcomd

MarketplaceWorks with Claude CodeGitHub

capcomd: durable orchestration for swarms of coding agents, as a plugin for your agent

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/marvinamador7--capcomd/badge.svg)](/listings/marvinamador7--capcomd)

HTML

<a href="/listings/marvinamador7--capcomd"><img src="/api/listings/marvinamador7--capcomd/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

**Requirements:** macOS or Linux, a sandbox provider account ([boxd](https://boxd.sh) today), a GitHub repository, and a Claude and/or ChatGPT plan (or Anthropic/OpenAI API keys).

**Install** (one self-contained executable, no runtime to install first):

curl -fsSL https://raw.githubusercontent.com/MarvinAmador7/capcomd/main/install.sh | sh
# or: brew install MarvinAmador7/tap/capcomd
# or, with Bun: bun add -g capcomd

`capcomd upgrade` updates it later.

**The Mac app** (optional; macOS 14 or later): a window with each run's agents side by side and a menu bar item with approvals, in one app. It uses the CLI you installed above, however you installed it (install.sh, Homebrew, Bun or npm), and doesn't install a second one:

brew install --cask MarvinAmador7/tap/capcomd-app

If Homebrew refuses to load something "from untrusted tap" (Homebrew 7 and later), trust the tap once with `brew trust MarvinAmador7/tap` and run the install again.

Open capcomd from Applications. It finds your CLI and connects by itself; if capcomd already runs as a service (`capcomd service install`), it uses that one and the CLI that runs it, and asks nothing. Otherwise it starts capcomd for you (as a login service). No terminal is needed after this. Without a CLI yet, the app shows the command to install it. The app isn't notarized by Apple yet, so macOS blocks its first open: click **Done**, then in **System Settings › Privacy & Security** click **Open Anyway** next to "capcomd" and confirm. After that it opens like any app. Without Homebrew, download `capcomd-app-X.Y.Z.zip` from the [release](https://github.com/MarvinAmador7/capcomd/releases) and move `capcomd.app` to Applications.

**1. Add capcomd to your agent.** The capcomd plugin gives your agent the MCP tools and two skills (orchestration, and setup):

# Claude Code
/plugin install capcomd --marketplace MarvinAmador7/capcomd
# Codex
codex plugin marketplace add MarvinAmador7/capcomd     # then install capcomd from /plugins
# Hermes (Nous Research): after installing the CLI, in your repository
capcomd setup agent      # adds capcomd's MCP server and skills to ~/.hermes (docs/integration-agents.md#hermes)

**2. Ask your agent to set it up**, in the repository the agents should work on:

> Set up capcomd for this repository.

It installs the CLI if it's missing (the installer above), connects your sandbox provider (with the boxd CLI logged in, it creates a key just for capcomd and keeps it in your OS keychain), builds the agent VM snapshot, detects your repository, target branch and test command, and starts the engine. A few steps are yours: logging in to boxd (`boxd auth login`) and your agents (`capcomd auth login claude`) open a browser, and you confirm the gates (the checks, the reviewer, the target branch). Prefer a terminal? `capcomd setup` after installing does the same, including the plugin, and can be re-run safely; `capcomd setup check` shows what's configured.

**3. Ask for the outcome:**

> Use capcomd to fix the failing tests in `src/`: one worker per file, each verified and reviewed, then merged.

> Use capcomd to add rate limiting to the API: plan it, put the shared types first, then the middleware and its > tests in parallel; land on a `staging` branch.

Your agent reports back as agents finish and merges land. Merges into protected branches wait for you: `capcomd approve <runId> <mrgId>`. Watch a run with `capcomd tree <runId>`, or in the terminal debugger: `capcomd tui [runId]` (its agents live, a waterfall of what each did, a timeline, cost rollups and events; with no runId, the latest run).

Each [release](https://github.com/MarvinAmador7/capcomd/releases) has the binaries for macOS and Linux (arm64 and x64), the npm package and the Mac app (universal, signed ad hoc until it's notarized), each with its SHA-256 (the installer and `capcomd upgrade` check it); the npm package is

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 13 lines
  1. {
  2. "name": "capcomd",
  3. "description": "capcomd: durable orchestration for swarms of coding agents, as a plugin for your agent",
  4. "owner": { "name": "Marvin Amador Campos", "url": "https://github.com/MarvinAmador7" },
  5. "plugins": [
  6. {
  7. "name": "capcomd",
  8. "source": "./plugins/capcomd",
  9. "description": "Spawn Claude Code and Codex agents in isolated VMs from your agent; verify, review and merge only tested commits.",
  10. "category": "development"
  11. }
  12. ]
  13. }
README.md · README · 292 lines · 1 finding marked
  1. # capcomd
  2. [![CI](https://github.com/MarvinAmador7/capcomd/actions/workflows/ci.yml/badge.svg)](https://github.com/MarvinAmador7/capcomd/actions/workflows/ci.yml)
  3. [![npm](https://img.shields.io/npm/v/capcomd)](https://www.npmjs.com/package/capcomd)
  4. [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
  5. **Durable orchestration for swarms of coding agents, driven by your agent.**
  6. Give your coding agent capcomd (a skill and a CLI, or an MCP server) and ask for the outcome. Your agent becomes
  7. the orchestrator: it splits the work, spawns a team of Claude Code and Codex agents that run in parallel, each in
  8. its own isolated VM on its own branch, and lands only the work that passed checks you defined and a review by
  9. another agent, as the exact commit that was tested. Runs are durable: agents keep working when your agent's session
  10. ends, a crash or a restart resumes where it stopped, and every merge happens exactly once.
  11. > **Early release (0.x).** The primitives, sub-agents, verification, review and durability are built and verified
  12. > live; expect changes between minor versions. Your agent drives capcomd through the plugin (MCP tools and
  13. > skills) or the CLI. See [STATUS.md](STATUS.md) and
  14. > [ROADMAP.md](ROADMAP.md).
  15. ## How you use it
  16. You don't run orchestration commands by hand. You tell your agent what you want:
  17. > Use capcomd to fix the failing tests in `src/`: one worker per file, each verified and reviewed, then merged.
  18. Your agent does the rest with capcomd's primitives (`spawn`, `await`, `verify`, `merge`, a task board and a shared
  19. blackboard), and you watch, approve merges into protected branches, or step in:
  20. ```
  21. you ──▶ your agent (Claude Code, Codex, …) + capcomd skill/CLI/MCP
  22. │ plans, then spawns a swarm in parallel, each in its own VM and branch
  23. ├──▶ worker: parser ─┐
  24. ├──▶ worker: tests ├──▶ verify ──▶ your checks (in a fresh VM)
  25. └──▶ worker: docs ─┘ └──▶ reviewer agent (read-only)
  26. │ both pass
  27. ▼
  28. merge the exact tested commit ──▶ your branch
  29. (protected branch: waits for your approval)
  30. ```
  31. Workers can be orchestrators too: an agent allowed to delegate gets the same primitives inside its VM and runs
  32. its own sub-team, within limits you set.
  33. ## Why
  34. Coding agents are fast, but on their own they are hard to trust and hard to scale:
  35. - **They report success, not proof.** "All tests pass" is a claim until something else runs the tests.
  36. - **Parallel agents collide.** Several agents on one checkout overwrite each other, and their changes conflict on
  37. the way in.
  38. - **Delegation multiplies risk.** An agent that spawns agents can spend without limit and approve its own work.
  39. - **Long runs break.** A crash or a dropped session halfway through a multi-agent run loses the work, or merges it
  40. twice.
  41. - **You can't see what happened.** Who did what, in what order, at what cost, and why it failed.
  42. capcomd treats each of these as a hard rule rather than a hope.
  43. ## What you get
  44. **Durable runs.** A run is a set of durable actors (built on [Rivet](https://rivet.dev)) whose state survives
  45. crashes and restarts. Every step is an idempotent, recorded transition, so a crashed orchestrator, engine or agent
  46. driver resumes where it stopped, a retried call never acts twice, and a merge happens exactly once. Tests kill the
  47. process at named points to check it.
  48. **Isolation.** Every agent runs in a fresh VM with its own clone and branch; VM snapshots are scrubbed of secrets.
  49. Agents can't touch each other's work or your machine, and never hold push credentials. Inside its VM an agent is
  50. unrestricted by default (every tool, open network); a profile can narrow its tools, sandbox and egress allowlist.
  51. **Verification you control.** You name the checks (`run new --checks-set unit='bun test'`); agents pick one by
  52. name and can never write their own. Checks run on the branch merged with the latest target, in a throwaway VM, so
  53. agent-written code never executes on your host. A merge lands only the exact commit that passed.
  54. **Review by another agent.** Set a reviewer for the run (`--reviewer`) and every change that passes its checks is
  55. also read by a separate, read-only reviewer agent against acceptance criteria. Both must pass; a missing or
  56. garbled verdict is a fail.
  57. **Agents that delegate, safely.** You set the ceiling (depth, fan-out, allowed profiles, budget share); a parent
  58. can only narrow it for its children. Capability tokens scope every call, and text from other agents is treated as
  59. data, never instructions.
  60. **Budgets and cost.** Budgets in dollars, turns and wall time are carved down the tree. Costs roll up per agent and
  61. subtree, including the API-equivalent cost of work on Claude and ChatGPT subscription plans.
  62. **You stay in charge of what lands.** Merges into protected branches wait for your approval. A run can land on its
  63. own staging branch instead of `main`.
  64. **See everything.** A terminal debugger shows the agent tree (what ran in parallel, each child's checks → review →
  65. merge), a span waterfall, per-agent timelines, rollups and the event log, live while the run executes.
  66. ### VMs come from a sandbox provider
  67. capcomd doesn't depend on one VM vendor. It creates, runs commands in, snapshots and destroys VMs through a small
  68. sandbox provider interface ([`src/providers/sandbox.ts`](src/providers/sandbox.ts)): create from a snapshot, exec,
  69. upload and download, egress allowlist, checkpoint and snapshot, suspend and resume, destroy. The orchestration,
  70. durability and gates sit above it.
  71. [boxd](https://boxd.sh) is the first provider, and the one verified live. A local fake provider runs everything
  72. on your machine with scripted agents, for tests and the setup demo (it isolates nothing). More providers, and a
  73. documented contract for writing one, are on the [roadmap](ROADMAP.md).
  74. ## A real run
  75. From the live end-to-end test (`scripts/mac-subagents-e2e.sh`, 2026-10-21): three broken functions in a private
  76. repo, one failing test each. A planner agent split the fix across two Claude workers and one Codex worker, ran
  77. them in parallel, verified each against its own named check in a checks VM, had a reviewer agent review each
  78. change, and merged all three.
  79. | | |
  80. |---|---|
  81. | Result | 3 of 3 fixed, reviewed and merged; full test suite green on the result |
  82. | Agents | 7 (planner, 3 workers, 3 reviewers), 13 VMs, all cleaned up |
  83. | Time | 228s end to end |
  84. | Cost | $0 billed on subscription plans (about $0.37 at API prices) |
  85. ## Quickstart
  86. **Requirements:** macOS or Linux, a sandbox provider account ([boxd](https://boxd.sh) today), a GitHub repository,
  87. and a Claude and/or ChatGPT plan (or Anthropic/OpenAI API keys).
  88. **Install** (one self-contained executable, no runtime to install first):
  89. ```bash
  90. curl -fsSL https://raw.githubusercontent.com/MarvinAmador7/capcomd/main/install.sh | sh
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 123 on GitHub
  91. # or: brew install MarvinAmador7/tap/capcomd
  92. # or, with Bun: bun add -g capcomd
  93. ```
  94. `capcomd upgrade` updates it later.
  95. **The Mac app** (optional; macOS 14 or later): a window with each run's agents side by side and a menu bar item with
  96. approvals, in one app. It uses the CLI you installed above, however you installed it (install.sh, Homebrew, Bun or
  97. npm), and doesn't install a second one:
  98. ```bash
  99. brew install --cask MarvinAmador7/tap/capcomd-app
  100. ```
  101. If Homebrew refuses to load something "from untrusted tap" (Homebrew 7 and later), trust the tap once with
  102. `brew trust MarvinAmador7/tap` and run the install again.
  103. Open capcomd from Applications. It finds your CLI and connects by itself; if capcomd already runs as a service
  104. (`capcomd service install`), it uses that one and the CLI that runs it, and asks nothing. Otherwise it starts capcomd
  105. for you (as a login service). No terminal is needed after this. Without a CLI yet, the app shows the command to
  106. install it. The app isn't notarized by Apple yet, so macOS blocks its first open: click **Done**, then in **System
  107. Settings › Privacy & Security** click **Open Anyway** next to "capcomd" and confirm. After that it opens like any app.
  108. Without Homebrew, download `capcomd-app-X.Y.Z.zip` from the [release](https://github.com/MarvinAmador7/capcomd/releases)
  109. and move `capcomd.app` to Applications.
  110. **1. Add capcomd to your agent.** The capcomd plugin gives your agent the MCP tools and two skills
  111. (orchestration, and setup):
  112. ```bash
  113. # Claude Code
  114. /plugin install capcomd --marketplace MarvinAmador7/capcomd
  115. # Codex
  116. codex plugin marketplace add MarvinAmador7/capcomd # then install capcomd from /plugins
  117. # Hermes (Nous Research): after installing the CLI, in your repository
  118. capcomd setup agent # adds capcomd's MCP server and skills to ~/.hermes (docs/integration-agents.md#hermes)
  119. ```
  120. **2. Ask your agent to set it up**, in the repository the agents should work on:
  121. > Set up capcomd for this repository.
  122. It installs the CLI if it's missing (the installer above), connects your sandbox provider (with the boxd CLI logged in, it creates
  123. a key just for capcomd and keeps it in your OS keychain), builds the agent VM snapshot, detects your repository,
  124. target branch and test command, and starts the engine. A few steps are yours: logging in to boxd
  125. (`boxd auth login`) and your agents (`capcomd auth login claude`) open a browser, and you confirm the gates (the
  126. checks, the reviewer, the target branch). Prefer a terminal? `capcomd setup` after installing does the same,
  127. including the plugin, and can be re-run safely; `capcomd setup check` shows what's configured.
  128. **3. Ask for the outcome:**
  129. > Use capcomd to fix the failing tests in `src/`: one worker per file, each verified and reviewed, then merged.
  130. > Use capcomd to add rate limiting to the API: plan it, put the shared types first, then the middleware and its
  131. > tests in parallel; land on a `staging` branch.
  132. Your agent reports back as agents finish and merges land. Merges into protected branches wait for you:
  133. `capcomd approve <runId> <mrgId>`. Watch a run with `capcomd tree <runId>`, or in the terminal debugger:
  134. `capcomd tui [runId]` (its agents live, a waterfall of what each did, a timeline, cost rollups and events; with no
  135. runId, the latest run).
  136. Each [release](https://github.com/MarvinAmador7/capcomd/releases) has the binaries for macOS and Linux (arm64 and
  137. x64), the npm package and the Mac app (universal, signed ad hoc until it's notarized), each with its SHA-256 (the installer and `capcomd upgrade` check it); the npm package is
  138. published by CI with [provenance](https://docs.npmjs.com/generating-provenance-statements).
  139. ### Connecting your agent
  140. | Agent | How it drives capcomd | Today |
  141. |---|---|---|
  142. | Claude Code | The capcomd plugin: MCP tools + orchestration and setup skills | Works, verified live: Claude Code ran a 3-worker swarm with only the plugin's tools |
  143. | Codex | The same plugin from the marketplace (`/plugins`) | Built to OpenAI's plugin format; not yet tried in Codex |
  144. | Hermes | `capcomd setup agent`: `capcomd mcp` in Hermes's `config.yaml` + the skills ([how](docs/integration-agents.md#hermes)) | Setup tested against Hermes's documented config; not yet driven live |
  145. | Any other MCP client | `capcomd mcp` ([how](docs/integration-agents.md#mcp)) | Works |
  146. | Any agent with a shell | The CLI with `--json` and [the skill](plugins/capcomd/skills/capcomd-orchestration/SKILL.md) | Works, verified live |
  147. The orchestration skill teaches the agent the primitives and when to use which pattern (single loop, fan-out,
  148. supervisor, critic, best-of-n, planner, interface-first).
  149. <details><summary>What your agent runs</summary>
  150. The same commands work for you, and every one takes `--json` (a stable, versioned contract):
  151. ```bash
  152. RUN=$(capcomd run new --budget usd=6,turns=200 --json | jq -r .runId) # checks + reviewer come from setup
  153. A=$(capcomd spawn $RUN --profile worker --task "Fix the off-by-one in src/pager.ts" --check unit --key pager --json | jq -r .agentId)
  154. capcomd await $RUN $A
  155. V=$(capcomd verify $RUN --ref $A --json | jq -r .id) # checks in a VM, then the reviewer
  156. capcomd merge $RUN --ref $A --require $V # only the verified commit lands
  157. ```
  158. Or hand the whole goal to a `planner` agent, which spawns, verifies and merges its own workers from inside its VM:
  159. ```bash
  160. capcomd spawn $RUN --profile planner --task "Fix the three failing tests; one child per file; verify and merge each"
  161. ```
  162. </details>
  163. <details><summary>Setting up by hand</summary>
  164. ```bash
  165. export BOXD_API_KEY=… CAPCOMD_SANDBOX=boxd
  166. capcomd env build # bake the agent CLIs into a VM snapshot (once; no secrets)
  167. capcomd auth login claude # log in with your plan inside a VM (or: codex; fx for a Vercel or Grok login)
  168. capcomd doctor --strict # check every agent works
  169. export CAPCOMD_REPO=https://github.com/you/app.git CAPCOMD_MERGE_TARGET=main CAPCOMD_MERGE_MODE=pr
  170. capcomd profiles add worker --provider claude --auth subscription # no limits; add --max-turns, --timeout-ms or --budget for one
  171. capcomd profiles add reviewer --provider claude --auth subscription \
  172. --allowed-tools 'Read,Glob,Grep,LS,Bash(git diff:*),Bash(bun test:*)'
  173. capcomd serve & # the engine (setup can install it as a service instead)
  174. ```
  175. State lives in `~/.capcomd` (set `CAPCOMD_HOME` to move it); a project's own `.capcomd/` holds its settings and
  176. agent profiles.
  177. </details>
  178. ## Core concepts
  179. | | |
  180. |---|---|
  181. | **Run** | A durable scope with a budget, its named checks, an optional reviewer and target branch (`capcomd run new`). |
  182. | **Orchestrator** | Whoever calls the primitives: your agent, an agent inside a VM allowed to delegate, or you. |
  183. | **Agent** | One Claude Code, Codex or fx session in its own VM and branch (`capcomd spawn`). |
  184. | **Profile** | A reusable agent definition: provider, login, model, limits, tools, and whether it may spawn (`capcomd profiles`). |
  185. | **Check** | A command the operator names for the run; agents choose one per child, never write one. |
  186. | **Reviewer** | An agent profile that reads each verified change and returns pass or fail with reasons. |
  187. | **Verify / merge** | `verify` runs the checks and the review on a commit; `merge --require` lands exactly that commit. |
  188. | **Report** | A read-only agent (`spawn --report`) whose answer is its result: research, triage, analysis. |
  189. | **Provider** | Where VMs come from, behind the sandbox provider interface ([boxd](https://boxd.sh) today). |
  190. ## Safety model
  191. - **Gates belong to the operator.** Test commands, the reviewer, protected-branch approvals and the target branch
  192. are set by you; agents can't choose or change them.
  193. - **Authority comes from tokens, not text.** An agent can only act on its own subtree with the operations its token
  194. grants; anything another agent writes is fenced and treated as data.
  195. - **Nothing runs on your machine.** Agents and checks run in VMs. An agent's VM holds only its own login, never a
  196. git credential: capcomd fetches and pushes for it from your machine; a checks VM holds none.
  197. - **No self-approval.** An agent can't verify or merge its own work.
  198. ## Integrations
  199. - **Plugin** for Claude Code and Codex ([plugins/capcomd](plugins/capcomd)): the MCP server and the
  200. [orchestration](plugins/capcomd/skills/capcomd-orchestration/SKILL.md) and
  201. [setup](plugins/capcomd/skills/capcomd-setup/SKILL.md) skills.
  202. - **CLI with a JSON contract**: every command takes `--json` (schema `relay.v1`, stable exit codes), documented in
  203. [docs/output-contract.md](docs/output-contract.md).
  204. - **MCP server** (`capcomd mcp`): the primitives as tools for your agent, with bounded waits; it starts the engine
  205. when none is running. See [docs/integration-agents.md](docs/integration-agents.md#mcp).
  206. - **Hermes** (Nous Research's agent, also from Telegram, Slack and the rest of its gateway): `capcomd setup agent`
  207. registers the MCP server and installs the skills; see [docs/integration-agents.md](docs/integration-agents.md#hermes).
  208. - **Other callers** (scripts, services): see [docs/integration-agents.md](docs/integration-agents.md).
  209. - **Plugins for capcomd** (a notifier, a gate on merges, …): your own program, started and supervised by the daemon,
  210. written with `@capcomd/plugin`; see [docs/plugins.md](docs/plugins.md).
  211. ## Documentation
  212. - [STATUS.md](STATUS.md): what works today, and how it's verified.
  213. - [ROADMAP.md](ROADMAP.md): what's next, known limits and their approaches.
  214. - [CHANGELOG.md](CHANGELOG.md): what's in each release.
  215. - [DEVELOPMENT.md](DEVELOPMENT.md): architecture, tests, cutting a release.
  216. - [docs/](docs/): design decisions (ADRs), and the operator's orchestration skill in [skills/](skills/).
  217. ## Contributing
  218. Issues and pull requests are welcome: see [CONTRIBUTING.md](CONTRIBUTING.md), the [Code of Conduct](CODE_OF_CONDUCT.md),
  219. and [SECURITY.md](SECURITY.md) for reporting vulnerabilities privately. Coding agents follow [AGENTS.md](AGENTS.md).
  220. ## License
  221. [MIT](LICENSE) © Marvin Amador Campos
plugins/capcomd/mcp/launch.sh · Bundled script · 12 lines · 1 finding marked
  1. #!/bin/sh
  2. # The capcomd plugin's MCP server (ADR-018 §2). Agent apps often start servers with a short PATH, so look in the
  3. # usual install places too. launch.mjs finds the installed capcomd and runs `capcomd mcp`, or serves a one-tool
  4. # server (capcomd_setup) that says how to install it. Without bun or node to run it, the capcomd binary serves itself.
  5. here=$(cd "$(dirname "$0")" && pwd)
  6. PATH="$PATH:$HOME/.capcomd/bin:$HOME/.bun/bin:/opt/homebrew/bin:/usr/local/bin"
  7. export PATH
  8. if command -v bun >/dev/null 2>&1; then exec bun "$here/launch.mjs"; fi
  9. if command -v node >/dev/null 2>&1; then exec node "$here/launch.mjs"; fi
  10. if command -v capcomd >/dev/null 2>&1; then exec capcomd mcp; fi
  11. echo "capcomd plugin: capcomd isn't installed; install it with: curl -fsSL https://raw.githubusercontent.com/MarvinAmador7/capcomd/main/install.sh | sh" >&2
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 11 on GitHub
  12. exit 1

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.