REPLUME / DOCS / START

Start

Set up Replume once in your Git repository. Then give your coding agent a task as usual.

Let your agent set it up

Paste this into Claude Code, Cursor or Codex. The linked checklist tells it to check Node, install the persistent command, verify its project hooks, and run your existing test command once.

Read https://replume.dev/docs/onboard-with-your-agent.md and set up Replume in this repo.

The agent should report what it observed. It should stop and ask you only if global installation needs permissions or the repository has no test command. Read the agent checklist →

Or do it yourself

Use macOS or Linux, Node.js 20 or newer, Git, and a repository with a working test command. Install globally so project hooks can find replume later.

Install

Terminal

npm install -g replume-cli
replume --version

The published version is 0.2.1. If an older version prints, check command -v replume; your shell may find an older installation first.

Initialize in the repo root

Terminal

git rev-parse --show-toplevel
replume init

The first command must print your repository root. The normal default init then prints:

Output

Replume is on (mode: auto). Hooks are installed.
Start your agent in this folder.
Nothing else to set up.

The banner does not prove that your agent's hooks were installed or fired. For Cursor without a .cursor/ directory, use replume init --cursor. For Codex without a .codex/ directory, use replume init --codex, then trust the project hooks with /hooks. Check the agent-specific hook file →

Give your agent a task

Start Claude Code, Cursor or Codex in this repository and ask for a concrete change. In auto mode, Replume forms a task contract from the first prompt; no draft, confirm or setup commit is needed. The contract can misread the scope, so inspect what it assumed.

Watch the checks, if you want

Second terminal in the same repo

replume watch

watch displays recorded hook events; it does not run checks by itself. replume watch --once prints the recorded lines and exits.

START: The task prompt reached Replume.
OK: An agent action was recorded without a block or warning.
BLOCK: The hook denied an action; read the reason before the agent tries another path.
STEER: Replume warned or advised the agent. A warning is not a block; check what the agent did next.
TEST: The test command ran and the line says whether it passed or failed.
RETRY: A failed Stop check sent the agent back. The number shows the attempt and limit.
GATE: The Stop test check passed.
HOLD: Replume asked the agent to continue instead of finishing.
STOP: The agent's turn ended.
PASS / FAIL / INCOMPLETE: The report passed its checks, found a failure, or could not verify enough. INCOMPLETE is never PASS.

When an action is blocked

For a protected test or config file, have the agent fix the source instead. For a scope warning, keep the work on the task or explicitly widen the task if another file is needed. After a RETRY, use the failing test output; retries have a limit. If the report is INCOMPLETE, read which check was missing before continuing.

Read the report

At finish, Replume saves Markdown and HTML under .replume/reports/. Start with PASS, FAIL or INCOMPLETE, then read the test result, changed paths, steering and missing evidence. A green test does not prove every requested behavior. How to read the report →

NextHow it works ↗