Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,12 @@ agents through SQL and a CLI. Nothing leaves the machine.
- **A status line in Claude Code:** `qx $3.42 · ctx 182k · cache 96%`, from the harness's own numbers.
- **Nudges** (toasts, never added to the model's context): the prompt cache expired after idle time and the next
call re-wrote it; the context passed 200k.
- **`/clear-tool-outputs [keep N]`:** compacts by replacing old tool outputs with short stubs instead of a summary.
- **`/clear-tools [outputs] [keep N]`:** compacts by replacing old tool calls (their inputs) and old tool outputs
with short stubs instead of a summary, in one pass, so the prompt cache is written once. `outputs` clears only
the outputs; `keep N` leaves the last N whole. Also as `/compact tools [outputs] [keep N]`. The next call
writes the whole new context to the cache again; the toast gives that cost and after how many calls the
smaller context pays it back, so a clear pays most right after the cache expired. A run with nothing to clear
changes nothing. Small inputs (300 chars or less) and ToolSearch results stay whole.
- **`/quantext view`:** opens a live viewer on `http://127.0.0.1:4747` with every session on the machine:
- the context of each call, exactly as the model received it (system prompt, tool schemas, messages), with the
tokens and cost of each block, and what was read from the cache or written to it;
Expand Down
4 changes: 2 additions & 2 deletions docs/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ agents (SQL, CLI, later MCP). Nothing leaves the machine.

| Part | Runs in | Can do | Cannot do |
|---|---|---|---|
| **Mod** | Claude Code's mod sandbox (no DOM, no Node; I/O only through `$`) | Read each call's `usage`, status line, toasts, commands, `/clear-tool-outputs`, `/clear-tool-calls`, `/clear-tools`; `$.http.fetch` to the engine; start the engine with `$.process.run` | Open a server, use npm packages or Node built-ins, keep a child process alive (`$.process.spawn` dies with the session) |
| **Mod** | Claude Code's mod sandbox (no DOM, no Node; I/O only through `$`) | Read each call's `usage`, status line, toasts, commands, `/clear-tools [outputs] [keep N]`; `$.http.fetch` to the engine; start the engine with `$.process.run` | Open a server, use npm packages or Node built-ins, keep a child process alive (`$.process.spawn` dies with the session) |
| **Engine** | A separate Node ≥ 22.18 or Bun process, started detached | Watch and parse transcripts, write the store, serve HTTP + SSE and the viewer's files | — |
| **Viewer** | The browser | Read the engine's API | — |

Expand Down Expand Up @@ -222,7 +222,7 @@ Each step ends with tests, and later steps never reach below the layer they depe
| 6 | **Query layer + CLI**: `qx ingest`, `qx sessions`, `qx call`, `qx sql` with views | 1 | An agent answers "top tool outputs by lifetime cost" with `qx sql` |
| 7 | **API + engine process**: HTTP JSON + SSE, Host check, single instance, idle exit | 1 | SSE fires on a new call; a second start reuses the running engine |
| 8 | **Live context viewer**: reuse the eduagent visualiser components with a read-only Claude Code adapter; the teaching features above | 1 | A running session updates in the browser call by call; meets the UX bar |
| 9 | **Mod**: status line, nudges, `/clear-tool-outputs` from in-process `usage`; `/quantext view` starts the engine and opens the viewer | 1 | Works on a fresh Claude Code install; harness features work with no Node or Bun |
| 9 | **Mod**: status line, nudges, `/clear-tools` from in-process `usage`; `/quantext view` starts the engine and opens the viewer | 1 | Works on a fresh Claude Code install; harness features work with no Node or Bun |
| 10 | **Agent surface**: schema docs, a skill, MCP later | **2** | The reviewer questions are answered and checked in the viewer |

Code from the earlier prototype (the Python parser and incremental store, pricing, the mod widget) is ported inside
Expand Down
13 changes: 11 additions & 2 deletions docs/known-issues.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,8 +31,17 @@ workaround), **low** (cosmetic, rare, or only a cost).
| medium | mod | No install straight from GitHub: the marketplace entry points at `./dist/plugin`, which is built, not committed (ADR 27). | A release job commits `dist/plugin` to a `plugin` branch, and the marketplace entry names that ref. |
| medium | mod | CI does not run the mod's tests: `pnpm test:mod` needs the `claude` CLI and skips loudly without it. | Install a pinned Claude Code in CI and set `QUANTEXT_REQUIRE_CLAUDE=1`. |
| medium | mod | A fake engine that listens on a stale `engine.json` port can answer `/health` with the right version and pid, and the mod opens it. Accepted inside the single-user trust boundary: only a local process of the same user can do it. | A secret in `engine.json` (mode 600) that `/health` echoes, checked by the mod. |
| medium | mod | `clearToolOutputs` and `clearToolCalls` drop the `handle` of a message they change (`clear-tool-outputs.ts`, `clear-tool-calls.ts`), so the engine rebuilds it from role, text and tool blocks: images or extra text blocks in that message can be lost or joined. | Leave a message whole when it holds more than tool blocks and one text block. |
| medium | mod | After `claude --resume` of a session cleared by `/clear-tool-outputs`, `/clear-tool-calls` or `/clear-tools`, Claude Code 2.1.322 sends the original tool inputs and outputs again (seen in the resumed request: the full `Write` content, a `[Tool use interrupted]` row, a thinking block twice). In the same session the stubs hold. The likely cause is that resume joins the assistant rows of one API response by message id, and the kept rows still carry the original id. | Report it to Claude Code with a repro; until then, run the clear command again after a resume (not yet tested). |
| low | mod | `/clear-tools` drops the `handle` of a message it changes, so Claude Code rebuilds it. On a live clear (session 244) the rebuilt messages kept all their thinking, text and image blocks (same counts before and after). Not tested: an image inside a tool result that is kept, in a message that changed. | Add that case to a live check (or a harness test) and see that the image stays. |
| medium | mod | `/clear-tools` clears even when it saves little: a clear on a large context re-writes the whole cache for a small per-call saving (the toast now gives the cost and payback, review H1). | Skip with "saves little" when the saving is under ~10% of the context unless the user adds `force`; have the expiry nudge say "the cache expired: /clear-tools now costs no extra write". |
| low | mod | The `/clear-tools` reply ("Clearing …", ~21 tokens) and Claude Code's "Compacted …" stdout (~22 tokens) enter the model's context as `<local-command-stdout>`. | A shorter (or empty) reply; say in the docs that this text enters. |
| low | mod | The `/clear-tools` toast counts an image tool result as 0 chars (about 1.5k tokens each), and the tokens it gives are chars / 4. | Add a fixed cost per image result whose `text` is empty. |
| low | mod | `keep N` counts calls and outputs on their own, and small inputs count toward N: an interrupted call with no result shifts the count, so a call can stay while its output gets a stub. | Count both from one list, the ids of the last N tool uses; say "each parallel call counts" in the help text. |
| low | mod | Tests miss: parallel calls with the `keep` boundary inside one message, a check that every `tool_use` id keeps its `tool_result`, an `updateLive` failure after a clear; fixtures need `as never` casts. | Add those cases, and a typed fixture helper in `test/kit.ts`. |
| low | mod | Bare `/compact tools` is a clear with `keep 0`, so a user who means "focus the summary on tools" gets a clear and no summary. | Say so in the README, or ask for `/compact tools keep N` only. |
| medium | adapter | Late in a long context, per-block token estimates for tool-call blocks are 3 to 4 times too high (session 244, call 880: a 129-char Bash input counted as 499 tokens), so the viewer's tool-calls figure is too high. | Cap a block's estimate at about 1 token per 1.5 chars; find where the call's residual goes to the last blocks. |
| low | pricing | On session 244 the engine priced a cache read at $0.22/M and a 1-hour write at $8.80/M (40x); list prices give 20x, so a payback the viewer derives may be off. | Check those prices against the provider's list for the model. |
| medium | mod | After `claude --resume` of a session cleared by `/clear-tools` (either form), Claude Code 2.1.322 sends the original tool inputs and outputs again (seen in the resumed request: the full `Write` content, a `[Tool use interrupted]` row, a thinking block twice). In the same session the stubs hold. The likely cause is that resume joins the assistant rows of one API response by message id, and the kept rows still carry the original id. | Report it to Claude Code with a repro; until then, run `/clear-tools` again after a resume (not yet tested). |
| low | mod | `/compact tools` with words the mod does not read (e.g. `/compact tools keep -1`) is not a clear: it goes to Claude Code as summary instructions, and costs a summary. `/clear-tools` checks its words first, so only the typed `/compact` form has this. | Answer `/compact tools <bad words>` with a skip that names the usage; the cost is that instructions starting with "tools" can no longer go to the summary. |
| low | mod | Permission prompts for `/quantext view` are untested; an interactive session may ask before each `$.process.run` (`node --version`, `uname`, `sh`, `open`). | Try it on a fresh install; if it asks several times, find the runtime with one `sh -c 'command -v node bun'` and cache it in `$.store`. |
| low | mod | `xdg-open` can block on some Linux desktops; after 5 s the mod says "open it in a browser" although it opened. | Run it detached, as the engine is started. |
| low | mod | Two `/quantext view` at once both find no engine and both run `sh`. Safe: the engine's writer lock lets one serve and the other exit. | An in-memory "starting" flag, so the second waits for the first. |
Expand Down
24 changes: 11 additions & 13 deletions packages/mod/src/clear-tool-calls.ts
Original file line number Diff line number Diff line change
@@ -1,28 +1,25 @@
/**
* `/clear-tool-calls [keep N]`: replace the input of old tool calls with a short stub, so the model's own Write
* contents, Bash heredocs and Agent briefs leave the context. Each call keeps its name and id, so it still pairs
* with its result. Deterministic: no model call. It runs as `/compact tool-calls keep N`.
* The calls half of `/clear-tools`: replace the input of old tool calls with a short stub, so the model's own
* Write contents, Bash heredocs and Agent briefs leave the context. Each call keeps its name and id, so it still
* pairs with its result. Deterministic: no model call (`clear-tools.ts`).
*/
import type { SessionMessage, ToolUseSummary } from "claude-code";
import { tokens } from "./format.ts";
import { approx } from "./format.ts";

