# Using Spaccato

Written for the coding agent that sets Spaccato up and works with it afterwards, Claude Code or another; the person it works with hears their part from the agent. A card is made in two ways: from the terminal, for the change in the repository on the person's machine, with the conversation that led to it; or on a pull request, through the GitHub App. The command installs with `curl -fsSL https://spaccato.dev/install.sh | sh`; an agent that arrived with only the address, because someone said they want to use Spaccato, starts at Who does what, which has the steps around it. The working rules alone, as a skill a coding agent can install, are at `https://spaccato.dev/skill.md`. Updated 2026-11-08.

## What Spaccato is

Spaccato explains a coding agent's change to the people who have to live with it, non-coders first, as a one-page card: a headline, a verdict, and the things that need a look. There are two ways to get one. From the terminal, `spaccato`, run in the repository, reads what changed in the working tree and the conversation that led to it, and a few minutes later prints a brief for you to read and relay, and the card's address for the person; no pull request is needed. On a pull request, someone comments `@spaccato`, and the comment Spaccato keeps on that pull request holds the headline, the verdict and the link.

The card says what was asked and what was done, and lists every statement in the description the code does not bear out. It shows what people will see differently, in the product's own words. It shows what the AI inside the product is told, when a change touches that. It puts what cannot be undone first: a migration that drops data, a message or a payment that goes out, a script that rewrites records. It is not code review, it does not run the code, and it does not decide what merges.

## When it earns its cost

- Before you say a piece of work is done, and before merging what a coding agent built: did it do what was asked, and what else did it do. The card's Asked vs done block answers both from the code, not from the agent's own account of its work.
- When a change touches live things: posts that publish, emails that send, rows a script rewrites, money that moves. Those come first on the card, marked as what cannot be undone.
- When a change touches the instructions an AI in the product reads, or the tools it may call. The card shows the lines that changed and an example of what the AI now reads.
- When someone who does not read code has to understand the change: a partner, a client, an assistant. The card is written for that reader, in the words they use for the product.

## Who does what

