From b16f1361a0c65854aaa90468f0ef969cb2c856f7 Mon Sep 17 00:00:00 2001 From: AraneaDev <12177132+AraneaDev@users.noreply.github.com> Date: Sat, 24 Oct 2026 19:58:40 +0200 Subject: [PATCH] docs(readme): redraw the session image and reorganise the readme The session image showed the pane before its header, rule and fitted lists. session-svg.ts now lays the pane out as the mod does: the project, branch and commit in the header, and the lists grown into the pane's rows. The readme had drifted: the image's alt text gave file counts where the pane counts changes, the live section did not mention the header or the scrolling lists, and the tests badge said 412. It is also reordered. Status sits with the introduction, Install comes right after it with the requirements folded in, then what Minos does, how it classifies, and the commands. The long sessions --all paragraph is a subsection with a list. No section was reworded beyond these fixes. --- README.md | 153 +++++++++++++++++++++------------------- docs/images/session.svg | 99 +++++++++++++------------- scripts/session-svg.ts | 17 ++++- 3 files changed, 141 insertions(+), 128 deletions(-) diff --git a/README.md b/README.md index 966b798..f9fcd32 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ [![Last commit](https://img.shields.io/github/last-commit/AraneaDev/minos?label=last%20commit)](https://github.com/AraneaDev/minos/commits/main) [![Conventional Commits](https://img.shields.io/badge/commits-conventional-fe5196?logo=conventionalcommits&logoColor=white)](https://www.conventionalcommits.org/) [![Status](https://img.shields.io/badge/status-pre--release-orange)](#status) -[![Tests](https://img.shields.io/badge/tests-412%20passing-brightgreen)](#development) +[![Tests](https://img.shields.io/badge/tests-431%20passing-brightgreen)](#development) @@ -24,9 +24,10 @@ > 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 counts one file changed under auto, -one inside a subagent and three changes that did not survive, lists the five prompts that changed -something, and shows every change to src/checkout.ts as a diff](docs/images/session.svg) +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](docs/images/session.svg) 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 @@ -43,12 +44,49 @@ Nothing is captured while you work: the live view's hooks read only the transcri 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). + +--- + +## Install + +In Claude Code, as a plugin, which is where `/minos` and `/minos:report` come from: + + +Install from the Aranea marketplace: + +```sh +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: + +```bash +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](https://bun.sh/) 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. 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. +- `/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. @@ -60,8 +98,8 @@ happened before you installed it, for as long as Claude Code still keeps their t 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. -All three ask the CLI and show what it prints, so the pane and the tool use the same counts and -wording as `minos report`. The pane can trail the transcript by a second or so after a change. +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. @@ -78,15 +116,6 @@ Minos reporting on a staged demo session. Times are in the timezone Minos runs i the transcript's UTC, and a `+1d` marks a time that falls on the calendar day after the session began. - - -> **Status:** pre-release. Minos is **not yet published to npm**, so it installs from this -> repository or from the aranea marketplace: see [Install](#install). It requires -> [Bun](https://bun.sh/) 1.1 or newer and a Claude Code transcript store at -> `~/.claude/projects`. - ---- - ## What it will not tell you Minos reports whether Claude Code **put a change to you as a decision**. It does not report @@ -101,17 +130,6 @@ 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. -## 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. - ## The three classes | Class | What it means | @@ -200,27 +218,31 @@ project moved on disk, the first line reads `recorded under N paths:` followed b 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. -A project whose every recorded directory is under the temp directory (the system one, and `/tmp`) -is left out by default, since that is where test runs and agent scratchpads live, and a line counts -the projects skipped. `--include-temp` lists them. `--exclude ` leaves out a project whose -every recorded directory matches the glob, and a line counts those too. A long project path is cut -in the middle, so the row keeps both where it lives and which checkout it is. Auto is broken down -per recorded permission mode, and a line says how many duplicates were dropped. A history line gives -the oldest and newest transcript, and the project directories that have no transcripts left. Claude -Code prunes old transcripts (`cleanupPeriodDays`), so `--all` only covers what has not been pruned -yet, and the totals will shrink as that happens. A project with no session in the window gets no -row, and 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. 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. 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. - -In Claude Code, `/minos:report` prints the report for the session you are in. + +- **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 ` 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 @@ -231,33 +253,16 @@ In Claude Code, `/minos:report` prints the report for the session you are in. apply a change without showing it, and nothing else. - It makes no network request, runs no daemon, and sends no telemetry. -## Install - -In Claude Code, as a plugin, which is where `/minos` and `/minos:report` come from: - - -Install from the Aranea marketplace: - -```sh -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: - -```bash -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. +## Why it exists -## Requirements +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. -Bun 1.1.0 or newer, and a Claude Code transcript store at `~/.claude/projects`, or wherever -`CLAUDE_CONFIG_DIR` points. +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 diff --git a/docs/images/session.svg b/docs/images/session.svg index 195460d..6702147 100644 --- a/docs/images/session.svg +++ b/docs/images/session.svg @@ -37,58 +37,55 @@ ⏺ I've undone the receipt change. The `sendReceipt` call and its import are gone, and `console.log(\`charging ${email} ${amount}\`)` is back at `src/checkout.ts:8`, exactly as it was. I read the file back to confirm. - ± Minos session d150c973 · since 2026-10-23 22:50 - - ╭──────────────────────────────────────────────────────────────────────────────╮ - │ 0 │ 1 │ 1 │ 3 │ - │ decided · files │ auto · files │ subagent · files │ undone · changes │ - ╰──────────────────────────────────────────────────────────────────────────────╯ - - ── ≡ Changed without asking ───────────── 2 files · press one for its history ── - ● src/checkout.ts auto · 6 changes - ● src/cart.ts subagent · 2 changes - - ── › By prompt ──────── 5 prompts changed something · press one for its files ── - prompt 5 Undo the receipt change in src/checkout.ts: put… 1 file · 2 changes - prompt 4 On second thought, the email check is too strict… 1 file · 1 change - prompt 3 Send the receipt from src/checkout.t… 1 file · 2 changes · 2 undone - prompt 2 Use a subagent (the Agent tool) to add discount… 1 file · 2 changes - prompt 1 Validate the email in src/checkout.ts… 1 file · 1 change · 1 undone - - ── ◇ Edits ──────────────────────────────────────────────────────── 6 changes ── - × close - 22:50 edit · auto · prompt 1 - - - export function checkout(items: Item[], email: string) { - - + const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/ - - + - - + export function checkout(items: Item[], email: string) { - - + if (!EMAIL.test(email.trim())) { - - + throw new Error(`Invalid email address: "${email}"`) - - + } - const amount = total(items) - 22:51 edit · auto · prompt 3 - const amount = total(items) - - - console.log(`charging ${email} ${amount}`) + + minos-demo master · 29e325f + + ──────────────────────────────────────────────────────────────────────────────── + + ╭──────────────────────────────────────────────────────────────────────────────╮ + │ 0 │ 6 │ 2 │ 3 │ + │ decided · chang… │ auto · changes │ subagent · chan… │ undone · changes │ + ╰──────────────────────────────────────────────────────────────────────────────╯ + + ── ≡ Changed without asking ───────────── 2 files · press one for its history ── + + ● src/checkout.ts auto · 6 changes + ● src/cart.ts subagent · 2 changes + + ── › By prompt ──────── 5 prompts changed something · press one for its files ── + + prompt 5 Undo the receipt change in src/checkout.ts: put… 1 file · 2 changes + prompt 4 On second thought, the email check is too strict… 1 file · 1 change + prompt 3 Send the receipt from src/checkout.t… 1 file · 2 changes · 2 undone + prompt 2 Use a subagent (the Agent tool) to add discount… 1 file · 2 changes + prompt 1 Validate the email in src/checkout.ts… 1 file · 1 change · 1 undone + + ── ◇ Edits ──────────────────────────────────────────────────────── 6 changes ── + + × close + 22:50 edit · auto · prompt 1 + + - export function checkout(items: Item[], email: string) { + + + const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/ + + + + + + export function checkout(items: Item[], email: string) { + + + if (!EMAIL.test(email.trim())) { - + sendReceipt(email, amount) - return { ok: true, amount } - 22:51 edit · auto · prompt 3 - import { total, type Item } from './cart' - - + import { sendReceipt } from './mailer' - 22:51 edit · auto · prompt 4 - - - const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/ - - - + + throw new Error(`Invalid email address: "${email}"`) + + + } + const amount = total(items) + 22:51 edit · auto · prompt 3 + const amount = total(items) + + - console.log(`charging ${email} ${amount}`) + + + sendReceipt(email, amount) + return { ok: true, amount } > diff --git a/scripts/session-svg.ts b/scripts/session-svg.ts index 99f6aec..2b04e88 100644 --- a/scripts/session-svg.ts +++ b/scripts/session-svg.ts @@ -15,10 +15,10 @@ * * Usage: bun run scripts/session-svg.ts [file to open] */ -import { paneRows } from '../hooks/layout' +import { fitWindows, paneRows } from '../hooks/layout' import type { Segment } from '../hooks/layout' import { cells, fit } from '../hooks/text' -import type { MinosEdit, MinosHistory, MinosLedger, MinosSession } from '../types' +import type { MinosEdit, MinosHead, MinosHistory, MinosLedger, MinosSession } from '../types' const GROUND = '#10151d' const BODY = '#b8c0cb' @@ -36,6 +36,7 @@ const THEME: Record = { subtle: FRAME, claude: CLAUDE, inactive: DIM, + text: BONE, } const FONT_SIZE = 13 @@ -175,7 +176,17 @@ const codeLines = (source: string): Line[] => : { runs: [{ text: ` ${fit(l, PANE - 4)}` }] }, ) -const pane: Line[] = paneRows(ledger, [], history, PANE, sessions) +/** The header as the pane reads it: the project's name, and its branch and commit when git answers. */ +async function headOf(dir: string): Promise { + const run = Bun.spawn(['git', '-C', dir, 'rev-parse', 'HEAD', '--abbrev-ref', 'HEAD'], { stdout: 'pipe', stderr: 'ignore' }) + const [rev = '', branch = ''] = (await new Response(run.stdout).text()).trim().split('\n') + const git = (await run.exited) === 0 && rev !== '' ? { rev, branch: branch === 'HEAD' ? null : branch } : null + return { project: dir.split('/').filter((part) => part !== '').pop() ?? dir, git } +} +const where = await headOf(project) +// The lists grown into the pane's rows, as the mod sizes them for a pane BODY_ROWS tall. +const windows = fitWindows(BODY_ROWS, { files: 0, prompts: 0 }, ledger, [], history, PANE, sessions) +const pane: Line[] = paneRows(ledger, [], history, PANE, sessions, false, false, windows, where) .flatMap((r): Line[] => (r.code === undefined ? [{ runs: r.segments }] : codeLines(r.code.source))) .slice(0, BODY_ROWS)