Lean Ctx Review

lean-ctx session review

Upstream repo: yvgude/lean-ctx (https://github.com/yvgude/lean-ctx).

Reads a Claude Code session transcript, so it applies to agents that write ~/.claude/projects/*/*.jsonl. Other harnesses need their own extractor; the triage rules below are harness-independent.

1. Extract

Run from this skill's directory (needs python3):

python3 scripts/scan_session.py

Defaults to the newest transcript under ~/.claude/projects/*/ — the live Claude Code session. Pass a path to review a different one. -d N dumps call #N in full.

The script reports facts, not verdicts: every ctx_* call in order, which results the harness flagged is_error, which calls repeated identical arguments, which asked for raw/fresh output, and how many native Read/Grep/Bash calls happened. It deliberately does not guess which of those is a problem — that judgment is yours, below.

Transcripts run to megabytes, so read the table, not the raw JSONL.

2. Triage

Start from is_error. In practice every genuine tool failure carries it. Then read the call list for the softer signals: identical retries, raw/fresh re-reads, native calls clustered right after a ctx_* call, or a sequence that only completed once ctx_* was abandoned.

Before absolving anything, do these two things

Skipping them is how this review returns a false "nothing to report". Both cost one command each.

Search the tracker for the guard or tool you are about to excuse. Do this during triage, not at step 4. A closed issue defines intended behaviour: if a shipped fix says a form is supported and you just watched it fail, that is a regression and one of the most valuable things this review finds. It also stops you re-filing a settled design decision.

gh issue list --repo yvgude/lean-ctx --search "<guard or tool keyword>" --state all

Probe the stated rationale — never accept a message's self-description. An error explains itself, and that explanation can be wrong. Three checks, each one command:

• Does the sanctioned alternative achieve the same thing? If the block is bypassable through a route the message itself recommends, it constrains syntax, not capability. Sometimes that is deliberate (structured input parses reliably where a shell string does not) — decide which, do not assume.
• Does the stated reason match the observed rule? Vary one axis at a time. A guard blaming payload size that actually keys on path, or blaming a pipe on a command that is piped, is misdiagnosing itself.
• Does the message contradict itself? A rejection that also states the rejected form is allowed is a finding on its own, whichever way the policy should go.

A wrong diagnostic is a real bug even when the block is correct: it sends the next caller down a route that cannot work.

Not a finding

• Words inside returned content. A file containing http.StatusConflict, a git rebase printing CONFLICT (content):, gh returning "mergeable":"CONFLICTING", a test run printing not found. The tool returned exactly what was asked for. Judge the tool's own behaviour, never the payload's vocabulary.
• Self-reference. Any result that quotes a previous scan, this skill, or a transcript will echo every error word in it.
• Guard blocks — only after they survive the probe above. Inline env overrides (GIT_EDITOR=), shell redirects (>/>>), non-allowlisted commands, paths outside the project root. "It offered an alternative and the alternative worked" is not enough to clear one: that is true of a guard whose reason is wrong, whose rule is different from its description, or that contradicts itself. Clear it only once the stated rationale holds up.
• Malformed tool input. InputValidationError on __unparsedToolInput is the caller's own JSON serialization — commonly a raw tab or newline inside a string — rejected before lean-ctx ever ran.
• My own wrong arguments, a genuinely missing file, a failing build.