Shared decisions in Claude Code
The quickstart connects Claude Code to Retiform so your agent can read your documents and memory. The Retiform plugin goes one step further for a code repository: every Claude Code session started in it begins by recalling the decisions your team has recorded about it, and records new ones as they are made.
Before you start
- A Retiform tenant you can sign in to, from the quickstart's step 1.
- Claude Code.
- Node.js 22 or later, for the
kgcommand that links the repository. - A Git repository. The link is one small file at its root, which you commit.
1. Install the plugin
In Claude Code, run:
/plugin marketplace add retiform-ai/claude-plugins
/plugin install retiform@retiform
Then restart Claude Code.
The plugin adds Retiform as an MCP server, at the address your console's Connect your agent panel shows.
Run /mcp, choose the
plugin's retiform server and authenticate. The browser steps are the quickstart's step 2: sign in with the
code Retiform emails you, approve the agent in Retiform's console, and confirm. If you already added Retiform
with claude mcp add at the same address, Claude Code connects to it once.
You should see the plugin's server connected in /mcp.
2. Link the repository
Start Claude Code in the repository. Its first line says the repository is not linked yet. Ask:
Link this repository to Retiform.
The agent runs the plugin's link skill. It lists your tenant's Projects and tells you which command to run in a terminal, at the repository:
- To link an existing Project:
npx @retiform-ai/kg link --project <id> - To create one:
npx @retiform-ai/kg link --name "<name>"
The first run of kg shows an address and a code. Open the address, check that it shows the same code, and
sign in as in step 1. kg then says which tenant and account it links for, and writes
.retiform/project.json. Tell the agent when it is done: it checks the file and that it can see the Project.
Commit .retiform/project.json. It holds only the Project's identifier: no key, address or tenant data.
Teammates who install the plugin then start with the same Project's decisions.
If this differs: if the agent says it cannot see the Project, kg and Claude Code are signed in to
different accounts. Check the account kg named, and the tenant on the approval page you saw in step 1.
3. Work as usual
Each session started in the linked repository shows one line, "Retiform: linked to Project …", and the agent recalls the Project's current decisions, and the tenant's, before it acts on your first request. It weighs each one as a claim, with its writer and date.
When you or the agent decide something during a session, such as a choice between alternatives, a constraint you found or a convention you agreed, the agent records it in Retiform, citing what it rests on. When a decision changes, it supersedes the old entry, which keeps its history. You can review and correct every entry on the console's Memory page.
A long session's context is compacted from time to time. Right after, the agent records a hand-off of the work done and the work left, replacing its earlier one, and recalls what other sessions decided since the day before.
Three more skills are there when you want them:
| Ask the agent to | Skill |
|---|---|
| List what this session recorded | retiform:decisions |
| Import the repository's instruction files and decision records as a first set of decisions, recording only those you accept | retiform:import |
| Link the repository again, or to another Project | retiform:link |
Several sessions at once
Sessions that share one approval of the plugin write as one agent. To tell them apart on the Memory page,
set a label before starting Claude Code: RETIFORM_SESSION_LABEL=worktree-2 claude, or in PowerShell
$env:RETIFORM_SESSION_LABEL = 'worktree-2'. A label is 1 to 40 letters, digits and . _ : -. Retiform shows it
as declared by the session, never as verified, and nothing depends on it.
If it does not work
| What you see | What to check |
|---|---|
| The session's first line says the link is not valid | .retiform/project.json was edited by hand. Delete it and link again |
| The agent says it cannot reach Retiform | Run /mcp and authenticate the plugin's retiform server again |
| The agent recalls nothing, though the console lists decisions | They may be about another Project. Check the Project on the entries in the console |
kg link says the name is in use |
A Project with that name exists: link it with --project and its identifier |