superwiki 0.1.3 → 0.1.4

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "sw",
   "description": "An LLM-maintained wiki and task tracker in docs/ for coding agents. Obsidian friendly, with a static viewer.",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "license": "MIT",
   "keywords": [
     "wiki",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "sw",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "An LLM-maintained wiki and task tracker in docs/ for coding agents. Obsidian friendly, with a static viewer.",
   "license": "MIT",
   "skills": "./skills/",

package/README.md

@@ -17,9 +17,13 @@ Then, in a project: `/sw-init`.
 
 ## Why
 
-Superwiki follows the LLM Wiki pattern described by Andrej Karpathy: raw sources you curate, a wiki the agent owns, and a short schema that tells the agent how to maintain it. On top of that it adds what a software project needs: tasks with dependencies, plans, and a record of decisions and lessons.
+Superwiki follows the LLM Wiki pattern described by Andrej Karpathy: raw sources you curate, a wiki the agent owns, and a short schema that tells the agent how to maintain it. On top of that it adds what a software project needs: tasks with dependencies, plans, reviews, and a record of decisions and lessons.
 
-It is built to be cheap for the agent. One small index to read, one file per task, and a script that answers "what is ready?", "what blocks this?" or "is anything broken?" without the agent reading the vault.
+It is built to be cheap for the agent:
+
+- **Little to read.** One small index, one file per task, and a script that answers "what is ready?", "what blocks this?" or "is anything broken?" without the agent reading the vault.
+- **Work in clean contexts.** Planning, implementing and reviewing run in subagents, each on the model you choose for it. The main session only keeps the task's status true, so it stays small.
+- **Cost you can see.** `sw-stats` shows what a session used, per agent.
 
 Measured on a real project with 165 tasks, converted from a single markdown index:
 
@@ -29,7 +33,7 @@ Measured on a real project with 165 tasks, converted from a single markdown inde
 | Read to start one task | the index, then the task's section | one file, 2 KB at the median |
 | Marking a task done | a status cell, plus a ✅ at every reference to it (median 12 places) | one frontmatter line |
 
-> Status: early. The CLI, the viewer, `sw-init` and the migration script are tested, and the planning flow has been run in all three agents; some skills have only been exercised once. [DESIGN.md](DESIGN.md) lists what has and has not been proven.
+> Status: early. The CLI, the viewer, `sw-init` and the migration script are tested. Planning, implementing and reviewing have been run end to end on real projects in Claude Code, and the planning flow in Codex and Copilot CLI; some skills have only been exercised once. [DESIGN.md](DESIGN.md) lists what has and has not been proven.
 
 ## What you get
 
@@ -84,9 +88,13 @@ git clone https://github.com/mhmtsrfglu/superwiki ~/.superwiki
 
 A linked install follows the clone: `git pull` updates every agent. `install.sh --copy` copies instead, `--uninstall` removes.
 
-All three agents below were checked the same way: the agent found the skills, refused to start a task with an unfinished dependency, and ran `sw-plan` end to end with the planner subagent.
+### Per agent
+
+All three agents were checked the same way: the agent found the skills, refused to start a task with an unfinished dependency, and ran `sw-plan` end to end with the planner subagent.
 
-### Claude Code
+The model for each role (planning, implementing, reviewing) is set with `sw-config`, which writes one agent file per role into the project. The skills dispatch those agents by name.
+
+#### Claude Code
 
 ```bash
 npx superwiki install claude
@@ -94,11 +102,11 @@ npx superwiki install claude
 
 Invoke with a slash: `/sw-init`, `/sw-plan T-01`.
 
-Claude Code reads `~/.claude/skills/` (and a project's `.claude/skills/`); it does not read `~/.agents/skills/`, so `global` is not enough for it.
-
-`sw-plan` enters plan mode when the session offers it. A model set with `sw-config` for `claude` applies to the planner and implementer subagents, written to `.claude/agents/`; if those agents are not loaded, the skills fall back to built-in agents with the same model.
+- Claude Code reads `~/.claude/skills/` (and a project's `.claude/skills/`). It does not read `~/.agents/skills/`, so `global` is not enough for it.
+- `sw-plan` enters plan mode when the session offers it.
+- Agent files: `.claude/agents/sw-planner.md`, `sw-implementer.md` and `sw-reviewer.md`. They load when a session starts; in a session that began before they existed, the skills fall back to built-in agents with the same model.
 
-### Codex CLI
+#### Codex CLI
 
 ```bash
 npx superwiki install codex
@@ -106,9 +114,10 @@ npx superwiki install codex
 
 Invoke with a dollar sign, or by name in a sentence: `$sw-init`, `$sw-plan T-01`, "use the sw-plan skill for T-01". Checked with CLI 0.153.
 
-A skill cannot switch Codex into plan mode; start planning yourself with `/plan` if you want the mode, or let `sw-plan` proceed without it (it changes no file before you approve). A model set with `sw-config` for `codex` is written to `.codex/agents/sw-planner.toml` and `sw-implementer.toml`, and the skills spawn those agents by name. Subagents must be enabled (they are by default in current releases).
+- A skill cannot switch Codex into plan mode. Start planning yourself with `/plan` if you want the mode, or let `sw-plan` proceed without it: it changes no file before you approve.
+- Agent files: `.codex/agents/sw-planner.toml`, `sw-implementer.toml` and `sw-reviewer.toml`. Subagents must be enabled; they are by default in current releases.
 
-### GitHub Copilot CLI
+#### GitHub Copilot CLI
 
 ```bash
 npx superwiki install copilot
@@ -116,11 +125,11 @@ npx superwiki install copilot
 
 Invoke with a slash, or by name in a sentence: `/sw-init`, "use the sw-plan skill for T-01". Checked with CLI 1.0.31.
 
-Copilot CLI also reads `~/.agents/skills/`, so if you installed `codex` or `global` it already has the skills.
+- Copilot CLI also reads `~/.agents/skills/`, so if you installed `codex` or `global` it already has the skills.
+- A skill cannot switch Copilot into plan mode. Start with `copilot --mode plan` or `/plan` if you want it.
+- Agent files: `.github/agents/sw-planner.agent.md`, `sw-implementer.agent.md` and `sw-reviewer.agent.md`, dispatched with the `task` tool. Whether Copilot honours the `model:` field of those files has not been checked.
 
-A skill cannot switch Copilot into plan mode; start with `copilot --mode plan` or `/plan` if you want it. A model set with `sw-config` for `copilot` is written to `.github/agents/sw-planner.agent.md` and `sw-implementer.agent.md`; the skills dispatch them with the `task` tool. Whether Copilot honours the `model:` field of those files has not been checked.
-
-### Other agents
+#### Other agents
 
 ```bash
 npx superwiki install global
@@ -128,8 +137,9 @@ npx superwiki install global
 
 Agents that load `SKILL.md` folders from `~/.agents/skills` pick the skills up from there. For an agent with its own skills folder (Cursor, Gemini CLI, OpenCode and others), copy the `skills/sw-*` folders from a clone into it by hand. Nothing has been run in these agents. What will differ:
 
-- the skills name Claude Code, Codex and Copilot tools when they dispatch subagents; elsewhere they fall back to doing the planning or implementing in the main session, and say so;
-- `sw-config` writes agent files only for `claude`, `codex` and `copilot`, so a per-role model cannot be set.
+- the skills name Claude Code, Codex and Copilot tools when they dispatch subagents; elsewhere they fall back to doing the work in the main session, and say so;
+- `sw-config` writes agent files only for `claude`, `codex` and `copilot`, so a per-role model cannot be set;
+- `sw-stats` reads the session records of those three tools only.
 
 Everything else (the vault, the CLI, the viewer, ingest, lint, explain, triage) depends only on Node and on the agent following the skill text.
 
@@ -156,7 +166,7 @@ A project's `docs/` folder is plain markdown and keeps working as an Obsidian va
 | Skill | What it does |
 | --- | --- |
 | `sw-init` | set up `docs/` in the current project, or upgrade it |
-| `sw-migrate` | convert an existing table-based task index, on a new git branch |
+| `sw-migrate` | convert an existing table-based task index, on a git branch of its own |
 | `sw-ingest` | file a source into the wiki |
 | `sw-plan` | plan a task with the planner subagent and get your approval |
 | `sw-implement` | run a task with the implementer subagent, have it reviewed if the task asks for that, and record the result |
@@ -164,6 +174,7 @@ A project's `docs/` folder is plain markdown and keeps working as an Obsidian va
 | `sw-triage` | for a problem: seen before? lessons, likely causes |
 | `sw-lint` | structural checks by script, semantic review on request |
 | `sw-visualize` | open the viewer |
+| `sw-stats` | what the current session has cost: tokens, context, steps and tool calls, per agent |
 | `sw-config` | the model each tool uses for planning, implementing and reviewing; task areas |
 
 ### Examples
@@ -191,6 +202,7 @@ Shown as typed in Claude Code. In Codex, write `$sw-plan` instead of `/sw-plan`.
 /sw-config plan with opus, implement with sonnet, review with opus
 /sw-lint                          check links, frontmatter and task dependencies
 /sw-visualize                     open the task board and the wiki in the browser
+/sw-stats                         what this session has cost so far, per agent
 ```
 
 You do not have to type a command. The rules `sw-init` adds to `AGENTS.md` tell the agent which skill fits, so a plain request should reach the same skill:
@@ -204,6 +216,22 @@ Users get the magic-link email twice. Have we seen this before?
 
 A filled-in example vault is in [examples/demo/docs](examples/demo/docs).
 
+### What a session cost
+
+`sw-stats` reads the record your agent keeps of the session and prints one row for the main session and one for each subagent. It writes nothing. `sw-implement` ends its report with the same table. This one is a real task: planned, implemented and reviewed in 37 minutes.
+
+```text
+session  claude  fe4cbd6c-8abf-4db6-9755-469dc7321dc7  2026-10-05 10:27 to 11:04, 37 min
+agent           model              steps  first  peak   sent  cached  output  tools  min
+main            claude-opus-5-5       27    79k  126k   2.8M     96%     18k     23   37
+sw-planner      claude-opus-5-5       31    59k  154k   3.5M     96%      8k     32    6
+sw-implementer  claude-sonnet-5-5     68    59k  252k  12.2M     96%     16k     76   26
+sw-reviewer     claude-opus-5-5       23    60k  137k   2.4M     89%     372     24   12
+total                                149      -     -  20.9M     95%     43k    155
+```
+
+`first` and `peak` are the tokens sent with one request. `sent` is that, summed over every step: each step sends the whole context again, which is why a long session in one context is expensive. In Copilot CLI the token columns fill in once the session has closed.
+
 ### The CLI
 
 The skills call a small script that answers questions without the agent reading the vault. You can run it yourself, from the project root:
@@ -211,11 +239,12 @@ The skills call a small script that answers questions without the agent reading
 ```bash
 node docs/.sw/sw.mjs status                 # counts per area
 node docs/.sw/sw.mjs ready                  # tasks that can start now
-node docs/.sw/sw.mjs check P-15             # can it start or finish, and what is open
+node docs/.sw/sw.mjs check P-15             # can it start or finish, what is open, is a review required
 node docs/.sw/sw.mjs explain P-15           # dependencies, what it unblocks, plan, area guide
 node docs/.sw/sw.mjs search sync timeout    # where something is mentioned
 node docs/.sw/sw.mjs next-id P              # next free id in an area
 node docs/.sw/sw.mjs lint                   # broken links, bad frontmatter, dependency errors
+node docs/.sw/sw.mjs stats                  # tokens, context and steps of the agent session here
 node docs/.sw/sw.mjs serve --open           # the viewer, reading files live
 node docs/.sw/sw.mjs snapshot               # or: freeze the vault into docs/viewer.html, no server
 ```
@@ -223,14 +252,23 @@ node docs/.sw/sw.mjs snapshot               # or: freeze the vault into docs/vie
 ## Develop
 
 ```bash
-npm test       # builds skills/sw-init/assets/sw.mjs, then runs the tests
+npm test       # builds skills/sw-init/assets/sw.mjs and viewer.html, then runs the tests
 ```
 
-Releases are cut by the `Release` workflow (Actions → Release → Run workflow): it tests, bumps the version in `package.json` and the plugin manifests, publishes to npm, tags, and creates a GitHub release. It publishes through npm trusted publishing, so no token is stored: the package's settings on npmjs.com name this repository and `release.yml` as its trusted publisher.
+Edit sources in `src/`:
+
+| File | What it is |
+| --- | --- |
+| `src/core.js` | the vault model, derived task state, lint and search; shared by the CLI and the viewer |
+| `src/stats.js` | reads the agents' session records |
+| `src/cli.js` | the commands |
+| `src/viewer.html` | the viewer |
+
+`scripts/build.mjs` bundles them into `skills/sw-init/assets/sw.mjs` and `viewer.html`. Those two files are generated: do not edit them.
 
 `node scripts/build-demo.mjs` builds the public demo into `site/` (the viewer with the example vault baked in); the Pages workflow deploys it on every push to `main`.
 
-`src/core.js` is shared by the CLI and the viewer. Edit sources in `src/`; the files in `skills/sw-init/assets/` named `sw.mjs` and `viewer.html` are generated.
+Releases are cut by the `Release` workflow (Actions → Release → Run workflow): it tests, bumps the version in `package.json` and the plugin manifests, publishes to npm, tags, and creates a GitHub release. It publishes with the repository secret `NPM_TOKEN`, an npm access token allowed to publish `superwiki`.
 
 ## License
 

package/commands/stats.md

@@ -0,0 +1,5 @@
+---
+description: Show what this session has cost so far: tokens, context, steps and tool calls per agent
+---
+
+Use the sw-stats skill. User arguments: $ARGUMENTS

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superwiki",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Agent skills that turn docs/ into an LLM-maintained wiki and task tracker. Obsidian-friendly. Works with Claude Code, Codex and Copilot CLI.",
   "keywords": [
     "claude-code",

package/skills/sw-implement/SKILL.md

@@ -7,7 +7,7 @@ description: Use when the user wants to implement, build, execute, start or cont
 
 Runs one task. You keep the task's status true and judge the result. The work is done by subagents that start from a clean context, on the models set in sw-config: an implementer, and a reviewer when the task asks for one. You do not read the code or the plan: their reports are your input.
 
-That split is what keeps a task cheap. A long session re-sends its whole context on every step; work done in a fresh context does not carry yours, and yours stays small because the work never enters it.
+That split is what keeps a task cheap. A long session sends its whole context again on every step; work done in a fresh context does not carry yours, and yours stays small because the work never enters it.
 
 Run commands from the project root. `<skill-dir>` is the directory this SKILL.md is in.
 
@@ -15,12 +15,16 @@ Run commands from the project root. `<skill-dir>` is the directory this SKILL.md
 
 1. **Pick the task.** Id given: use it. Otherwise `node docs/.sw/sw.mjs ready` and let the user choose; tasks already in progress come first.
 2. **Gate**: `node docs/.sw/sw.mjs check <ID>`.
-   - `can start: no  open deps: ...`: stop. Tell the user which tasks block it and offer to run the first blocker instead; do not run it unasked. Do not start the task anyway, and do not edit `deps` to get past this.
-   - `can start: n/a, status is in-progress`: this is a continuation; skip step 3.
-   - `can start: n/a, status is done` or `cancelled`: stop and ask what the user wants.
-   - `plan: ... (draft, not approved)`: stop; the plan needs the user's approval (sw-plan).
-   - `plan: none`: fine for a small task (one area, three "Done when" items or fewer, nothing open in its notes, a few files). For anything larger, recommend sw-plan first and let the user choose.
-   - `review: required (...)`: remember it for step 7.
+
+   | `check` says | Do |
+   | --- | --- |
+   | `can start: no  open deps: ...` | stop. Tell the user which tasks block it and offer to run the first blocker instead; do not run it unasked. Do not start the task anyway, and do not edit `deps` to get past this |
+   | `can start: n/a, status is in-progress` | this is a continuation; skip step 3 |
+   | `can start: n/a, status is done` or `cancelled` | stop and ask what the user wants |
+   | `plan: ... (draft, not approved)` | stop; the plan needs the user's approval (sw-plan) |
+   | `plan: none` | fine for a small task: one area, three "Done when" items or fewer, nothing open in its notes, a few files. For anything larger, recommend sw-plan first and let the user choose |
+   | `review: required (...)` | remember it for step 7 |
+
 3. **Mark it started** before any work: in the frontmatter of `docs/tasks/<ID>.md` set `status: in-progress` and `started:` today. Append `## [date] task | <ID> started` to `docs/log.md`, in the layout its last entries use.
 4. **Checks that need the environment.** If the task has a plan, look for `needs:` in it: `grep -n 'needs:' docs/plans/<ID>-plan.md`. Each hit is a check that starts services or changes data. Ask the user which of them may run; without a yes, none.
 5. **Dispatch the implementer** (how: "Dispatching" below). Its prompt is the task id, the project root if it is not your working directory, and which `needs:` checks it may run. Do not paste the plan into the prompt; it reads the files.
@@ -43,8 +47,18 @@ Run commands from the project root. `<skill-dir>` is the directory this SKILL.md
 9. **Keep the area guide, if the area has one.** `node docs/.sw/sw.mjs explain <ID>` prints `area guide:` with a path or `none`.
    - A guide exists: add the reports' `Guide:` lines to it, one line per fact under Layout, Patterns, Verify or Gotchas. Replace a line the new fact corrects, and keep the page under 60 lines.
    - No guide: do nothing. A guide is worth starting once several tasks in an area have needed the same facts; if the user asks for one, create `docs/wiki/guide-<area, lowercase>.md` from `docs/.sw/templates/guide.md` and list it in `index.md`.
-10. **File what else was learned.** If a report held a decision or constraint the wiki should keep, offer to save it as a wiki page (`type: decision` or `concept`) and add it to `index.md`. If the task fixed a problem whose cause is now known, or the review caught a defect worth remembering, offer a `type: lesson` page (Symptom, Cause, Fix, How to notice it earlier); sw-triage finds these later. If a report named follow-up work, offer to create the tasks. These are separate offers: act on each only when the user says yes to that one.
-11. **Report** to the user: outcome, each requirement with its evidence, the review verdict and findings, anything that differs from the task, files changed, and which tasks this unblocked (`node docs/.sw/sw.mjs ready`). Commit only if the user asks. End with one line: the task is recorded, so the next task is cheapest in a new session.
+10. **File what else was learned.** These are separate offers: act on each only when the user says yes to that one.
+    - A report held a decision or constraint the wiki should keep: offer a wiki page (`type: decision` or `concept`), added to `index.md`.
+    - The task fixed a problem whose cause is now known, or the review caught a defect worth remembering: offer a `type: lesson` page (Symptom, Cause, Fix, How to notice it earlier); sw-triage finds these later.
+    - A report named follow-up work: offer to create the tasks.
+11. **Report** to the user, in this order. Commit only if the user asks.
+    - the outcome;
+    - each requirement with its evidence, and anything that differs from the task;
+    - the review verdict and its findings;
+    - the files changed;
+    - the tasks this unblocked (`node docs/.sw/sw.mjs ready`);
+    - what the task cost: run `node docs/.sw/sw.mjs stats` and show its table as printed;
+    - one last line: the task is recorded, so the next task is cheapest in a new session.
 
 ## Dispatching
 

package/skills/sw-init/assets/sw.mjs

@@ -1,5 +1,11 @@
 #!/usr/bin/env node
-// Generated by scripts/build.mjs from src/core.js and src/cli.js. Do not edit.
+// Generated by scripts/build.mjs from src/core.js, src/stats.js, src/cli.js. Do not edit.
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, join, resolve as resolvePath, sep } from 'node:path';
+import { spawn } from 'node:child_process';
+import { createServer } from 'node:http';
+import { fileURLToPath } from 'node:url';
 // Superwiki core: vault model, derived task state and lint. Pure: no fs, no DOM.
 // Runs in Node (docs/.sw/sw.mjs) and inlined in the viewer, so both report the same findings.
 
