rashomon

Your coding agent writes its own account of what it did. rashomon writes a second one, independently of the agent's narration, and puts the two side by side.

For Claude Code only, on macOS and Linux. Alpha: v0.1.0-alpha.1.

In plain words

When Claude Code finishes a task, it tells you what it did: "Done, all tests pass." That summary comes from the agent itself.

rashomon keeps its own record of every step the agent takes, like each command it runs and each file it edits, and whether each one worked. It puts that record beside the agent's summary: if a step failed and the closing message uses none of rashomon's failure words, it tells you at the end of the turn. Every report also lists what subagents did, which the main conversation does not show.

You keep working the way you do now. rashomon stays quiet unless something is worth a look. The name comes from Rashomon, the film in which witnesses give different accounts of the same event.

Get started

Pick one of these two ways. Using both records everything twice.

As a Claude Code plugin:

claude plugin marketplace add altrace-dev-role/rashomon
claude plugin install rashomon@rashomon
claude plugin enable rashomon@rashomon

Then start a new Claude Code session. Inside it, /rashomon:report shows what was recorded.

From the command line (macOS and Linux):

curl -fsSL https://raw.githubusercontent.com/altrace-dev-role/rashomon/main/install.sh | sh
rashomon watch

Then use claude as usual, and run rashomon report whenever you want to look. The installer puts rashomon in ~/.local/bin; if your shell cannot find it, add that folder to your PATH.

What you'll see

Most of the time, nothing: a turn with nothing worth a look prints nothing. When something is off, one line appears at the end of the turn (or, if you refused a permission prompt, when you send your next prompt, marked previous turn):

※ rashomon: 1 recorded failure.
            → rashomon report --session <id>

With the plugin, the arrow points at /rashomon:report --session <id> instead. That command shows the whole story. Here is an example.

What a disagreement looks like

Here the tests failed while a helper agent (a subagent) looked through the code, yet the agent's closing message says the tests pass. The session is built by test/acceptance/readme_test.go, which feeds hook payloads through the real recorder, and that test fails if this excerpt and the render ever differ. This excerpt is rashomon report exactly as it renders that session:

  the agent's account:
    "Done. I refactored ParseConfig and all tests pass."
  subagents: 1
    agent-a41f (Explore): 3 declarations, 3 executions, 1 Bash
    (these calls do not appear in the main transcript)
  failed calls: 1
    the final message contains none of these 43 words: fail, failed, failing, error, errors, couldn't, could not, unable, not able, didn't, did not, blocked and 31 more of 43 (--json lists them all)

The first line quotes the agent. The rest comes from rashomon's own record, checked against those words: one call failed (its record holds exit code 1, and --chain shows which call it was), and the subagent's three calls are recorded under the subagent's own transcript, not the main one. The report lists the failure words the summary does not use; it does not guess why.

Try it yourself

You can produce the same kind of report in a few minutes:

1. Install rashomon (see Get started).
2. In a project you have open, break one test on purpose.
3. Start claude. Ask it to have a subagent look through the code, then to run the tests and finish with a one-line summary.
4. Run rashomon report (or /rashomon:report inside Claude Code).

The report quotes the summary above the subagents and failed calls lines. Whether the failure is flagged depends on what the agent writes. If the summary contains none of rashomon's 43 failure words (matched as substrings, so "debug" counts as "bug"), the failed calls line lists them. Most honest summaries contain one, and then the report says so instead.

What a report tells you

• What subagents did: the helper agents Claude starts on its own, whose steps the main conversation never shows.
• Which steps failed, and whether the agent's closing summary uses any of rashomon's failure words. It lists the ones that are absent; it never guesses at intent.
• What ran differently from what was asked, for example another hook that rewrote a command's input before it ran.
• What rashomon could not see, on every report, even a healthy one.

Common questions

Does it see my code or my prompts? It sees them in passing and keeps none of them. Claude Code hands every hook the tool call's full input (for Write and Edit, that includes the file's text) and hands the next-prompt hook your prompt; rashomon reads what it needs and discards the rest. It stores no prompts, responses, file contents or tool output. A command is reduced to its program name, an argument count and a keyed digest, by a parser that names nothing when it is unsure. The one thing it keeps from inside a command is any hostname the command names (and the host of a WebFetch URL), stored in clear so the report can list it. The working directory and transcript path are stored too; see What is recorded. When you run rashomon report, it quotes the agent's final message from Claude Code's own transcript; that quote is never stored.

Does it send anything anywhere? It has no account, no telemetry and no network code of its own, and what it records is kept in a folder on your machine. No rashomon package imports a networking package, and CI checks that on every pull request, every push to main and every release tag. On Linux, CI also runs the declaration hook with the network switched off; the other hooks, the report and the end-of-turn line have no such runtime test yet.

