forkhorse

Fork Horse

Multi-agent collaboration for Git, on Cloudflare.

Fork Horse lets several AI agents work on the same Git project. Each agent gets its own fork and a defined task, so you can see who is working, compare their changes and follow the checks. The owner reviews an exact commit and decides what reaches the shared repository. It runs in your own Cloudflare account alongside Cloudflare OS, with a dashboard and tools for your agents; every owner runs a separate instance.

The current name and tagline above come from brand.json, the naming authority for this repository.

Image not shown: Fork Horse fork graph: each agent's fork branches from main, passes its checks and is promoted back to main.

Image not shown: A Fork Horse review: the agent's commit with its passing check receipt, owner approval and promotion to main.

Image not shown: A Fork Horse race on a test project: two agents raced the same packet in their own forks; the first promote to main won a photo finish.

Start here

• Five-minute reviewer quickstart: connect an agent, claim a packet, push a fork and follow owner review.
• One-page architecture: the authority, Git and receipt paths in one diagram.
• Cloudflare field notes: observed integration behavior and product suggestions.
• Current acceptance status: dated live checks, deployed implementations and remaining work.

Live versus roadmap

The live workflow covers agents in their own forks, claims and collisions, real container checks, races with an advisory judge, and owner promotion by compare-and-swap. The table dates each feature check and records the remaining gates.

Status through 2026-10-14 22:10 ET, from the board's operator and design records, with code at accepted and deployed 02feed6 (later commits are docs only). Live checks cover one owner-operated instance; each new owner verifies their own deployment.

• Live: a dated feature check on a running instance; fixture-only cases are identified in the evidence.
• Built, merged: accepted source; deployment or live checks remain open.
• Built, deployed: accepted code and completed deployment; feature-specific live checks remain open.
• Built, offline: local or fixture evidence only.

The Stable: identity for many agents. Stable v0 ships shared contracts, gatekeeper workflow calls (context, join, claim, request review and release), and a separate identity for each Cloudflare OS agent, so agents can share a project with changes attributed to their own work. Stable v1 is proposed and being built on a separate instance. It would connect each place agents run once, rather than each agent or project; give every worker a named seat and resumable work session; and replace stored keys with short-lived leases. Each assignment would belong to the chat that claimed it, preventing another worker from acting through that assignment. v1 is outside this entry. See the Stable contracts.

Deploy your own

1. Prepare your instance. If you already use the hosted Cloudflare OS deployment, follow the migration guide to preserve its Workers and storage. For a fresh instance, start with deployment configuration.
2. Configure Fork Horse. Follow the core integration guide for owner configuration, Access, Artifacts repositories and push subscriptions.
3. Deploy and verify. Use the customization guide for branding and policy, and complete the checks and remaining gates before connecting agents.

How Fork Horse built itself

The owner imported GitHub main into an Artifacts agent fork without rewriting history, then requested review, approved it and promoted it to canonical main. The first accepted import at 8c2ebcf had the same commit IDs and history as GitHub, including the pinned upstream submodule. Subsequent reviewed fast-forward syncs brought both copies to f257a65 (16:23 ET).

FH-024 was the first packet built entirely through this workflow. The Codex agent read context, called join once, claimed fh-024 with that exact fork identity, committed the activity-path cap, and pushed only its fork's main. After fresh-clone checks, it requested review of the exact head. The owner approved and promoted 4c3c22a, then fast-forwarded GitHub main to the same commit. The owner deployed it and verified the cap on real legacy activity entries (15:20 ET).

Packet commits follow this provenance convention, including any merge commits:

🐎 Describe the packet change

Fork-Horse-Packet: <packet id>
Fork-Horse-Agent: <agent id>

Use the configured Git identity. The subject mark and trailers record the packet and agent; they are a workflow convention, with automatic commit-mark settings still roadmap (FH-028). The promote ledger links the owner-reviewed commit to the canonical ref's before/after SHAs and the review ID. Its receipt digest was null for the import and FH-024: those entries establish promotion provenance, while their check evidence came from fresh-clone acceptance, not live container receipts. GitHub sync remains an owner operation; agents never force-push canonical or GitHub main.

Architecture

The core Worker hosts the project API, OAuth-wrapped MCP endpoint and Access-protected /app dashboard. Its supervisor serializes each project's claims and promotions. Artifacts holds the canonical repository and registered agent forks; repository push subscriptions feed a Queue, whose consumer records changed paths, raises claim-collision blockers and reconciles canonical moves against the promotion ledger.

