Install

CC ships as two artefacts built from one source: a plugin for Claude Code, and a CLI on npm. They install separately, update separately, and do not collide — the plugin carries its own copy of the binary and puts nothing on your PATH.

Which one you want depends on what you are after:

What you want	Install
Writes into a closed zone blocked as they happen, in Claude Code	The plugin
cycle in any terminal, in any editor, in CI	npm
Both	Both — they are independent

The distinction is not packaging trivia. Only the plugin enforces, and it is a Claude Code plugin. Everything else runs the process and records it. For Codex, Cursor and Windsurf, what blocks in each editor says what exists and what has never been exercised.

The plugin — Claude Code

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

Four things arrive with it:

• The hook — PreToolUse and PostToolUse on every tool call. This is the only part that stops a write before it lands, and the only part that produces .zones/state/events/: a witness, not a decision.
• An MCP server with five read-and-describe tools — cc_zones, cc_intake, cc_interview, cc_scope, cc_status. None of them starts work, issues a grant, or approves access. That is D-31, not an oversight.
• Two skills — one that sets a repository up by asking about it, one that files and scopes a task before the work begins.
• Its own binary. No npm install step, nothing added to PATH, nothing outside the project you are working in.

Why installing it cannot break your other repositories

Plugin hooks load user-wide — they run in every repository you open, not only the one you set up. That is exactly why the hook was held back until it could tell “this repository never installed CC” from “this task has not been started yet”. It could not, and answered deny to both, so a single install would have blocked every write in every unrelated project on the machine.

It can now. A repository with no .zones/zones.yml is left alone silently — allowed, nothing recorded, no advice. You should not be able to tell the hook ran. A repository that has a zone map keeps every rule it has, and an empty map is not the same thing as an absent one: that is a project that ran the setup and protected nothing, and a task is still required there.

If /plugin reports an old version

/plugin reads the version from its local clone of the marketplace repository, not from GitHub. A release pushed minutes ago will show as “already at the latest version” until that clone refreshes. Run /plugin again to update it, then /reload-plugins to apply.

The CLI — npm

npm i -g commitcycle
cycle init

The command is cycle, not cc. On every Unix machine cc is already the system C compiler, and a governance tool that shadows a compiler is a governance tool people uninstall.

The npm package does not carry the hook

It ships the CLI and nothing else. So npm gives you the whole process — the board, the gate, grants, records, the closing checks — and not the wall.

That split is deliberate. Nothing running in someone else’s cloud can stop a file being written on your machine, and nothing installed as a library can see an editor’s tool calls. Enforcement has to live where the writes happen, which is why it arrives with the editor plugin.

What blocks in each editor

A wall is a hook that the editor runs before each tool call, and every editor reads its hook from a file of its own. A file on disk is not a wall that fires: Claude Code is the only editor where CommitCycle has been seen to block a write. For Codex, Cursor and Windsurf, everything below is read from the vendor’s own documentation and from what cycle init writes, and none of it has been exercised against a real install of that editor.

Editor	Hook file	Seen to block a write
Claude Code	the plugin, or .claude/settings.json	yes
Codex	.codex/hooks.json	no — never exercised
Cursor	.cursor/hooks.json	no — never exercised
Windsurf (Devin Desktop)	.windsurf/hooks.json	no — never exercised

Claude Code

The plugin’s PreToolUse hook denies a write into a closed zone before it lands. Claude Code is fail-open when a hook script is missing, which is why cycle init writes hook configuration only where a wrapper is already on disk (CC-641). macOS and Linux are the platforms that enforce today; Windows is post-MVP (D-25), and nothing blocks there yet.

Codex, Cursor and Windsurf: what cycle init --harness leaves behind

The hook files for these three editors come from cycle init --harness with codex, cursor, windsurf or all; Codex’s is also written by default, beside Claude Code’s. Two facts decide what that command actually leaves behind:

• It writes a hook file only where a hook wrapper is already on disk. An editor told to run a script that is missing lets the write through without a word, so with no wrapper cycle init writes no hook file for any editor, and prints that it did not. Neither published artefact, the plugin or the npm package, puts a wrapper where cycle init looks for one.
• The file it writes does not select that editor’s reply. The hook picks its reply format from how it is invoked, and these entries carry no argument that picks it (CC-729), so the hook answers in Claude Code’s format. What Codex, Cursor or Windsurf does with that reply has never been observed, and cycle init prints beside each of these files to treat it as filed, not as enforcing.

Codex

• Trust. Codex ignores a project’s .codex/ layer, hooks included, until the project is trusted. Nothing in CommitCycle checks that, so in an untrusted project .codex/hooks.json is inert and nothing here can tell.
• Not verified. No Codex install has ever run the entry cycle init writes. Its shape is the one OpenAI documents, which is a different claim from “it works”.

Cursor

• Trust. Cursor loads project hooks only in a trusted workspace, and nothing in CommitCycle checks that.
• Coverage. Only preToolUse is registered in .cursor/hooks.json, with failClosed: true; without it, Cursor lets the action through when a hook crashes, times out or returns invalid JSON. Shell commands, MCP calls and file reads go through separate Cursor events that are not registered, so treat shell commands and file reads in Cursor as unguarded.
• Not verified. .cursor/hooks.json has never been exercised against a Cursor install.

Windsurf (Devin Desktop)

• Channel. Windsurf has no JSON reply: a denial is exit code 2 and nothing else, and any other non-zero exit lets the action proceed. show_output, reported to be what lets a person see why an action stopped, is not written, so a person blocked here may see the action stop with no reason given.
• Coverage. .windsurf/hooks.json registers pre_write_code, pre_read_code, pre_run_command and pre_mcp_tool_use: writes, reads, commands and MCP calls.
• Rename. Windsurf is being renamed Devin Desktop, and whether .windsurf/hooks.json keeps working, and for how long, is not documented.
• Not verified. .windsurf/hooks.json has never been exercised against a Windsurf install.

What you actually have

cycle doctor answers this better than any version number, because it checks the wiring rather than the label:

$ cycle doctor
[  ok  ] git repository         /path/to/your/repo
[  ok  ] zone map               4 zone(s): schema, contracts, enforcement, brand
[  ok  ] hook installed         .../hook/bin/cc-hook.sh
[  ok  ] active task            CC-262 — no zones open

A row that is not ok names what is missing and what to run. The hook installed row is the one that separates documented from guarded: without it, everything else still works and nothing is stopped.

That row reads Claude Code’s wiring: the plugin and .claude/settings.json. It does not read the Codex, Cursor or Windsurf hook files, and nothing in CommitCycle can tell whether an editor trusts the project.

For the packages themselves:

npm view commitcycle version    # what the registry holds
npm ls -g commitcycle           # what this machine installed

and /plugin inside Claude Code for the plugin’s own version. There is no cycle --version; cycle doctor is the supported answer.

Updating

The two are independent — updating one does not move the other.

/plugin            # refreshes the clone, then /reload-plugins

npm i -g commitcycle@latest

What to read next

• Quickstart — a board, a connector and a zone map, in about five minutes
• Two accounts on one machine — signing in more than once, and which identity a repository uses
• Two sessions at once — the layout that lets two agents work on one repository without one authorising the other’s writes
• The three layers — what enforcement proves, and what it does not