Can it break my agent? No. It never stops a command, and if something inside it goes wrong, it exits quietly so Claude Code carries on.

Does it work with Cursor or Codex? No. This release supports Claude Code only. Cursor (by default) and Codex (after /import) read Claude Code's settings, so they can trigger the recorder anyway, and what it records for them can be wrong. If you use Cursor, see Scope for the setting to turn off.

Is it a sandbox or a security tool? No. It does not stop or contain the agent, and it cannot stop a determined agent from changing its records. It is a second, independent account of what happened, to set beside the agent's own.

Can I see network activity? rashomon itself observes no network traffic in this alpha: the report says destinations: not observed in this alpha, and --chain lists only the hosts each command named. If you run Claude Code inside the nono sandbox, rashomon report --nono-audit <path to nono's audit-events.ndjson> adds what nono allowed and refused in that session's window. This is experimental, and nono writes that file when its session ends. See Inside a sandbox first.

How do I turn it off? Plugin: open /plugin in Claude Code and turn it off. Command line: rashomon detach. Your records stay in ~/.local/state/rashomon (by default) until you delete that folder.

Is it finished? No. This is an alpha: Windows is not supported yet, and network destinations are not observed in this release.

The details

Everything below is the precise version: what gets installed, what is stored, and what the report can and cannot see.

Install options, in detail

As a Claude Code plugin (macOS and Linux):

claude plugin marketplace add altrace-dev-role/rashomon
claude plugin install rashomon@rashomon
claude plugin enable rashomon@rashomon

Installing does not start recording; enabling does. Start a new Claude Code session after enabling. /plugin shows it and turns it off again, and /rashomon:status / /rashomon:report work inside Claude Code. The plugin installs the release's rashomon-plugin.zip, which carries a prebuilt recorder per platform, because a plugin cannot compile Go at install time. So it needs a tagged release to exist. To try the plugin from a checkout instead:

scripts/build-plugin.sh
claude --plugin-dir ./plugin --settings '{"enabledPlugins": {"rashomon@inline": true}}'

The plugin ships disabled, and a plugin loaded with --plugin-dir (Claude Code names it rashomon@inline) is enabled only through settings. Without the --settings flag the session loads the plugin and records nothing.

If you already ran watch, run rashomon detach first. With both installed, every call is recorded twice, and the report marks the session duplicate_declarations. rashomon status names the overlap for a plugin installed from the marketplace; it cannot see one loaded with --plugin-dir.

As a settings install (Windows is not usable yet; see Status). From a release, on macOS or Linux:

curl -fsSL https://raw.githubusercontent.com/altrace-dev-role/rashomon/main/install.sh | sh

It downloads the release archive for your platform, checks it against the release's checksums.txt, refuses to install on a mismatch, and puts one binary in ~/.local/bin (set RASHOMON_INSTALL_DIR to change that). Or with Go:

go install github.com/altrace-dev-role/rashomon/cmd/rashomon@latest

This writes to $GOBIN, or $(go env GOPATH)/bin when GOBIN is unset; make sure that folder is on your PATH. A binary built this way, or from a clone, reports its version as dev: only release builds carry the version number. Or clone and build:

git clone https://github.com/altrace-dev-role/rashomon
cd rashomon && go build ./cmd/rashomon

Install to a location that will not move. watch writes the running binary's absolute path into your Claude Code settings, and Claude Code executes that path on every tool call. If you built inside a clone you later delete, every tool call fires a hook that cannot start. Build into a directory you keep (or go install it), and re-run watch after any move. watch records the path with symlinks resolved, so a stable symlink that points into a clone still breaks when the clone goes. (watch refuses a binary whose path runs through a go-build directory, which is where go run builds it.)

Why a broken hook matters more than usual: a PreToolUse hook that exits non-zero in the wrong way can block the tool call, and the user sees Claude Code failing rather than this program. Every recoverable failure here is engineered to exit 0 for that reason (a Go runtime fatal error cannot be caught, so those are prevented structurally instead, for example by capping how much input a hook reads); see docs/design-notes.md.

What watch sets up

rashomon watch                      # install the recorders (the only command that installs anything)
claude                              # work normally
rashomon report                     # read the sessions back

watch adds eight entries to your Claude Code settings: PreToolUse, PostToolUse, PostToolUseFailure, SessionStart, SessionEnd, Stop, StopFailure, UserPromptSubmit. The first three match * (every tool); the rest carry no matcher, so they fire on every occurrence of their event. All eight run a 5-second timeout except the three recap entries, which get 10: finding a turn's boundaries means reading a whole run, not one call. rashomon detach removes them again and leaves every other entry's value byte-for-byte as found. The top-level keys and the hooks block are re-written with two-space indentation, so a file kept in another layout comes back with mixed indentation.