@@ -316,13 +322,368 @@ export function guideFor(vault, area) {
   return vault.pages.find(p => p.folder === 'wiki' && p.data.type === 'guide' && key(p.data.area ?? '') === key(area)) || null;
 }
 
+// Session statistics: what the agent session working in this project has cost so far.
+// Claude Code, Codex and Copilot CLI each keep a record of every session on disk. This finds the
+// record of the project's session and reduces it to one row per agent: the main session and each
+// subagent it started.
+
+export const STATS_TOOLS = ['claude', 'codex', 'copilot'];
+
+const MAIN = 'main';
+// Codex keeps every project's sessions in one tree; only the most recent files are opened.
+const CODEX_FILES_SCANNED = 100;
+
+// ---------- Reading records ----------
+
+// A record still being written can end in half a line; lines that do not parse are skipped.
+function jsonLines(path) {
+  const records = [];
+  for (const line of readFileSync(path, 'utf8').split('\n')) {
+    if (!line) continue;
+    try {
+      records.push(JSON.parse(line));
+    } catch {}
+  }
+  return records;
+}
+
+function jsonFile(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+const modifiedAt = path => statSync(path).mtimeMs;
+
+// The project root as typed and as resolved: tools record the working directory either way.
+function rootForms(root) {
+  const forms = new Set([root]);
+  try {
+    forms.add(realpathSync(root));
+  } catch {}
+  return [...forms];
+}
+
+const isWithin = (roots, dir) => Boolean(dir) && roots.some(root => dir === root || dir.startsWith(root + sep));
+
+// ---------- The summary being built ----------
+
+const newSession = (tool, id) => ({ tool, id, agents: [], tools: {}, note: '' });
+
+// Token fields stay null when the record does not hold them, so "unknown" never prints as 0.
+const newAgent = name => ({
+  name, model: '', steps: 0, first: null, peak: null, sent: null, cached: null, output: null, toolCalls: 0, start: null, end: null,
+});
+
+const plus = (sum, n) => (sum ?? 0) + (n || 0);
+
+// One model request. `context` is everything sent with it, `cached` the part read from the cache.
+function addStep(agent, { context, cached, output }) {
+  agent.steps++;
+  agent.first ??= context;
+  agent.peak = Math.max(agent.peak ?? 0, context);
+  agent.sent = plus(agent.sent, context);
+  agent.cached = plus(agent.cached, cached);
+  agent.output = plus(agent.output, output);
+}
+
+function addToolCall(session, agent, name) {
+  agent.toolCalls++;
+  session.tools[name] = (session.tools[name] || 0) + 1;
+}
+
+// Widens the agent's working period to include this record.
+function touch(agent, timestamp) {
+  const time = Date.parse(timestamp);
+  if (Number.isNaN(time)) return;
+  agent.start = Math.min(agent.start ?? time, time);
+  agent.end = Math.max(agent.end ?? time, time);
+}
+
+// Subagents are listed in the order they were started.
+const byStart = (a, b) => (a.start ?? 0) - (b.start ?? 0);
+
+// ---------- Claude Code ----------
+// ~/.claude/projects/<working directory, non-alphanumerics as dashes>/<session>.jsonl, and next to
+// it <session>/subagents/agent-<id>.jsonl with a .meta.json naming the agent type.
+
+const claudeHome = () => process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude');
+
+function claudeSessions(root) {
+  const sessions = [];
+  for (const form of rootForms(root)) {
+    const dir = join(claudeHome(), 'projects', form.replace(/[^A-Za-z0-9]/g, '-'));
+    if (!existsSync(dir)) continue;
+    for (const name of readdirSync(dir)) {
+      if (!name.endsWith('.jsonl')) continue;
+      const id = name.slice(0, -'.jsonl'.length);
+      const path = join(dir, name);
+      sessions.push({
+        tool: 'claude',
+        id,
+        modified: modifiedAt(path),
+        current: id === process.env.CLAUDE_CODE_SESSION_ID,
+        read: () => readClaude(id, path, join(dir, id, 'subagents')),
+      });
+    }
+  }
+  return sessions;
+}
+
+function readClaudeAgent(session, name, path) {
+  const agent = newAgent(name);
+  // A reply is written as one line per content block. Each line repeats the reply's usage, and
+  // only the last one has the final output count, so the last line of a reply is the one kept.
+  const replies = new Map();
+  for (const record of jsonLines(path)) {
+    touch(agent, record.timestamp);
+    const message = record.type === 'assistant' && record.message;
+    if (!message) continue;
+    for (const block of message.content || []) {
+      if (block.type === 'tool_use') addToolCall(session, agent, block.name);
+    }
+    if (message.usage) replies.set(message.id, message);
+  }
+  for (const { model, usage } of replies.values()) {
+    agent.model = model || agent.model;
+    const cached = usage.cache_read_input_tokens || 0;
+    addStep(agent, {
+      context: (usage.input_tokens || 0) + cached + (usage.cache_creation_input_tokens || 0),
+      cached,
+      output: usage.output_tokens,
+    });
+  }
+  return agent;
+}
+
+function readClaude(id, path, subagentDir) {
+  const session = newSession('claude', id);
+  session.agents.push(readClaudeAgent(session, MAIN, path));
+  if (!existsSync(subagentDir)) return session;
+  const subagents = readdirSync(subagentDir)
+    .filter(name => name.endsWith('.jsonl'))
+    .map(name => {
+      const meta = jsonFile(join(subagentDir, name.replace(/\.jsonl$/, '.meta.json')));
+      return readClaudeAgent(session, meta.agentType || 'subagent', join(subagentDir, name));
+    });
+  session.agents.push(...subagents.sort(byStart));
+  return session;
+}
+
+// ---------- Codex ----------
+// ~/.codex/sessions/<year>/<month>/<day>/rollout-*.jsonl. The first line is the session's meta:
+// its working directory and, for a subagent, the session that spawned it and its role.
+
+const codexHome = () => process.env.CODEX_HOME || join(homedir(), '.codex');
+
+function rolloutFiles(dir, found = []) {
+  if (!existsSync(dir)) return found;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) rolloutFiles(path, found);
+    else if (entry.name.endsWith('.jsonl')) found.push({ path, modified: modifiedAt(path) });
+  }
+  return found;
+}
+
+function codexSessions(root) {
+  const roots = rootForms(root);
+  const recent = rolloutFiles(join(codexHome(), 'sessions')).sort((a, b) => b.modified - a.modified).slice(0, CODEX_FILES_SCANNED);
+  const byId = new Map();
+  for (const { path, modified } of recent) {
+    const records = jsonLines(path);
+    const meta = records[0]?.type === 'session_meta' ? records[0].payload : null;
+    if (!meta || !isWithin(roots, meta.cwd)) continue;
+    const id = meta.session_id || meta.id;
+    if (!byId.has(id)) byId.set(id, { modified: 0, files: [] });
+    const group = byId.get(id);
+    group.modified = Math.max(group.modified, modified);
+    group.files.push({ meta, records });
+  }
+  return [...byId].map(([id, { modified, files }]) => ({ tool: 'codex', id, modified, current: false, read: () => readCodex(id, files) }));
+}
+
+function readCodexAgent(session, name, records) {
+  const agent = newAgent(name);
+  let lastTotal = null;
+  for (const record of records) {
+    touch(agent, record.timestamp);
+    const payload = record.payload || {};
+    if (record.type === 'turn_context') agent.model = payload.model || agent.model;
+    if (record.type === 'response_item' && /_call$/.test(payload.type || '')) addToolCall(session, agent, payload.name || payload.type);
+    if (record.type !== 'event_msg' || payload.type !== 'token_count' || !payload.info) continue;
+    // The count is also repeated when only the rate limits change; a new request moves the total.
+    const total = payload.info.total_token_usage?.total_tokens;
+    if (total === lastTotal) continue;
+    lastTotal = total;
+    const last = payload.info.last_token_usage || {};
+    addStep(agent, { context: last.input_tokens || 0, cached: last.cached_input_tokens, output: last.output_tokens });
+  }
+  return agent;
+}
+
+function readCodex(id, files) {
+  const session = newSession('codex', id);
+  const subagents = [];
+  for (const { meta, records } of files) {
+    if (meta.thread_source === 'subagent') subagents.push(readCodexAgent(session, meta.agent_role || meta.agent_nickname || 'subagent', records));
+    else session.agents.push(readCodexAgent(session, MAIN, records));
+  }
+  session.agents.push(...subagents.sort(byStart));
+  return session;
+}
+
+// ---------- Copilot CLI ----------
+// ~/.copilot/session-state/<session>/events.jsonl, with the working directory in workspace.yaml.
+// Events of a subagent carry its agentId. Token counts are written only when the session closes.
+
+const copilotHome = () => join(homedir(), '.copilot');
+
+function copilotSessions(root) {
+  const roots = rootForms(root);
+  const base = join(copilotHome(), 'session-state');
+  if (!existsSync(base)) return [];
+  const sessions = [];
+  for (const id of readdirSync(base)) {
+    const events = join(base, id, 'events.jsonl');
+    const workspace = join(base, id, 'workspace.yaml');
+    if (!existsSync(events) || !existsSync(workspace)) continue;
+    const cwd = (readFileSync(workspace, 'utf8').match(/^cwd: (.*)$/m) || [])[1];
+    if (!isWithin(roots, cwd)) continue;
+    sessions.push({ tool: 'copilot', id, modified: modifiedAt(events), current: false, read: () => readCopilot(id, events) });
+  }
+  return sessions;
+}
+
+function readCopilot(id, path) {
+  const session = newSession('copilot', id);
+  const agents = new Map();
+  const agentOf = key => {
+    if (!agents.has(key)) agents.set(key, newAgent(key));
+    return agents.get(key);
+  };
+  agentOf(MAIN);
+  let closed = false;
+  for (const event of jsonLines(path)) {
+    const data = event.data || {};
+    const agent = agentOf(event.agentId || MAIN);
+    touch(agent, event.timestamp);
+    if (event.type === 'subagent.started') {
+      agent.name = data.agentName || agent.name;
+    } else if (event.type === 'assistant.message') {
+      agent.steps++;
+      agent.model = data.model || agent.model;
+    } else if (event.type === 'tool.execution_start') {
+      addToolCall(session, agent, data.toolName);
+    } else if (event.type === 'session.shutdown' && data.agentMetrics) {
+      // A resumed session closes more than once; each close reports the run that ended with it.
+      closed = true;
+      for (const [key, metrics] of Object.entries(data.agentMetrics)) {
+        const reported = agentOf(key);
+        for (const { usage = {} } of Object.values(metrics.modelMetrics || {})) {
+          reported.sent = plus(reported.sent, usage.inputTokens);
+          reported.cached = plus(reported.cached, usage.cacheReadTokens);
+          reported.output = plus(reported.output, usage.outputTokens);
+        }
+      }
+    }
+  }
+  session.agents = [...agents.values()];
+  if (!closed) session.note = 'Copilot writes token counts when the session closes; until then /usage shows them.';
+  return session;
+}
+
+// ---------- Choosing the session ----------
+
+const LISTERS = { claude: claudeSessions, codex: codexSessions, copilot: copilotSessions };
+
+// The session to report: the one named by `id` (a prefix is enough), else the session this command
+// runs in when the tool says which one that is, else the most recently written one.
+export function sessionStats(root, { tool, id } = {}) {
+  let sessions = (tool ? [tool] : STATS_TOOLS).flatMap(name => LISTERS[name](root));
+  if (id) sessions = sessions.filter(session => session.id.startsWith(id));
+  sessions.sort((a, b) => b.modified - a.modified);
+  const chosen = (!id && sessions.find(session => session.current)) || sessions[0];
+  return chosen ? chosen.read() : null;
+}
+
+// ---------- Printing ----------
+
+const COLUMNS = ['agent', 'model', 'steps', 'first', 'peak', 'sent', 'cached', 'output', 'tools', 'min'];
+const TEXT_COLUMNS = 2; // agent and model align left; the numbers after them align right
+const LEGEND = 'first, peak: tokens sent with one request. sent: that, summed over every step. cached: the share of sent read from the cache.';
+
+function tokens(n) {
+  if (n == null) return '-';
+  if (n < 1000) return String(n);
+  if (n < 1e6) return `${Math.round(n / 1000)}k`;
+  return `${(n / 1e6).toFixed(1)}M`;
+}
+
+const cachedShare = agent => (agent.sent ? `${Math.round((100 * (agent.cached || 0)) / agent.sent)}%` : '-');
+const minutes = (start, end) => Math.round((end - start) / 60000);
+
+function clock(time) {
+  const d = new Date(time);
+  const two = n => String(n).padStart(2, '0');
+  return `${d.getFullYear()}-${two(d.getMonth() + 1)}-${two(d.getDate())} ${two(d.getHours())}:${two(d.getMinutes())}`;
+}
+
+// "2026-10-05 10:27 to 11:04, 37 min"; the end repeats the date only when it is another day.
+function period(start, end) {
+  const [from, to] = [clock(start), clock(end)];
+  const sameDay = from.slice(0, 10) === to.slice(0, 10);
+  return `${from} to ${sameDay ? to.slice(11) : to}, ${minutes(start, end)} min`;
+}
+
+function sessionPeriod(agents) {
+  const timed = agents.filter(agent => agent.start != null);
+  if (!timed.length) return '';
+  return period(Math.min(...timed.map(agent => agent.start)), Math.max(...timed.map(agent => agent.end)));
+}
+
+// The sum of the agents. It has no context of its own and no period, so those cells stay empty.
+function totalOf(agents) {
+  const total = newAgent('total');
+  for (const agent of agents) {
+    total.steps += agent.steps;
+    total.toolCalls += agent.toolCalls;
+    for (const field of ['sent', 'cached', 'output']) {
+      if (agent[field] != null) total[field] = plus(total[field], agent[field]);
+    }
+  }
+  return total;
+}
+
+const cells = agent => [
+  agent.name, agent.model, String(agent.steps), tokens(agent.first), tokens(agent.peak), tokens(agent.sent), cachedShare(agent),
+  tokens(agent.output), String(agent.toolCalls), agent.start == null ? '' : String(minutes(agent.start, agent.end)),
+];
+
+function table(rows) {
+  const widths = COLUMNS.map((_, column) => Math.max(...rows.map(row => row[column].length)));
+  const pad = (cell, column) => (column < TEXT_COLUMNS ? cell.padEnd(widths[column]) : cell.padStart(widths[column]));
+  return rows.map(row => row.map(pad).join('  ').trimEnd());
+}
+
+export function formatStats(session) {
+  const { agents } = session;
+  const rows = [COLUMNS, ...agents.map(cells)];
+  if (agents.length > 1) rows.push(cells(totalOf(agents)));
+  const calls = Object.entries(session.tools).sort((a, b) => b[1] - a[1]).map(([name, count]) => `${name} ${count}`);
+  return [
+    ['session', session.tool, session.id, sessionPeriod(agents)].filter(Boolean).join('  '),
+    ...table(rows),
+    `tool calls  ${calls.join('  ') || 'none'}`,
+    LEGEND,
+    ...(session.note ? [session.note] : []),
+  ].join('\n');
+}
+
 // Superwiki CLI. Lives in a project at docs/.sw/sw.mjs and prints short answers,
 // so agents do not have to read the vault to get them.
