Skip to content
AraneaDevPublic

About

Reports what a Claude Code session actually changed, and separates the changes you were asked about from the ones applied without asking.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Minos

A session changed 47 files. You saw six of them. Minos separates the changes you were asked about from the ones that were not.

Release Tool page License Language Last commit Conventional Commits Status Tests


Minos (Μίνως) is the king whose palace is the labyrinth at Knossos, and one of the three judges of the dead. The court he sits in weighs what a life actually did rather than what it says it did. This tool weighs something smaller: what an agent session actually changed in your repository, and which of it was ever put in front of you.

A Claude Code session with the Minos pane docked beside it: the chat on the left shows the prompts and the edits as they happen, and the pane on the right, headed by the project, its branch and its commit, counts six changes applied without asking, two inside a subagent and three that did not survive, lists the two files and the five prompts that changed something, and shows every change to src/checkout.ts as a diff

Type /minos in Claude Code and a pane opens beside the chat. It shows what this session changed while the session runs: which changes were put to you as a decision, which were applied without asking, which happened inside a subagent whose diff never reached your terminal, and which did not survive. Press a file to see its changes as diffs, or a prompt to see what it changed.

TL;DR: Minos reconstructs what an agent session changed and whether Claude Code would have shown each change for a decision. It reads Claude Code transcripts, classifies Edit, Write, and NotebookEdit operations by permission mode and subagent context, and tracks changes that did not survive to the final working tree. It shows that live in a pane, gives the agent the same ledger as a tool, and answers for any past session from the command line.

Nothing is captured while you work: the live view's hooks read only the transcript Claude Code already writes. Because that transcript is all Minos reads, it can also answer for sessions that happened before you installed it, for as long as Claude Code still keeps their transcripts.

Status: pre-release. Minos is not yet published to npm, so it installs from the Aranea marketplace or from this repository: see Install.


Install

In Claude Code, as a plugin, which is where /minos and /minos:report come from:

Install from the Aranea marketplace:

claude plugin marketplace add https://github.com/AraneaDev/aranea-marketplace
claude plugin install minos@aranea

On the command line, from this repository, since Minos is not on npm yet:

bun install -g github:AraneaDev/minos
minos report

Nothing has to be installed before the session you want to read. Minos runs against the transcript store as it stands, so it answers for sessions that happened weeks earlier.

Minos needs Bun 1.1.0 or newer, and a Claude Code transcript store at ~/.claude/projects, or wherever CLAUDE_CONFIG_DIR points. The pane and the agent's tool need Claude Code 2.1.309 or newer.

Live in a session

  • /minos opens the pane. Its header names the project, its branch and its commit. A band of tiles counts the decided, auto, subagent and undone changes. Under it are the files changed without you being asked, the prompts that changed something, the changes that did not survive, and this repository's earlier sessions. It refreshes after each change and at the end of each turn while it is open.
  • The lists of files and prompts grow to fill the pane. A longer list scrolls with the mouse wheel over it, or opens in full with show all.
  • Press a file and the pane shows each of its changes as a diff, drawn by Claude Code's own diff view, with the time, the class and the prompt behind it. Press a prompt to see the files it changed, or an earlier session to see its ledger.
  • The agent gets a minos_ledger tool with the same ledger as text. Its description asks the agent to call it before saying the work is done, and before writing a commit message or a PR description, so a summary cannot leave out what a subagent changed.
  • When an Edit or Write undoes a change the session made earlier, the agent reads one line about it with that tool's result, and you get the same line as a toast and in the pane. Nothing is ever blocked. The check covers Edit and Write, not NotebookEdit, and it gives up after 1.5 seconds, so on a transcript of hundreds of megabytes the line can be missing.

The pane, the tool and the undo line all ask the CLI and show what it prints, so they use the same counts and wording as minos report. The pane can trail the transcript by a second or so after a change. They need Claude Code 2.1.309 or newer, which runs a plugin's hooks module. On an older version the CLI and /minos:report work as before.