Stop and StopFailure drive an exception-only recap: after a turn, it prints at most one line, and only when there is something worth looking at (a recorded failure that the agent's final message does not acknowledge, meaning it uses none of the failure words; a declaration without recorded execution; coverage that did not verify; or a truncated/unknown projection). One known gap: Claude Code discards what a StopFailure hook prints, so a turn that ends in an API error shows no line, and in this release the next prompt does not show it either. The line points to rashomon report --session <id> for the detail. A clean turn prints nothing at all; rashomon status says whether a turn has actually been evaluated, so silence never gets read as proof the turn was clean.

Saying No at a permission prompt interrupts the turn, and Claude Code fires no Stop after an interrupt. UserPromptSubmit catches that case: when you send your next prompt it checks the turn that just ended, and if no recap reached it and it has something to show, prints the line then, marked previous turn. The catch-up has no final message to check, so it can show every finding except an unacknowledged failure.

What is recorded, and what never is

Recorded: identifiers, shapes and hostnames. tool_use_id, session_id, prompt_id, agent_id, agent_type, transcript_path, cwd, permission_mode, tool_name; the call's program, verb_class, argument count, and a keyed digest (HMAC) of its full input: the whole command line for Bash, the whole tool input for other tools; how it ended (outcome, exit_code, is_interrupt, duration_ms); and a file_label classifying the path named by a Read, Edit, Write or NotebookEdit call into categories such as ssh-key, env-file, cloud-config, credential-shaped or certificate (paths touched from Bash are not labelled).

Note that cwd and transcript_path are filesystem paths and carry directory names. docs/store-schema.json is the field list for the record files; a record carries no key the schema does not declare (the one open object is rule_match).

Hostnames are stored in clear, because the report has to name them: report --chain lists the hosts each call named beside that call, and a digest cannot be rendered back into a name. They are extracted from WebFetch.url, from any http(s), ws(s), ssh://, git+ssh:// or git@host: address in a Bash command line, and from the destination arguments of ssh, scp, sftp and rsync, whether or not the call reached it. Only those two tools are read.

Never recorded: prompts, responses, argument values (other than those hostnames), file contents, tool output. Not redacted: structurally absent from the store. The recorder's payload types declare no field for tool output, so it is never decoded into a value and no record has a field that could hold it. The raw hook input is read into memory before decoding, and a failed call's error message, which can quote command output, is decoded and reduced to an exit code; nothing else of it is kept. Commands are reduced to a program name and an argument count, by a parser that names nothing when it is unsure. It can still misread a rare shape; how it decides is described in #29. A misread can store a fragment of a command, so report one privately (see Contributing).

Those rules govern the store. The report additionally reads Claude Code's own transcript at render time: it quotes the agent's final message, and checks tool results for the message Claude Code writes when you refuse a call. That is content: none of it is written to the store or transmitted, and --redact drops the quote entirely rather than partially cleaning prose that may name anything.

The digest is an HMAC under a random per-install key kept in the store (install.key). The same command digests differently on two machines, so digests cannot be matched against a dictionary built elsewhere. Anyone holding the store holds the key, though, and can test guessed commands against it. Store directory 0700, files 0600.

Where the store lives, and how to remove it

$RASHOMON_HOME, else $XDG_STATE_HOME/rashomon, else ~/.local/state/rashomon. RASHOMON_STORE_CAP_BYTES (default 512 MiB) is a soft limit: at session start and end, the least recently written runs are evicted, each leaving a gap record so the deletion is visible. The session whose start or end triggered the pass, and any run written in the last hour, are never evicted, so the store can run past the cap for a while. Another session left open but idle for more than an hour is not protected. detach removes the hooks, not the records. To remove everything, delete that directory.

Redaction, and what it does not hide

report --redact digests hostnames under this install's key. It is for sharing a report, and its limits are real: the digest is 32 bits, so two hosts can collide; the last label is kept in clear on purpose, so .internal and .com survive (x.s3.amazonaws.com keeps only .com), and an IPv4 address keeps its last octet; and anyone holding this install's store can recompute every digest. The text report repeats all of this in its own header; --json --redact marks only "redacted": true.

forget --host <h> removes every call that named that host from this store, and leaves a gap record saying something was removed. Pass the host exactly as the report prints it (lower-case, no scheme or port): in this release any other form matches nothing and reports forgot 0 records. That record is keyed by a digest of the host, not its name.

What it cannot see

Network destinations are not observed in this alpha. The text report says so in one line:

destinations: not observed in this alpha

It is printed for every session, including a completely healthy one, because it is a property of the instrument and not of the session. A reader told only what was observed will read the rest as an absence of traffic rather than an absence of observation. --json states the same fact in its own form: the destinations object carries "observed": false and the reason no_proxy_store, so its empty host lists read as not watched, not as none. --chain lists the hosts each call named; it does not say whether the call reached them.

Inside a sandbox

If Claude Code runs inside a sandbox that limits where it can write, the sandbox must allow rashomon's store directory, or nothing is recorded and nothing says so. With nono, create the directory first, then grant it: mkdir -p ~/.local/state/rashomon, and add --allow ~/.local/state/rashomon to nono run. Running Claude Code under nono has not been tested end to end in this release.

The two rules it will not break

Never print "nothing happened" where the truth is "not watching." Every count that could not be measured renders as unknown, never as zero. A run that could not measure itself does not get to report a number. One known exception in this release: executed differently from declared prints 0 even when no declared and executed pair could be compared.

Never print "not watching" where the truth is "nothing happened." Every degradation line has a healthy twin, so a clean run and a blind run do not read the same.

One consequence worth expecting: coverage reads verified only when the probe can find the recorder's entry, either in the settings file Claude Code itself resolves (a watch install) or as the enabled plugin. A session started with claude --settings <other file> records perfectly well and still reports hook_entry_absent: the probe under-claims rather than confirming an entry it cannot read.

The reasoning behind all of this, and the acceptance criteria that hold it, is in docs/design-notes.md.

Commands

rashomon --help lists the commands above and their main flags. It does not list detach --force, the override a refused detach names in its error message. The commands in the table do not take --help in this release: rashomon watch --help runs watch, and rashomon pause --help pauses recording.

detach has two recovery forms for when things are gone: detach --install <id> (printed by watch at install time) removes one install's entries without opening a store, and detach --all removes every entry carrying a rashomon marker, for when the store is gone and the id with it. Both refuse, naming the field, if an entry of ours had its matcher, hook count, hook type or timeout edited by hand.

Editor integration

This repository installs nothing in your sessions. There is no committed .claude/settings.json; opening this checkout runs nothing. The recorder runs only once you run watch or enable the plugin.

Slash commands ship as assets you copy from a clone of this repository (go install leaves none), deliberately not under .claude/ here. A skill in this repository would load only for someone who has this repository open, which is the one place it is least useful:

mkdir -p "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills" && cp -r skills/rashomon* "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills/"   # every project
mkdir -p /path/to/project/.claude/skills && cp -r skills/rashomon* /path/to/project/.claude/skills/                            # one project

scripts/claude-rashomon starts a recorded session in one word once it is on your PATH. It runs watch, which installs user-wide hooks that keep recording every later session, in every project, until detach. scripts/rashomon-sessionstart.sh is an optional SessionStart hook that puts one line of recorder state into a session's context; its header shows the entry to add. It reads only a settings install, so with the plugin it wrongly reports the session as not recorded.

Scope and threat model

Claude Code only. The hooks, the store and the report describe Claude Code sessions. Other tools that read ~/.claude/settings.json can trigger the recorder anyway: Cursor by default, and Codex after /import. This release does not support them, and what gets recorded for them can be wrong. If you use Cursor with rashomon installed, turn off Include Third-Party Plugins, Skills, and Other Configs (Cursor Settings, Agents, Third-Party Imports).

rashomon installs no certificate and decrypts nothing.

No account. No telemetry. No phone-home. No model in any path.

What it defends against, stated plainly: this release defends against the agent's narration: a summary that omits, compresses or misremembers. It does not defend against an agent that tampers. The store, the digest key and forget are all reachable by any shell command the agent makes. Treat the record as an honest second account, not as tamper-proof evidence.

A declaration is not an execution. PreToolUse fires before the permission prompt resolves, so the store holds records for calls you went on to deny. That is deliberate (intent is worth keeping whether or not it was granted). Each declaration carries the session's permission_mode (for example default or acceptEdits). That is the mode, not the answer you gave the prompt, so it cannot by itself separate what ran from what you refused.

Building from source

go build ./cmd/rashomon
go test ./...

Status

Alpha: v0.1.0-alpha.1. No signed binaries, no Homebrew formula. macOS and Linux are the supported targets.

Windows is not usable yet. The release publishes Windows binaries, but no install path has been shown to work there. watch quotes the installed command line for a POSIX shell, and scripts/claude-rashomon.ps1 runs the same watch. CI cross-builds and vets the Windows code; no test runs on Windows.

Contributing

Issues and pull requests are welcome. main is protected: changes land through a pull request with CI green. Security issues should go through private vulnerability reporting rather than a public issue; see SECURITY.md.

License

Apache 2.0. See LICENSE.

Built by Altrace.