Quickstart

This page shipped empty for months, on purpose — a quickstart describing software you cannot download is marketing wearing a docs costume. Every step below is real now. What still separates a connected repository from a guarded one is one thing, and step 4 names it rather than rounding it off.

Steps 1–3 download and run nothing on your machine.

1 · Open a board

Signup is closed while CommitCycle is this new — ask for an invite if you have not already, and this step waits until you have one.

With an invite: go to dash.commitcycle.com. One address, one six-digit code — no password, no card. An address nobody has invited is turned away before any code is sent, so if you get that refusal, nothing was created and nothing is broken.

You will be asked to name a project — the word that screen uses for the organization that owns your boards — and a repository. Every board lives at that pair, so both are needed before there is one to open. Neither is permanent except the address you signed in with.

2 · Connect your editor

Open Connect a machine in the sidebar and stay on the Connector tab. It gives you a URL and, under it, the exact line for your editor.

For Claude Code:

claude mcp add --transport http commitcycle "<your connector URL>" --scope local

For Cursor, Windsurf or Codex, copy the JSON block beside it into your MCP settings.

Three things worth knowing before you paste it:

• The URL contains a key. --scope local keeps it out of anything you would commit. Treat it like a token, because it is one.
• It is listed and revocable. The connector shows up in the machines table on that same page. Revoke it there and it stops working immediately.
• It blocks nothing, in any editor. The connector runs the process; the wall is step 4, and step 4 is a Claude Code plugin. In Cursor, Windsurf and Codex, no CommitCycle hook has been seen to block a write, and none has been exercised against a real install of that editor. What blocks in each editor says what exists there and what has never been tried.

3 · Let your agent set the repository up

With the connector added, ask your agent to set this repository up for CommitCycle. It has nine tools: cc_setup, cc_zones, cc_status, cc_intake, cc_interview, cc_scope, cc_start, cc_submit and cc_close.

These three files are the whole of a fresh setup — if that looks thin next to a repository that has been running a while, see what .zones/ contains: the rest appears on its own as you use it.

cc_setup does not install anything, and it does not read your code — your agent does. The agent looks at the codebase, proposes the paths that would hurt if another agent got them wrong — with a reason for each that you can argue with — and the tool renders what you agreed into three files for the agent to write:

• .zones/zones.yml — the zone map
• .zones/board.json — which board this repository answers to
• the AGENTS.md block — how the next agent discovers all of this exists

Say no to any zone you disagree with. A map of thirty zones is a map nobody keeps.

From here the whole state machine runs: file a task, scope it, and cc_start asks the gate to open it — the gate decides exactly as it does everywhere else, and hands back the branch to create. cc_submit hands the work in; cc_close runs the closing gate against the file list you report and asks one question on the way out — what did this work teach? Records, grants, audit files and playbook lessons all arrive as files for your agent to write, so the repository keeps its own history.

4 · Enforcement — the one deliberate install

This is the difference between documented and guarded, and it is one step.

Everything above runs the process: the map, the board, the gate deciding every transition, the records and audit files landing in your repository. What none of it does is block a write as it happens. Steps 1–3 work on the honour system — a close reports its file list, nothing independent observed the writes, and the audit record shows it: base and head read reported instead of commit SHAs, and its observed-mutations count is zero.

The wall is the hook, and it ships in the CommitCycle plugin:

/plugin marketplace add pow-paulinho/commitcycle-plugin
/plugin install commitcycle@commitcycle

With it installed, writes into a closed zone are denied at the tool call, before they land, and .zones/state/events/ starts recording what the hook actually saw — the one part of the record no server can produce, because it is a witness, not a decision.

That plugin is for Claude Code, the one editor where CommitCycle has been seen to block a write. Codex, Cursor and Windsurf each read a hook file of their own, and cycle init --harness writes one only where a hook wrapper is already on disk. None of the three has been exercised against a real install, and Codex and Cursor ignore a project’s hooks until the project is trusted — which nothing in CommitCycle checks. What blocks in each editor has the rest.

The CLI on its own installs from npm — npm i -g commitcycle, and the command is cycle — but that package carries no hook. Install lays out both artefacts and what each one does.

cc_setup still refuses to write hook configuration itself, and the reason is measured: Claude Code is fail-open when a hook script is missing, so a repository carrying hook config with no binary behind it looks protected and blocks nothing — worse than no zone map at all, because you would stop checking. The install is deliberate or it is theatre.

What to read next

• Install — the plugin, the CLI, and which one is the wall
• Two sessions at once — one worktree per session, and the incident that made it a rule
• What is CC? — the model in one page
• Zones — what belongs in a zone map and what does not
• The three layers — including what Phase 0 proved and what it did not