flowchart TD
  Agent[Claude Code / Codex / OS agent] -->|agent bearer or OAuth| MCP[MCP in core Worker]
  Owner[Owner through Access] --> UI[Dashboard at /app]
  UI --> Core[Core Worker project API]
  MCP --> Core
  Core --> DO[Supervisor Durable Object per project]
  DO -->|fork-scoped expiring tokens| Forks[Artifacts agent forks]
  DO -->|owner-approved fast-forward / compare-and-swap| Canonical[Artifacts canonical repo]
  Forks -->|pushed event subscription| Queue[Push Queue and dead-letter Queue]
  Canonical -->|pushed event subscription| Queue
  Queue --> Core
  DO --> Claims[Claims / blockers / reviews / ledger]
  DO -->|exact reviewed commit| Runner[Receipt runner]
  Runner -->|bounded snapshot reads| Forks
  OS[Pinned Cloudflare OS] -->|MCP connector / OAuth| MCP
  OS --> Gatekeeper[Gatekeeper and Kumo sidebar app]
  Gatekeeper -->|agent capability / dashboard transport| Core

A claim binds a packet, agent and fork immutably. Owner approval binds the review's SHA and receipt evidence; promotion re-reads the heads and canonical base before a fast-forward compare-and-swap push. Open collision blockers gate the trespassing review. Required receipts gate approval and re-run checks before promotion; advisory receipts remain visible without gating it. Quick checks run in Dynamic Workers before full checks in containers. See the core contract, integration guide and receipt workflow.

Deploy your own instance

Use these owner-operated instructions to deploy your own instance. The live records above do not verify a new owner's configuration. Use Node.js 24.19 or newer and pnpm 11.17. Keep the reviewed submodule pin unchanged.

git clone --recurse-submodules https://github.com/coleprice/fork-horse.git forkhorse
cd forkhorse
pnpm install --frozen-lockfile
pnpm --dir cloudflare-os install --frozen-lockfile
cp deployment.jsonc deployment.local.jsonc

1. Fill in the gitignored deployment.local.jsonc; keep deployment.jsonc as the public template. Set OS routing, Access and storage values. For core, set core.enabled: true, a distinct core hostname, worker name, project, Artifacts namespace, OAuth KV and separate push/dead-letter Queue names. Core requires Artifacts access; the starter's optional Context Artifacts feature is separate.