-import { spawn } from 'node:child_process';
-import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, writeFileSync } from 'node:fs';
-import { createServer } from 'node:http';
-import { basename, dirname, join, resolve as resolvePath } from 'node:path';
-import { fileURLToPath } from 'node:url';
 
 const HELP = `sw <command> [--docs <dir>] [--json]
 
@@ -333,6 +694,8 @@ const HELP = `sw <command> [--docs <dir>] [--json]
   search <words>  pages and log entries that mention the words, best match first
   next-id <AREA>  next free task id for an area (numbers are never reused)
   lint            structural checks; exit code 1 on errors
+  stats           what the agent session here has cost so far: steps, context and tokens per agent
+                  [--session <id>] another session of this project  [--tool ${STATS_TOOLS.join('|')}]
   serve [--open]  start (or reuse) a local viewer at http://127.0.0.1:<port>/ that reads the files live
   snapshot        write docs/.sw/data.js so docs/viewer.html opens as a file, frozen at this moment`;
 
@@ -394,8 +757,8 @@ export function vaultData(docs) {
 export const dataScript = data => `window.SW_DATA = ${JSON.stringify(data).replace(/</g, '\\u003c')};\n`;
 
 // ---------- Commands ----------
-// Each command gets { docs, vault, args, flags } and returns { data, text, code? }.
-// `data` is what --json prints; `text` is the default output.
+// Each command gets { docs, vault, args, flags } and returns { data, text, code? } or
+// { error, code? }. `data` is what --json prints; `text` is the default output.
 
 function status({ vault }) {
   const s = summary(vault);
@@ -557,6 +920,17 @@ function lintCommand({ vault }) {
   };
 }
 
+// Agent sessions are recorded by the folder they ran in: the project root, which holds docs/.
+function stats({ docs, flags }) {
+  if (flags.tool && !STATS_TOOLS.includes(flags.tool)) {
+    return { error: `usage: sw stats [--session <id>] [--tool ${STATS_TOOLS.join('|')}]` };
+  }
+  const root = dirname(docs);
+  const session = sessionStats(root, { tool: flags.tool, id: flags.session });
+  if (!session) return { error: `no ${flags.tool || 'agent'} session record found for ${root}`, code: 1 };
+  return { data: session, text: formatStats(session) };
+}
+
 function snapshot({ docs }) {
   const data = vaultData(docs);
   mkdirSync(join(docs, '.sw'), { recursive: true });
@@ -664,20 +1038,24 @@ const COMMANDS = {
   search: { run: searchCommand, needsVault: true },
   'next-id': { run: nextIdCommand, needsVault: true },
   lint: { run: lintCommand, needsVault: true },
+  stats: { run: stats, needsVault: false },
   snapshot: { run: snapshot, needsVault: false },
   serve: { run: serve, needsVault: false },
 };
 
+// Flags that are on or off, and flags that take the next argument as their value.
+const SWITCHES = ['json', 'open', 'foreground'];
+const OPTIONS = ['docs', 'tool', 'session'];
+
+// Anything that is not a known flag is positional, so search words may start with dashes.
 function parseArgs(argv) {
-  const flags = { json: false, open: false, foreground: false, docs: null };
+  const flags = Object.fromEntries([...SWITCHES.map(name => [name, false]), ...OPTIONS.map(name => [name, null])]);
   const positional = [];
   for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i];
-    if (arg === '--docs') flags.docs = argv[++i] || '.';
-    else if (arg === '--json') flags.json = true;
-    else if (arg === '--open') flags.open = true;
-    else if (arg === '--foreground') flags.foreground = true;
-    else positional.push(arg);
+    const name = argv[i].startsWith('--') ? argv[i].slice(2) : null;
+    if (SWITCHES.includes(name)) flags[name] = true;
+    else if (OPTIONS.includes(name)) flags[name] = argv[++i] ?? null;
+    else positional.push(argv[i]);
   }
   return { command: positional[0], args: positional.slice(1), flags };
 }

package/skills/sw-stats/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: sw-stats
+description: Use when the user asks what the current agent session has cost or used (tokens, context size, steps, tool calls, time, per subagent), wants a session summary or statistics, or invokes sw-stats or sw:stats.
+---
+
+# sw-stats
+
+Shows what this session has cost so far: one row for the main session and one for each subagent it started. A script reads the record your tool keeps of the session; you read nothing yourself and write no file.
+
+Run from the project root:
+
+```bash
+node docs/.sw/sw.mjs stats
+```
+
+It reports the session it runs in. For another session of this project, add `--session <id or its first characters>`; to look only at one tool's sessions, `--tool claude|codex|copilot`.
+
+## Answer
+
+1. **Show the table as printed**, in a code block. Do not round, reorder or translate it.
+2. **Add at most three observations**, in the user's language, each one a number from the table and what it means. Pick the ones that apply:
+
+   | In the table | Say |
+   | --- | --- |
+   | one agent's `sent` is most of the total | which agent, and its share. That is where the session's cost is |
+   | an agent's `peak` is several times its `first` | its context grew during the work; `steps` times a large context is what makes `sent` large |
+   | `first` is large for `main` | the session starts heavy before it reads anything: rules files, plugins and tool definitions. The tool's own context command shows what fills it |
+   | `cached` is well below the others for one agent | much of what it sent was not served from the cache, which costs more per token. Long pauses do that |
+   | `main` has many `steps` or a `peak` far above its `first` | work is running in the main session that a subagent could do in a clean context |
+
+3. Nothing else: no advice the table does not support, and no price. The table counts tokens; what a token costs depends on the user's plan.
+
+## Columns
+
+So that you can answer a question about them:
+
+- `steps`: model requests. `tools`: tool calls. `min`: minutes between the agent's first and last record.
+- `first`, `peak`: tokens sent with the first request and with the largest one.
+- `sent`: tokens sent, summed over every step. A step re-sends the whole context, so this is far larger than `peak`.
+- `cached`: the share of `sent` that was read from the cache.
+- `output`: tokens the model wrote.
+- `-`: the tool's record does not hold that number.
+
+## If it fails
+
+| Output | Do |
+| --- | --- |
+| `unknown command stats` | the project's `docs/.sw/sw.mjs` is older than this skill; offer to run sw-init, which updates it |
+| `no agent session record found` | say so, and name the tool's own command instead: `/cost` or `/context` (Claude Code), `/status` (Codex), `/usage` (Copilot CLI). A session started in a subfolder of the project is recorded under that folder and is not found |
+| a note that Copilot has not written token counts yet | pass the note on; steps and tool calls are still valid |