Spaccato is by invitation, and two steps need a browser and the person's own GitHub account; the agent opens the address and says what to do, it cannot do them itself. Everything in the terminal and inside the repository is the agent's. Signing in accepts the Terms of Service (https://spaccato.dev/terms) and the Privacy Policy (https://spaccato.dev/privacy); point the person at both before they do.

1. **The person:** have an invitation. Spaccato is by invitation: the person who pointed you here adds your GitHub login. Without it, signing in ends on a page that says so. Done when signing in at https://spaccato.dev shows the dashboard.
2. **The agent:** install the command. `curl -fsSL https://spaccato.dev/install.sh | sh` puts it in `~/.spaccato/bin` and adds that directory to the PATH line of the shell's startup file; in the shell you are in, call it by its path, `~/.spaccato/bin/spaccato`, or export the PATH first. It needs Node.js 20 or newer; the script says so when Node is missing, and installing Node first is yours to do. Installing sends nothing anywhere.
3. **The agent, then the person:** connect the machine. `spaccato login` opens an approval page in the browser; the person, signed in, clicks Connect, and the terminal receives a token for their account, kept in `~/.spaccato/config.json`. Done when `spaccato whoami` names them.
4. **The agent:** `spaccato setup` writes the `/spaccato` skill for Claude Code (and for Codex when it is installed) into the person's home, so every session knows the command, and prints the lines for `~/.claude/settings.json`: the permission rule that lets Claude Code's auto mode run the command, and the optional gate (From the terminal). Then make the first card for the work at hand and report it. Done when it prints a brief and the card's address and the person has heard what it found; when Claude Code blocks the command instead, From the terminal says what to offer the person.
5. **The person, for pull requests:** install the App on the repository. On the dashboard, Install on GitHub opens `https://github.com/apps/spaccato/installations/new`; pick the repositories. Done when the repository is listed on the dashboard. Then **the agent** adds the working rules to the repository: save `https://spaccato.dev/skill.md` as `.claude/skills/spaccato/SKILL.md`, so they load in every session, and add the paragraph at the end of this text to `CLAUDE.md`.
6. **The person, for pull requests:** decide who pays. A pull request card costs about half a dollar on the default model, charged to an OpenRouter account. In Settings, under Who pays for runs, Connect OpenRouter, unless the person who invited you covers your account. Done when the dashboard no longer shows the turn-on step.
7. **The person, optional:** in Settings, under Who reads these reports, say in your own words who reads the cards and what they call the product's people and things. Every card is written for that reader.

## From the terminal

Run, from the repository's root, when you have finished a piece of work or the person asks what changed:

```
spaccato --format agent
```

It reads what changed: on a branch, everything since it left the main line, commits and uncommitted work alike; on the main line, the uncommitted work (`--base <ref>` for another starting point). New files count too; stage or commit nothing for it, the command reads the working tree as it is and changes nothing in the repository. It reads this session's transcript for the person's prompts and your replies since that point, and nothing else: no tool output, no thinking (`--since 2h` to read more of the conversation, `--transcript <file>` to name a session when it finds none). Obvious secrets are taken out. It sends the diff, the repository's text files the model may read, and that conversation to the person's own Spaccato account, where a separate model writes the card; that takes three or four minutes, and the command waits. `--share` adds a share link anyone can open. The card is the person's: on their dashboard under From your terminal, and at the address the command prints. When the working tree is as it was at the last card, the command says nothing has changed.

The first run in Claude Code's auto mode is often blocked, with no reason given: the command sends the repository and the conversation off the machine, which is what the classifier is there to catch. Do not work around it. Tell the person what it sends and where, and give them the choice: approve the run, under /permissions in Recently blocked, or in a message that names what it sends and to whom, and you run the command again; run it themselves by typing `! spaccato` in the prompt box, after which the card is theirs and you wait; or add a standing rule so no later card asks, `"Bash(spaccato *)"` under `permissions.allow` in `~/.claude/settings.json`, which `spaccato setup` prints. `--no-transcript` sends the code alone; the card then cannot check what you said against what changed. In the session that installed the command, call it by its path, `~/.spaccato/bin/spaccato`; from the next session on it is on the PATH and the rule covers it.

The brief it prints is for you to read and relay. It reads, in this order:

- `Spaccato read the change "<title>" and the conversation. Verdict: <label>.` with the reason, then `Headline for the person: ` and one line.
- `Claims the code does not bear out (the card can be wrong: check each against the code before you repeat it):` and one `- [status] "<quote>" — <note>` per claim, the status `differs`, `missing` or `partly`.
- `Needs a look (check each against the code too):` and one `- [kind] <what> — <why>` per item, worst first, with `(try: …)` when there is something to check by hand.
- `Done without being asked:` and one `- "<quote>" — <note>` per thing the code does that nobody asked for.
- `Unsettled:` and what is unsettled, or `Nothing unsettled.`; then `Card for the person:` and the address, and last the line that says what the brief is for: `This brief is for the person: tell them what the card found and where you disagree, with the headline and the card's address, then wait. Change nothing because of it until they ask.`

Read it with a careful eye: the card is a model's reading of the code and it is sometimes wrong, so check each claim and each item under Needs a look against the code before you repeat it. Then tell the person what the card found, what you agree with and what you think it got wrong and why, with the headline and the card's address, in their words, and wait. Change nothing because of a card until they ask, and do not retell the card. When the person ran the command themselves, its output is theirs: say the card is ready, in one line, and wait.

The gate, optional: in Claude Code, a Stop hook that runs `spaccato hook stop` makes a card every time you say you are done and blocks the stop while the brief has an `Unsettled:` line. It is the one place you act on a card on your own: settle what the brief lists, or tell the person why it stands, then stop again. `spaccato setup` prints the lines for `~/.claude/settings.json`. It costs a card per stop and it lets you change code unasked, so the person decides.

`spaccato update` brings the command to the published build, and a run says so, once a day, when a newer one exists. `spaccato whoami` names the connected account, `spaccato logout` forgets the token.

## Working rules for the agent

- **A card before you say you are done.** From the terminal, `spaccato --format agent`, and report the brief (From the terminal). On a pull request, a comment with `@spaccato`, and the comment reported before anyone merges. Both read the same code. The card is the person's; the brief and the comment are yours to read with care and relay, not to act on.
- **A branch and a pull request for every change that goes live.** Nothing goes straight to main. The person needs the card before the change is live, and a pull request card needs the pull request to read.
- **A description Spaccato can check.** Say what was asked, in the person's words; what you did; what you did not do or left for later; and what to check by hand. From the terminal, your replies in the conversation are that description, so say it in them. Spaccato checks every statement against the code and lists the ones the code does not bear out, and what the code does that nobody asked for. So claim nothing the change itself does not show: a script you ran, data you migrated, a test you did not add. Name the files that matter. Say when something is a spike.
- **Ask for the card on a pull request.** Once the pull request is open and pushed, post a comment that contains `@spaccato`; the mention alone is enough, and `@spaccato help` answers with what it understands. It needs write access to the repository, which you have when you act as the person. Spaccato keeps one comment on the pull request and edits it as it works. A new commit does not re-run it: comment `@spaccato` again after a change worth reading again.
- **Read the verdict before anyone merges.** It is one of three, on the comment and in the brief. Routine: tell the person, and merge when they say so. Needs a careful look: tell the person each line under Needs a look and whether you agree with it; fix what they choose, in a new commit, or write under the comment why it stands as it is. Needs fixing first: do not merge; bring it to the person, and fix what they choose.
- **Keep the person in the loop.** Put the headline, the verdict, the Needs a look lines and where you disagree with them into your reply, with the link, in their words. The card page asks for a GitHub sign-in with access to the repository; a share link opens without one.

## The comment, for a program reading it

On a pull request, the comment is written by `spaccato[bot]`, so `gh pr view <number> --comments` or `gh api repos/{owner}/{repo}/issues/<number>/comments` finds it. When the card is done it reads, in this order:

- `### ` and the headline, one line.
- The verdict in bold: `**Routine**`, `**Needs a careful look**` or `**Needs fixing first**`.
- One or two sentences on what the change touches.
- Counts, each a bold number and a few words, separated by middle dots.
- `**Needs a look**` and a numbered list, worst first; `And N more in the report.` when the list was cut.
- `## [Open the visual explanation →](url)` and a line with the files, lines and commits.

While Spaccato works, the comment shows the step and a Follow the run live link. When it fails, it starts `**Run failed.**` with the reason, and a new mention retries.

## What it reads, what it costs

On a pull request: its title and description, its commits, the diff and the changed files at the head commit, other files and a search over the repository when the analysis asks for them, and the CI status. From the terminal: the diff between the base and the working tree, the repository's text files trimmed to fit, and the conversation's prompts and replies with obvious secrets taken out, never tool output; files that hold secrets by name are never sent. Files coding agents read, CLAUDE.md, AGENTS.md, rules, skills and .mcp.json among them, are recognised by name, and a GLOSSARY.md at the repository's root gives the card the product's words. It skips lockfiles, vendored and generated code and binaries. It never sees the terminal itself or the running product.

A card costs about half a dollar on the default model, Claude Sonnet 5.5 through OpenRouter, more for a large change, plus under a cent for the plain-language pass. A pull request card is charged to the OpenRouter account that pays for the installation; a card from the terminal is on Spaccato while the beta lasts. A re-run costs the same again. A card takes three or four minutes.

## What not to do

- Do not post the card's contents or a share link anywhere public. The card quotes the code.
- Do not re-run to get a better verdict. The card reads the same code; change the code or the description instead.
- Do not take Routine, or a brief or comment that has not arrived, as approval. The person decides what merges.
- Do not write the description for the card. Write it for the person; the card checks it either way.
- Do not act on a card unasked. Report it and wait; the person decides what to fix and what merges. The gate they set up themselves is the one exception.
- Do not take the card as right either. It is a model's reading of the code and it is sometimes wrong: check each line against the code before you repeat it, and say where it is wrong.
- Do not work around a permission prompt or a block. The command sends the repository and the conversation off the machine, which Claude Code may ask the person about or stop; that is their question to answer, and From the terminal says what to offer them.

## A paragraph for CLAUDE.md

```
## Spaccato

This repository uses Spaccato (https://spaccato.dev/llms.txt). Before you say a piece of work is done, run `spaccato --format agent` from the repository's root and report the brief it prints: check each line against the code, since the card can be wrong, tell the person what it found and where you disagree, with the headline and the card's address, and wait. Change nothing because of a card until they ask. Every change goes on a branch and into a pull request, never straight to main, with a description that says what was asked, what was done, what was left out and what to check by hand, and claims nothing the pull request itself does not show. Once the pull request is open, comment `@spaccato` on it, report every line under "Needs a look" to the person before asking to merge, and comment `@spaccato` again after a change worth reading again.
```