ponens

Tutorials · Lesson 1 of 7

1 · Capture your first trace

You'll install ponens and turn a real agent session into a reasoning trace, then open it to see what was captured. You need: a recent coding session from an AI agent (Claude Code, Cursor, Codex, Gemini, or pi).

Why a trace at all?

When an AI agent finishes a task you're left with a diff and a chat log — but not a clear, checkable account of what it did and why, or what it left unverified. A ponens reasoning trace is that account: a curated, verifiable record you can review, govern with policies, and sign. This course builds one from your own work, step by step.

Install

pip install ponens

Emit the trace

Finish a task with your agent, then, from the project directory, capture the session. With no arguments ponens finds the newest Claude Code session for this project; pass --from to read a different agent (see Adapters).

ponens emit -o trace.json                 # newest Claude Code session for this project
ponens emit -o trace.json --from cursor   # or: cursor | codex | gemini | pi

Emission derives the trace from the transcript — you write nothing. It captures the actions, the file lineage, and the reasoning as ground truth.

The two layers

A trace has two layers, treated very differently — remember this, it's the heart of the model:

  • Atomic actions — the faithful record of what happened (files read/edited, commands run, results). Ground truth. Never rewritten.
  • Meta-action narrative — the curated story on top, seeded from your raw directives ("yes", "ok fix it"). This is the part you clean up (Lesson 2).

Look at it

Open the self-contained viewer — zoom from the intent-level steps down to the atomic actions, with the lineage graph and the residual surface.

ponens trace view trace.json              # opens in your browser
ponens trace status trace.json            # or a one-line summary in the terminal

Headless (SSH/CI)? view writes the HTML with --out trace.html. You can also explore a bundled example live in the demo.

What you learned

  • A trace is a curated, verifiable record of an agent session — captured with ponens emit.
  • It has two layers: faithful atomic actions and a curated meta-action narrative.
  • Any supported agent works via an adapter (--from).