A local comprehension workspace for agent-produced changes

Your agent shipped 3,000 lines overnight. Read them like a story.

ndrstnd turns a branch diff into an evidence-linked narrative: semantic chapters, color-coded impact, a build-path timeline, a test plan, and the full diff. Understand the change before you judge it.

Install ndrstnd View on GitHub

Runs entirely on your machine
Open source · Apache-2.0
Self-contained artifacts, private to your working copy

Payment captures now retry transient gateway failures with jittered exponential backoff, and idempotency keys guarantee a retry can never double-charge.

12 files · 31 evidence hunks · 5 story chapters · 5 build steps

01Retry transient capture failurescaptureCharge retries gateway timeouts with exponential backoff and jitter.behaviorperformance

02Idempotency keys guard every retryA stable key per payment intent makes retries safe from double-charging.securitybehavior

03Retry policy is configurableAttempts, base delay, and jitter validate through the config schema.behavior

04Extract a pure backoff moduleDelay math moves to src/payments/backoff.ts with no behavior change.refactor

05Cover exhaustion, jitter bounds, and key reuseNew tests pin retry exhaustion, delay bounds, and idempotency reuse.

The Story view of an ndrstnd artifact: one self-contained HTML file, no server required.

See it in action

Watch a branch become a story.

Fifty seconds, end to end: your agent finishes the checkout branch, its ndrstnd skill drafts the review, and the workspace opens with the story, zoom dial, timeline, and test plan. Pick your agent above; the demo follows.

The problem

Alphabetical order is not an explanation.

Coding agents produce more change per hour than anyone can absorb in file-path order. The diff is complete, but completeness isn't comprehension: a lockfile and a payment-critical retry loop get equal billing.

ndrstnd reads the branch the way you'd want a colleague to walk you through it: claims first, meaning second, evidence on demand. Every sentence in the story links to the hunks that prove it.

It compares the branch to its merge-base and asks your agent, Codex or Claude Code, for the narrative. If the analysis fails, it tells you so: it never fabricates a story it can't back with evidence.

What your forge shows

.github/workflows/ci.yml+6 −1
config/payment.schema.json+18 −2
package-lock.json+1,204 −87
src/payments/backoff.ts+47 −0
src/payments/capture.ts+52 −17
src/payments/gateway.ts+9 −4
src/payments/idempotency.ts+31 −0
test/payments/backoff.test.ts+44 −0
test/payments/capture.test.ts+59 −0
… 3 more files

Zoom controls

One dial, five altitudes.

The zoom dial moves the whole workspace between meaning and mechanism. Keep scrolling, and the workspace below follows the dial.

MapThemes and risk distribution

low 2contained 1elevated 1high 1

01Retry transient capture failures+64 −12 · 3 files · 6 hunks

02Idempotency keys guard every retry+38 −5 · 2 files · 4 hunks

03Retry policy is configurable+22 −3 · 2 files · 3 hunks

04Extract a pure backoff module+41 −29 · 2 files · 5 hunks

05Cover exhaustion and key reuse+103 −0 · 3 files · 8 hunks

01Retry transient capture failurescaptureCharge retries gateway timeouts with exponential backoff and jitter.

02Idempotency keys guard every retryA stable key per payment intent makes retries safe from double-charging.

03Retry policy is configurableAttempts, base delay, and jitter validate through the config schema.

04Extract a pure backoff moduleDelay math moves to src/payments/backoff.ts with no behavior change.

05Cover exhaustion, jitter bounds, and key reuseNew tests pin retry exhaustion, delay bounds, and idempotency reuse.

02Idempotency keys guard every retryA stable key per payment intent makes retries safe from double-charging.securitybehavior

Before

A single capture attempt per intent. Any gateway timeout surfaced to the caller as a failed payment, and manual retries risked charging the customer twice.

After

Transient failures retry up to maxAttempts with jittered exponential backoff, and every attempt reuses the same idempotency key, so a retry can never double-charge.

src/payments/capture.tsFocused excerpt · @@ −18 +18 @@

