Claude Code

Every agent that reads AGENTS.md gets the context. For Claude Code, Rness does more: the context loads when a session starts, an edit of a generated file or a mistake in .rness/ is refused before it is written, the workspace stays in view in the prompt footer, and the /rness:* commands help write and close decisions, specifications and plans.

Tested with Claude Code 2.1.289 (2026-10-04).

Turn it on

rness sync --agent claude

This declares Claude Code in rness.json for the whole team, then writes its files in every repository. A new workspace asks during create. Commit .rness/rness.json, then, in each repository:

git add .claude/settings.json .claude/skills/rness .mcp.json
git commit -m "chore: rness for Claude Code"

Claude Code applies these files once you trust the folder, in an interactive session. A folder inside one you already trust is never asked, and the /rness:* commands stay hidden: see Troubleshooting.

What it gives you

In a session	What happens
At start	A line such as rness 0.19.0 · acme · scope web — 10 standards, 9 decisions, and the scope's documents for the model. When the context may be wrong, both say why. A Claude Code older than 2.1.280, which shows no band, footer label or pane, is told once per version to run claude update when it names its version, as 2.1.240 does.
Above the prompt	Whenever something needs action (a pin not installed, problems rness validate would report): what, until it is fixed.
In the prompt footer	rness · web · 1 in progress, dim, among the session modes (focus), with ⚠ 1 at the end when something needs action.
Before an edit	Refused when it would change what rness sync generates: the block of an AGENTS.md or CLAUDE.md (the agent is told which standard to edit instead) or a file of .claude/skills/rness/. Refused too when it would add a problem to a document of .rness/.
After an edit in .rness/	The problems of that document's front matter go back to the model, which fixes them in the same turn.
On demand	The rness MCP server lets the model find what applies and where a subject was decided.
/rness:*	The commands below.
With Agent Pulse	The board shows what the agent works on, and follows its status changes.

The session reads .rness/ next to the repository without asking for permission.

The /rness:* commands

Command	Does
/rness:status [tab]	Where every decision, specification and plan stands.
/rness:adr [create <subject> | open NNNN]	Records a decision as an ADR, or reopens one.
/rness:spec [create <subject> | open NNNN]	Writes a specification, or reopens one.
/rness:plan from <spec>	Approves a specification and turns it into a plan.
/rness:plan create [subject]	Writes a plan from the conversation, for work too small for a specification.
/rness:plan open NNNN	Reopens a plan.
/rness:plan check NNNN	Runs the proofs of a plan: each task's command, now. All pass: the plan Completed, its specification Implemented, the documents the work made inaccurate fixed. One fails: nothing moves.

The first word is the verb; a bare number (/rness:spec 0028) reopens; anything else is the subject of a create.

The last four are procedures the agent follows in your conversation, not file generators:

you   : SQLite or Postgres for the local cache?
agent : … discussion … → SQLite
you   : /rness:adr
agent : ADR 0010 "The local cache is SQLite", repo app?
you   : yes
agent : writes adr/0010-local-cache-sqlite.md (Proposed) and shows it

• After a discussion, /rness:adr writes the decision from it. Otherwise it asks, one question at a time.
• The agent may offer one of them on its own, for example an ADR when a choice would be hard to reverse. It writes nothing without your yes, except /rness:plan check on a plan whose last task has just passed.
• A new document takes its collection's first status and the next number, allocated by rness doc new so that two sessions never pick the same one. The agent moves a status as the work goes, and whenever you ask: a plan In progress as it starts its tasks, Completed once its proofs pass, a specification Implemented with its last plan. Accepting an ADR stays yours; /rness:plan from NNNN is how you approve a specification.
• Each command records its session and the model it ran as in the document's sessions:, for example { id: 1e9cb41b-…, agent: Claude Opus 5.5 }. claude --resume <id> reopens that session on the machine it ran on.
• The rules they follow are your workspace's, in .rness/CONVENTIONS.md.
• Each command ends in a commit of the files the agent alone changed, added by name. A file you or someone else changed too stays uncommitted, and the agent names it. Nothing is pushed.

/rness:status opens a pane beside the conversation: a tab per collection, a line per document with its status in the colour Agent Pulse gives it, no model turn. It takes the keyboard as it opens: ↑/↓ select a line, Tab and Shift+Tab change the tab (a tab's digit too), Enter or a click on a line shows the document in the pane, q brings the list back; Esc and q close it. When the workspace has a pulse, Agent Pulse is a link: the board from the list, the document's item from the document. The band above the prompt, the footer's label and the pane are drawn by a Claude Code mod that comes with the commands. A Claude Code without mods ignores it (2.1.280 and later draw it; 2.1.240 ignores it), and in claude -p the command prints tables. There, for the full-screen view, run it in the same terminal: Ctrl+Z, then npx @rness/cli status, q, then fg. Or run it in another terminal, from the workspace's .rness/:

npm

npx rness status

pnpm

pnpm rness status

yarn

yarn rness status

bun

bunx rness status

The MCP server

Each developer approves the rness server once, in Claude Code's own dialog. It is read-only and local:

Tool	Returns
rness_context	What applies to the current repository: standards, decisions, specifications, plans
rness_list	Every document of a collection, optionally of one status
rness_read	One file of .rness/
rness_search	The documents that match a query, with the matching lines

Other agents can run the same server with rness mcp; Rness writes no configuration for them.

What Rness writes, exactly

• .claude/settings.json in each repository: ../../.rness in permissions.additionalDirectories, and four hooks (session start, before an edit, after an edit, session end). Each hook runs the Rness version pinned in .rness/. The hooks read .rness/, write nothing and install nothing. They reach the network only for Agent Pulse.
• .mcp.json in each repository: the rness server.
• .claude/skills/rness/ in each repository: the /rness:* commands, and the mod (hooks/, types/) that draws the band, the footer's label and the pane. It runs the Rness version pinned in .rness/, like the hooks.
• The same settings and commands at the workspace root, for sessions started there, on your machine only.

Rness adds what is missing and leaves your own settings, hooks and servers as they are. A file that is not valid JSON is reported, never rewritten. The files under .claude/skills/rness/ are Rness's own: an edit by hand is reported by rness sync --check, then written back by rness sync. Removing claude from agents leaves these files in place, and sync says where they are.

Review changes to these files

Claude Code runs hooks from a committed settings file without asking each developer, and would run a changed rness server once approved. Review a change to .claude/settings.json or .mcp.json as you review code. Rness does not pre-approve its MCP server, for that reason.

Other agents

Codex, Cursor and GitHub Copilot read the AGENTS.md block; Rness writes nothing else for them. rness sync --agent accepts claude only.