/** Starts every stub, so a second run sees which inputs are cleared already. */
export const CLEARED_INPUT = "[Old tool input cleared";

/** Inputs up to this size (~200 tokens) stay: a stub would save little. */
const SMALL_INPUT_CHARS = 800;
/** Inputs up to this size (~75 tokens) stay: a stub would save little. */
const SMALL_INPUT_CHARS = 300;
/** A field up to this size stays in the stub input (a path, a name, a short description). */
const SMALL_FIELD_CHARS = 200;
const SMALL_FIELD_CHARS = 80;
/** A stub must save at least this many chars, or the input stays (one of many short fields grows). */
const MIN_SAVED_CHARS = 100;
const HEAD_CHARS = 60;

const sizeOf = (v: unknown): number => JSON.stringify(v)?.length ?? 0;
const str = (v: unknown): string => (typeof v === "string" ? v : "");
const lineCount = (s: string): number => (s === "" ? 0 : s.split("\n").length);
/** Tokens at ~4 characters each: `850`, `4.2k`, `12k`. */
const approx = (chars: number): string => {
const n = Math.round(chars / 4);
return n < 1000 ? `${n}` : n < 10_000 ? `${(n / 1000).toFixed(1)}k` : tokens(n);
};
const head = (s: string): string => {
const first = s.split("\n")[0] ?? "";
return first.slice(0, HEAD_CHARS);
Expand Down Expand Up @@ -72,7 +69,7 @@ const isStub = (u: ToolUseSummary): boolean =>
Object.values(u.input).some((v) => typeof v === "string" && v.startsWith(CLEARED_INPUT));

/**
* Stubs the input of every tool call but the last `keep`; small inputs stay. A changed message loses its engine
* Stubs the input of every tool call but the last `keep`; small inputs, and those a stub would not shrink, stay. A changed message loses its engine
* handle and is rebuilt from role, text and tool blocks. Calls stubbed already do not count toward `keep`.
*/
export function clearToolCalls(messages: readonly SessionMessage[], keep = 0) {
Expand All @@ -95,6 +92,7 @@ export function clearToolCalls(messages: readonly SessionMessage[], keep = 0) {
const size = sizeOf(u.input);
if (size <= SMALL_INPUT_CHARS) return u;
const input = stubInput(u.tool, u.input);
if (size - sizeOf(input) < MIN_SAVED_CHARS) return u;
cleared++;
chars += size - sizeOf(input);
return { ...u, input };
Expand Down
15 changes: 11 additions & 4 deletions packages/mod/src/clear-tool-outputs.ts
Original file line number Diff line number Diff line change
@@ -1,17 +1,24 @@
/**
* `/clear-tool-outputs [keep N]`: replace old tool outputs with the stub Claude Code's own microcompact writes,
* and keep everything else, in place of a summary. It runs as `/compact tool-outputs keep N` (`clear-tools.ts`).
* The outputs half of `/clear-tools`: replace old tool outputs with the stub Claude Code's own microcompact
* writes, and keep everything else, in place of a summary (`clear-tools.ts`).
*/
import type { SessionMessage } from "claude-code";

/** Claude Code's own stub for a cleared tool output. */
export const CLEARED = "[Old tool result content cleared]";

/** Tools whose results load deferred tool schemas (`tool_reference`): a stub would unload them. */
const KEEP_WHOLE = new Set(["ToolSearch"]);

/**
* Stubs every tool result but the last `keep`. A message left whole keeps its engine handle; one changed loses
* it, so the engine rebuilds it from its role, text and tool blocks. Stubs already there do not count.
* it, so the engine rebuilds it from its role, text and tool blocks. Stubs already there, and ToolSearch
* results (kept whole), do not count.
*/
export function clearToolOutputs(messages: readonly SessionMessage[], keep = 0) {
const keepWhole = new Set(
messages.flatMap((m) => m.toolUses.filter((u) => KEEP_WHOLE.has(u.tool)).map((u) => u.tool_use_id)),
);
let left = keep;
let cleared = 0;
let chars = 0;
Expand All @@ -23,7 +30,7 @@ export function clearToolOutputs(messages: readonly SessionMessage[], keep = 0)
const results = [...before]
.reverse()
.map((r) => {
if (r.text === CLEARED) return r;
if (r.text === CLEARED || keepWhole.has(r.tool_use_id)) return r;
if (left > 0) {
left--;
return r;
Expand Down
Loading
Loading