1818 export async function captureCharge(intent: PaymentIntent) {19-  return gateway.capture(intent);19+  const key = idempotencyKey(intent);20+  for (let attempt = 0; ; attempt += 1) {22+      return await gateway.capture(intent, { idempotencyKey: key });⌁24+      if (!isTransient(error) || attempt === policy.maxAttempts) throw error;25+      await sleep(backoffDelay(policy, attempt));

4 routine lines omitted

src/payments/capture.tsComplete excerpt · @@ −18 +18 @@

1818 export async function captureCharge(intent: PaymentIntent) {19-  return gateway.capture(intent);19+  const key = idempotencyKey(intent);20+  for (let attempt = 0; ; attempt += 1) {21+    try {22+      return await gateway.capture(intent, { idempotencyKey: key });23+    } catch (error) {24+      if (!isTransient(error) || attempt === policy.maxAttempts) throw error;25+      await sleep(backoffDelay(policy, attempt));26+    }27+  }2028 }

Level 0 · Map

The whole change at a glance

Chapter cards show where the churn went and where the risk lives, in five attention colors from low to critical. Know in ten seconds where to spend your next ten minutes.

Level 1 · Summary

Every chapter is a claim

The story states what the change does in plain sentences, ordered by meaning instead of file path. Skim it like a table of contents.

Level 2 · Explanation

Before and after, in words

One notch down, each claim explains the system it replaced: what used to happen, what happens now, and why the difference matters.

Level 3 · Evidence

Proof, minus the noise

Every claim links to the exact lines that back it. Routine lines fold behind a counted ⌁ divider: omitted, never hidden.

Level 4 · Raw

Nothing between you and the patch

At the bottom of the dial the workspace shows complete hunks, exactly as Git sees them. Trust the story, then verify it, without leaving the page.

The timeline view

“We cannot follow the ideal design process. But we can fake it in the documentation.”

after David L. Parnas and Paul C. Clements, “A Rational Design Process: How and Why to Fake It” (1986)

No branch is built in the order it's best understood. Agents scaffold, backtrack, revert, and patch their way to a result, and the commit log faithfully records all of that wandering. Replaying it teaches you the journey, not the design.

The Timeline view takes Parnas seriously. It rebuilds the change as a dependency-ordered build path: each step states its goal, what you now have once it lands, and what it deliberately defers, with the evidence accumulating step by step. The history stays honest. The reading order becomes rational.

What's inside

Every claim travels with its evidence.

ndrstnd never asks you to trust a summary. Each view is a different altitude over the same linked facts.

Semantic grouping

Hunks are grouped by what they mean, not where they live. A claim, its synopsis, its risk tags, and its evidence travel together as one chapter.

Color-coded impact

Five attention levels mark every chapter number, map card, and timeline dot, so risk is visible from any altitude.

lowcontainedelevatedhighcritical

Timeline: a build path

Dependency-ordered steps replay how you would assemble the change. Each step states its goal, what you now have, and what it defers, with the evidence accumulated so far.

Test plan view

Tested behaviors grouped into themes and linked back to story claims, zoomable from summary cards down to raw test artifacts.

Full diff, always

Every patch hunk, syntax-highlighted, with low-signal files collapsed but one click away. The story never replaces the diff.

Focused excerpts

Evidence shows the lines that matter and folds the routine ones behind a counted divider. You always know exactly what was omitted.

Ask the change

Select any lines and ask. The menu copies a prompt grounded in the evidence you selected, not in vibes, ready to paste into your agent.

Private, portable artifacts

Each review is one self-contained HTML file in your repo's .ndrstnd directory: readable on any device, private to your machine, and yours to keep for as long as you need.

Codex & Claude Code integration

Your agent hands you the review.

ndrstnd ships as a skill for Codex and Claude Code, plus a CLI. Install the skill once, and your agent can end its coding tasks by preparing an ndrstnd workspace for the human, instead of a wall of diff.

1
Skill-aware
After finishing a task, Codex or Claude Code runs ndrstnd on the branch (the analysis runs on the same agent that asked) and links the artifact in its reply, ready to read on desktop or mobile.
2
Read it without leaving your agent
Ask Codex or Claude Code to use ndrstnd and open the artifact right in the app's side panel. And when your agent runs remotely, the same review reads comfortably from your phone.
3
Conversation-informed
Pass --conversation and the implementation dialogue becomes part of the story: the decisions, not just the diff.
4
Zero token custody
ndrstnd rides your agent's existing authenticated session, whichever one drafts the narrative. It never stores a credential of its own.

$ ndrstnd skill install
Installed the ndrstnd skill for Codex at ~/.codex/skills/ndrstnd.
Installed the ndrstnd skill for Claude Code at ~/.claude/skills/ndrstnd.

$ ndrstnd review codex/checkout-retry-hardening --repo .
Drafting the review narrative with Codex…
merge-base=f3a91c02b7d4 files=12 meaningful-files=7
hunks=31 conversation=42
ndrstnd artifact: .ndrstnd/codex-checkout-retry-hardening.html

Get started

Homebrew · shipping soon

Four commands to your first story.

The repository doubles as a Homebrew tap, so the whole setup is:

Install the CLI

The repository doubles as a Homebrew tap; the trust step is Homebrew's confirmation for third-party taps.

$ brew tap truizlop/ndrstnd https://github.com/truizlop/ndrstnd
$ brew trust truizlop/ndrstnd
$ brew install ndrstnd

Connect your agent

ndrstnd reuses your existing Codex or Claude Code session. It never stores a token itself.

$ ndrstnd auth login

Teach your agent

Install the skill for Codex and Claude Code so finished tasks arrive as ndrstnd workspaces.

$ ndrstnd skill install

Understand a branch

Compare any branch to its merge-base and open the story. Use --base main to review the checked-out worktree, staged and unstaged changes included.

$ ndrstnd review feature/my-change --repo /path/to/repository

Artifacts are written to the reviewed repository's .ndrstnd/ directory and stay private to your working copy. When you add ndrstnd to a repo, add .ndrstnd/ to its .gitignore so review artifacts never end up in version control.

The point

Comprehension, not critique.

ndrstnd deliberately doesn't leave review comments, doesn't score your agent, and never edits the branch. It explains the implementation story, the evidence, and the risk signals, then gets out of the way. The judgment stays yours.

For critique, keep your review workflow. ndrstnd makes sure you understand what you're judging.