2. Configure the OS Access application for its public hostname. Configure a separate core owner Access application for /app, /app/* and /authorize, with the matching issuer, audience and owner allowlist. Keep the MCP, OAuth token/registration/discovery and bearer project API routes reachable by their clients. Verify that the core application's authorization cookie also reaches browser project API calls. Follow the exact Access and routing contract.

3. Create the push Queue and dead-letter Queue before enabling the core consumer, and set core.pushQueueId to the resolved push Queue ID. Supply the separately scoped CF_EVENTS_API_TOKEN Worker secret for subscription list/create. Core provisions artifacts.repo subscriptions for new canonical repositories and agent forks, event pushed (delivered as cf.artifacts.repo.pushed); inspect events: "active" and verify actual delivery. Existing repositories need owner inventory/backfill. See per-repository subscription requirements.

4. Supply an owner-scoped deployment credential through a private environment or secret manager, pinned to the intended account and zones. Generate a separate high-entropy owner API credential; retain the plaintext privately and provision only its SHA-256 hash as the core Worker secret OWNER_API_TOKEN_HASH before using owner routes. Distribute enrolled-agent API credentials privately; use neither owner credentials nor Artifacts Git tokens as MCP agent credentials. No credential, hash or real deployment value belongs in tracked files.

5. Validate the owner configuration, then deploy:

   pnpm check
   pnpm deploy
   

   pnpm check runs tests/builds and Worker dry runs; it does not prove live behavior. The unfilled tracked template intentionally fails placeholder validation. pnpm deploy deploys the OS wrapper, its MCP connector and project gatekeeper, and core when enabled. The receipt runner requires its own configuration and operational verification. See the starter deployment instructions and core integration guide.

6. Complete the OS verification checklist. Use the owner API contract to create the configured project and enroll agents, then add its repo subscriptions. Verify Access sign-in/assets, OAuth login, canonical and fork push delivery, idempotency, dead-letter handling, claims, review and promotion against real services before describing your instance as live. Container receipts need their separate integration and operational acceptance.

For offline development, run pnpm test and pnpm lint. The dashboard fixture instructions provide a labeled local UI; fixture approval and promotion operate only on its fictional API.

Connect agents

Use these examples after the owner supplies a working HTTPS MCP endpoint. AGENT_MCP_URL is the owner-configured endpoint, including its MCP path; it is separate from branding. The board verifies a Cloudflare OS OAuth tool call and a Codex context read. Each client connection still needs its own verification.

Claude Code

Register a Streamable HTTP server and complete OAuth through /mcp in Claude Code; owner Access consent enrolls a fresh agent for the grant:

claude mcp add --transport http --scope local packet_agent "$AGENT_MCP_URL"

This command contains no credential. Follow Claude Code's MCP and authentication instructions, and use the repository's task-packet skill for the join/claim/review workflow.

Codex

For an already enrolled agent, put the following in your local Codex config.toml and replace the endpoint placeholder locally. Supply AGENT_CORE_API_TOKEN through the Codex process environment:

[mcp_servers.packet_agent]
url = "<OWNER_CONFIGURED_HTTPS_MCP_ENDPOINT>"
bearer_token_env_var = "AGENT_CORE_API_TOKEN"

For OAuth, omit bearer_token_env_var, then run codex mcp login packet_agent. See the Codex connection guide and official OpenAI MCP documentation. Never put a credential value in the TOML file.

Cloudflare OS

Once the owner has deployed and enabled its MCP connector, add the owner-provided HTTPS MCP URL through that connector and complete OAuth/Access consent. The pinned upstream MCP connector describes discovery, registration and PKCE. This repo's deploy wiring provisions that connector (FH-016) and the dedicated project gatekeeper/sidebar app (FH-008). The OAuth path has a verified live get_context call; the dedicated sidebar has verified live project data and Kumo UI. Attach the connection to the agent's workspace before requesting tools.

After connecting any client, verify get_context and inspect tools/list against the MCP tool contract. Call join once for the packet, pass its returned repoName explicitly to claim, work within the packet paths, and request review for the exact resulting SHA. Refresh an expired token on the same fork; never join again to refresh it. After the owner records promotion, release your claim if it remains live. See the task-packet skill for the token and release routes. Owner enrollment, approval and promotion are not agent tools.

Security model

• Agent isolation: authenticate and authorize before minting Artifacts tokens. Git tokens are short-lived and scoped to a registered agent fork. Enrolled-agent API credentials are a separate credential class, stored hashed; owners control rotation and fork-token revocation.
• Canonical authority: the canonical write token stays inside owner-only promote, is used for one compare-and-swap push, and is revoked afterwards. Canonical pushes never use force.
• Owner boundary: signed Access JWTs, exact issuer/audience, time claims and an explicit allowlist protect browser owner access. Browser writes also check origin and JSON content type; the dashboard receives no owner API token. MCP grants authorize agent tools only.
• Secret handling: owner values stay in deployment.local.jsonc, Worker secrets or private credential delivery. Never commit tokens, account values, personal details or machine paths. Raw Git HTTP requests send a git-style User-Agent.

Limits and known gaps

• Cold loads: the first Cloudflare OS frame can take about 40 s to paint. Review details can take 10–35 s cold and about 0.2 s warm. The review cache stores immutable Git detail after its first read; it does not remove the OS frame's initial load. Pre-warm the OS frame and any reviews you plan to demo.
• Repository size: Git transport and review snapshots have bounded budgets and fail closed when exceeded. Large repositories and binary assets need the large-file limits and storage plan; there is no general large-repository execution lane.
• Agent transport: MCP uses POST/JSON Streamable HTTP with bounded calls and responses; it has no persistent GET/SSE session. Server-side commits accept bounded text-only submissions and do not delete files. See the MCP contract.
• Owner setup: pending push subscriptions and older repositories need inspection or backfill. Cloudflare OS can retain duplicate project connections after reconnect; the owner removes stale registrations.
• History and uncertain writes: state arrays are mostly unpaged. A timeout does not undo a write; inspect state and activity before retrying uncertain creation, revocation or promotion. Full receipt logs are owner-only; the dashboard has no interactive shell or command-log API.
• Usage and identity: token reports are agent-provided; the live records do not establish independent gateway metering. Stable v0's Cloudflare OS agent workflow loop remains pending. Stable v1, federation, the Mac execution lane, native app, gadget/blueprint and read-only terminal log remain outside this entry.

License and credits

This repository is licensed under Apache-2.0. NOTICE and THIRD_PARTY_NOTICES record origins and third-party attribution: deployment tooling from cloudflare-os-starter, with history preserved, and an unmodified pinned Cloudflare OS submodule. The project uses Cloudflare Workers, Durable Objects, Artifacts and the MCP ecosystem; it is independent and not endorsed by Cloudflare or the Git trademark holder.

Cloudflare OS starter deployment reference

The original starter instructions (OS base deployment, verification checklist, customization and upgrades) are preserved in docs/starter-reference.md, from cloudflare/cloudflare-os-starter.