gm

# gm

gm is a skill and MCP server for coding agents (Claude Code, Cursor, Gemini CLI, Codex). It keeps a plan of tasks, runs real checks, and refuses to let the agent mark a task finished until those checks pass. It is for developers who already use one of these agents.

A gate decides when work is done, not the coding agent. Most agent harnesses ask the model to follow a process. gm turns the process into a state machine. Six edges in the graph carry gate predicates, and the edge from the gate state `G_SWEEP` into `COMPLETE` carries 21 of them. The CI check (`ci-validated-fresh`) reads the CI marker file `.gm/exec-spool/.ci-validated`, which `git_finalize` writes when its inline `ci-status` check reports success or no applicable workflow for HEAD. A hand-written marker that names HEAD also passes, so the check records intent and does not prove that CI ran.

[Releases](https://github.com/AnEntrypoint/gm/releases) | [License](./LICENSE) (MIT) | [Discord](https://discord.com/invite/c9VV59MKNr) | [Site](https://anentrypoint.github.io/gm/)

## Install

Run this in a terminal (Node.js required):

```
npx github:AnEntrypoint/gm -g
```

It installs the `/gm` skill and registers the MCP server in every detected agent host: Claude Code, Cursor, Gemini CLI and Codex. Drop `-g` to install into the current project only.

The MCP server launches from the local bundle, `~/.gm-tools/gm-mcp-server.mjs`, and never from an npx GitHub spec. A spec re-resolves the package on every connect: measured at 8.2 s warm and 22.2 s cold, against 0.19 s to launch the bundle from disk, which under load can trip Claude Code's 30 s connect timeout ([gm-mcp/README.md](./gm-mcp/README.md)). To repair a registration, run the first command for a global install (`-g`) or the second for the current project:

```
node bin/gm-install.js -g --mcp-only
node bin/gm-install.js --mcp-only
```

Restart the agent host after a registration change. Then open the agent and run `/gm` with a description of the change. The agent turns it into plan rows (one task each, see Terms) and works through them until every plan row is closed.

The `bin/gm` entry point runs a verb from a plain shell, with no agent host and no MCP client, using the same dispatch that `gm.gm({verb, body})` inside the `gm_codemode` MCP tool (see Tools below) runs.

### Skill only

Use this path only if you do not want the npx installer. On macOS or Linux:

```
curl -fsSL https://raw.githubusercontent.com/AnEntrypoint/gm/main/install.sh | sh -s -- install
```

On Windows PowerShell, `irm ... | iex` cannot pass an argument, so download the script and run it with `install`:

```
Invoke-WebRequest https://raw.githubusercontent.com/AnEntrypoint/gm/main/install.ps1 -OutFile install.ps1
.\install.ps1 install
```

Both scripts resolve the latest tagged release under [AnEntrypoint/gm releases](https://github.com/AnEntrypoint/gm/releases). They download the `gm-skill-<version>.tar.gz` asset and check it against its published SHA-256 sidecar. They then install `skills/gm` into `~/.claude/skills/gm/`. Run from a checkout (or with `GM_SKILL_SOURCE_DIR` set), the install is a link: a directory junction on Windows and a symlink elsewhere. A source edit then reaches the installed skill without a reinstall. With no local source, the install copies the release.

Inside a project, run the same script with the argument `spool`, for example `curl -fsSL https://raw.githubusercontent.com/AnEntrypoint/gm/main/install.sh | sh -s -- spool`. It starts the `agentplug-runner` that serves the project's verbs: the script resolves, checks, and runs that native spool host from the `AnEntrypoint/agentplug-bin` releases.

## Terms

- **gate**: a check that must pass before the agent may move to its next step.
- **edge**: a move from one graph state to another. A gate can sit on an edge and refuse the move.
- **predicate**: the check a gate runs, named in the `gates` array of `gm-config/fsm/graph.json`.
- **verb**: a command the agent sends to gm, such as `codesearch` or `git_status`.
- **spool**: the file queue under `.gm/exec-spool/`. A request is a file in `.gm/exec-spool/in/`, and the runner writes the reply to `.gm/exec-spool/out/`.
- **plan row**: one task, stored as a file at `.gm/prd/<id>.yml`.
- **mutable**: one open question, stored as a file at `.gm/mutables/<id>.yml`.
- **principle**: one discipline, usually from a book or author, that the agent applies to the code, such as Jobs To Be Done (Clayton Christensen).
- **CI marker**: the file `.gm/exec-spool/.ci-validated`, the marker that the `ci-validated-fresh` predicate reads.
- **walk**: one run of the gm state machine, driven to COMPLETE.

## Why gm uses a gate

gm will not let the agent say a task is done until every plan row is closed with recorded evidence, the CI marker names the current commit, and submodules are clean.

A refused transition names the gate and the condition that failed. The agent cannot route around a refusal. The graph's `gates` array name

... (truncated)