ponens

Documentation

ponens turns an AI coding agent's session into a higher-level reasoning record — a curated, verifiable account of what it built and why — then makes the reasoning rigorous and governs it with Computable Governance (machine-checkable best-practice policies). You do the work in the terminal; the browser is for reading, reviewing, and sharing the result.

New here? Take the course.

The Tutorials walk you through the whole methodology on your own agent session — capture, curate, declare, set a goal, govern, review, and sign — one lesson at a time.

Start the tutorials →

Quickstart

pip install ponens

ponens emit -o trace.json        # capture your latest agent session as a trace
ponens trace view trace.json     # read the reasoning behind the change

That's the first minute. The Tutorials take it from there; the guides are task-focused recipes; the spec is the reference.

Explore

Tutorials

A guided, hands-on course through the whole methodology — produce, govern, review, and sign a trace.

Guides

Short, copy-pasteable how-tos for real tasks — capture, review, CI, govern.

For agents

ponens is agent-first: how an agent produces and reviews its own traces.

Adapters

Capture any coding agent's session — Claude Code, pi, and more — via emit adapters.

Spec

The open standards — the trace, policy, and review-case models.

Key concepts

  • Trace — the curated, verifiable record of an agent's work session, in two layers: faithful atomic actions (ground truth) and a curated meta-action narrative.
  • Residual surface — what the trace did not establish: assumptions, unverified claims, out-of-scope items, limitations, open questions, and counter-evidence (defeaters). It tells a reviewer where to look.
  • Goals & acceptance — what the trace was for and its definition of done: typed criteria that resolve from the trace's own evidence, yielding three independent verdicts — met, governed, and certified (spec §18).
  • Computable Governance — best-practice policies as machine-checkable rules over the trace. Browse the gallery, read the Policy Language reference, or write your own.
  • Freshness & defeaters — evidence expires: a formal result is Fresh, Stale, or Detached as the code moves under it, and a defeater is counter-evidence that blocks a claim.