After the fact

/minos:report, or minos report on the command line, prints the whole account of a session, including one that ended weeks ago:

The minos report for a staged demo session: 2 files and 8 changes, none of them decided, 6 applied without asking and 2 inside a subagent, and 3 changes that did not survive the session

Minos reporting on a staged demo session. Times are in the timezone Minos runs in rather than the transcript's UTC, and a +1d marks a time that falls on the calendar day after the session began.

What it will not tell you

Minos reports whether Claude Code put a change to you as a decision. It does not report whether you read it, it cannot know that, and nothing on your machine records it. A change you approved in half a second is still counted as one you were asked about.

It is no softer on itself. A decided label is read off the permission mode alone, never off a recorded approval, so a standing allow rule can mean a default turn put nothing on screen at all. The report says so under its own figures, and names the allow rules it found in force at the moment you ran it.

That line matters more than any feature below it. A tool that implies it knows what your eyes did is worth less than one that says plainly where its knowledge stops.

The three classes

Class What it means
decided The prompt this change descends from was submitted in default or plan mode, so Claude Code would have stopped and asked. Read off the mode, never off an approval
auto Submitted under acceptEdits, bypassPermissions or auto, the mode most real changes run under. A mode this build does not recognise, or one the transcript never recorded, is counted here too, rather than guessed in your favour
subagent Applied inside a subagent. No diff reached your terminal in any form

subagent wins over the other two, because even in default mode a subagent's edits are not rendered to you. Every view counts the classes in changes: one Edit, Write or NotebookEdit call each, counted once by its tool_use id. Each change has exactly one class, so the three counts add up to the total, and report, sessions, sessions --all, export and ledger give the same numbers for the same sessions. Where a view counts files, the column or line says files.

What Minos can see at all is what the transcript holds, which is the Edit, Write and NotebookEdit tools. A file rewritten by a shell command, by MultiEdit or by an MCP server of your own leaves nothing to read and appears in none of the counts.

The changes that did not survive

Three shapes, reported by name rather than merged into one count:

  • overwritten: content an earlier operation introduced is gone after a later one
  • reverted: a later edit is the exact inverse of the earlier one, putting back the text it had replaced
  • discarded: a later whole-file Write no longer carries what an earlier operation introduced

Each one names both times, and the prompt on either side wherever the transcript allows it, because what you want to read is that what you asked for in prompt 4 did not survive prompt 9. A change that cannot be traced back to a prompt is marked (unattributed) rather than guessed at, and subagent operations often are.

Detection follows the lines each change added through every later change to the same file. A change did not survive when more than half of the lines it added are gone, which catches an agent taking a change back with a small edit, and does not count a file rewritten with most of its lines kept. Lines of only braces and punctuation are not counted. It works on the text of the changes themselves, so read it as a strong indication rather than a proof: a file whose final state cannot be reconstructed can produce a finding that does not hold, and text that turns up again elsewhere in a file can hide one that does.

minos file src/report.ts: six changes that did not survive, above the 23 operations that touched the file, every one of them inside a subagent

minos file puts one file's whole history in that session in front of you. Every operation on src/report.ts ran inside a subagent, so none of its 23 changes was ever rendered.

Commands

minos report        the default; the latest session for this directory
minos file <path>   one file's operation history in that session
minos undone        the changes that did not survive, on their own
minos sessions      sessions with headline counts, to pick one
minos sessions --all
                    every project under ~/.claude/projects, with totals
minos export        the ledger as data, JSON
minos export --all  every project's counts as data, JSON
minos ledger        the session's ledger in short, as text or (--json) data
minos undoes        which earlier changes one Edit or Write ends, read as JSON on stdin

report, file, undone, export, ledger and undoes each take --session <id> and --project <path>. sessions takes --project and --limit <n>. sessions and export also take --since YYYY-MM-DD and --until YYYY-MM-DD, which bound the listing to local calendar days, both inclusive. Any other command rejects them. --all takes the same two flags, and also --exclude <glob>, which you can repeat, and --include-temp.

The report is coloured when stdout is a terminal, on the same scheme the cards above use: one colour per class, one for the undone kinds, and grey for the caveats. A pipe, a redirect, minos export and any environment with NO_COLOR set get plain text, so what a script reads is what the tool means.

minos sessions: two sessions of this repository with their decided, auto, subagent and undone changes, their total, and auto broken down by permission mode

minos sessions gives you the headline counts per session, so you can pick the one you mean before asking for the full report. It prints a units line and a header first, and every count is changes. Each session shows its first and last local time. Under the rows come a total and the auto changes per permission mode. The total counts each change once, so a change that a resumed or forked session copied from its parent counts in both rows but once in the total, and a line says how many there were. When the listing reads every transcript of the project, that total is the project's row in sessions --all. When --limit leaves older transcripts unread, the total does not cover them, so the two can differ, and a line says how many were left unread. If the project moved on disk, the first line reads recorded under N paths: followed by the paths, and the sessions under all of them are listed together. A project is found when any of its transcripts records the directory, so a moved repository is not reported as having no transcript.

Across every project

minos sessions --all and minos export --all cover every project under ~/.claude/projects. They count changes the same way, so a forked or resumed session does not count the same call twice.

  • Left out by default: a project whose every recorded directory is under the temp directory (the system one, and /tmp), since that is where test runs and agent scratchpads live. --include-temp lists them. --exclude <glob> leaves out a project whose every recorded directory matches the glob. A line counts the projects skipped either way.
  • Rows: a long project path is cut in the middle, so the row keeps both where it lives and which checkout it is. A project with no session in the window gets no row; one line under the table counts those projects instead. With no window, that line counts the projects that had no session with a known time.
  • Lines under the table: auto per recorded permission mode, how many duplicates were dropped, and a history line with the oldest and newest transcript and the project directories that have no transcripts left.
  • Pruning: Claude Code prunes old transcripts (cleanupPeriodDays), so --all only covers what has not been pruned yet, and the totals will shrink as that happens.
  • Failed calls: an Edit or Write whose tool call failed or was refused wrote nothing, so it is left out of every count, here and in the single-session views, and a line says how many.
  • Shell writes: a separate line counts shell commands that look like file writes. A command is left out of it only when it never ran: a permission denial, a PreToolUse hook block, a classifier refusal or missing verdict, or a user rejection. A command that ran and exited non-zero (Exit code N) stays in, since it may have written before it failed. It is a loose heuristic, and those commands are never counted in the classes.

What it does not do

  • It does not review the code it reports on. Momus, Chaos and Knossos do that.
  • It does not touch git. Nothing is staged, nothing is committed, nothing is reverted.
  • It writes nothing under ~/.claude and nothing in your working tree. It reads the transcripts, and the allow rules in your settings.json so it can name the ones that let a default turn apply a change without showing it, and nothing else.
  • It makes no network request, runs no daemon, and sends no telemetry.

Why it exists

Every other tool in this collection checks an artefact that was already there. Knossos maps the architecture, Chaos attacks the test suite, Momus reads what the assertions actually assert, Argos draws a line around the database. None of them measures the session's own output, which is both the least reviewed artefact in the workflow and the one the agent produces.

Git does not close that gap. It shows you the final state of the tree and nothing about how it got there: not which changes you were asked about, not which arrived unannounced, and not the work that was done and then undone before you ever saw it.

Development

bun install
bun run check      # lint, lint:docs, typecheck, knip, then the full suite with coverage
bun run fp         # the attribution harness: plants a known answer, asserts Minos finds it
bun run test:mod   # the live view's own tests, under claude plugin test
bun run scripts/session-svg.ts <transcript> <session> <project> docs/images/session.svg <file>
                   # redraws the README's session image from a real session

License

MIT.


Built by Tim Schipper and released as open source under aranea.dev.

About

Reports what a Claude Code session actually changed, and separates the changes you were asked about from the ones applied without asking.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages