Prudence

Record how you build with AI coding agents. See what became of the code.
Carry what worked into the next round.

English | 简体中文

---

The problem

Developers who build with AI agents ship faster than ever, and many of them are not getting better.

• The code works, but the person who shipped it often cannot explain it.
• Nothing tells them which ways of working lead to code that lasts and which lead to rework and bugs. Solo developers have no colleague, no code review, and often no users, so reality's feedback never reaches them.
• Better methods exist, but they do not know which ones apply to what they are doing this week.
• Their improvement comes mostly from the model getting better, not from themselves, and they can feel it.

The loop

Prudence turns AI-assisted development into a feedback loop.

   record ──► link ──► learn ──► adjust
     ▲                              │
     └────────── next round ◄───────┘

• Record. It reads the sessions your AI coding agent already keeps on disk and archives them unmodified.
• Link. It follows every line those sessions produced through git: what survived at 7, 30 and 90 days, what was rewritten, where the tokens and hours went.
• Learn. It joins how you worked to what happened: which of your own habits went with which outcomes, in your own projects, with the coverage behind every number.
• Adjust. A review each period says what changed and what to try; the next review says whether it helped. What works stays, what does not is dropped.

Each round makes the next one better informed. The record is yours and stays on your machine.

What you get

• A record you own. Every session archived locally, byte for byte, with show, forget and export for all of it.
• Outcomes, not impressions. For each session: lines still alive at 7, 30 and 90 days, lines reworked by your own later commits, with the coverage and the attribution method behind every number.
• Usage by purpose. Tokens and active hours per session, classified into development, research, debugging, conversation, so a session that produced no code stops looking like a gap.
• Observations. Your sessions with a behaviour against your sessions without it, inside one project: "your 16 sessions that compacted their context reworked 28% of their lines; the 33 that did not, 6%." Reported only when your own data clears a sample floor and a gap floor.
• Reviews. prudence review turns a period into a stored review whose every figure is computed; an optional model-written paragraph on top may only quote those figures and is refused if it invents one or grades you.
• Ask. prudence ask "why do my refactors on this project keep getting reverted" answers from retrieved evidence and cites session ids.
• Three surfaces. The CLI, a Claude Code plugin with skills and an MCP server, and a native macOS menu-bar app with charts.

Where it is going

Three promises shape the roadmap:

1. Reality's feedback, delivered. What survived, what was rewritten, what broke, where the time and tokens went: the colleague and the code review you do not have.
2. Growth that is yours. How your way of working with AI evolves over months, what you shipped but did not understand, and help closing that gap only when you need it. Suggestions are tracked: the next review says whether one helped, and advice that does not work is retired.
3. A window to the outside. Knowing what you are wrestling with right now, it goes out to see how the field solves it today and explains what applies to your project, with sources.

The tools will keep changing; the record is built so that a new agent is a new source, a new way of reading it is a new lens, and a new way of reaching you is a new surface. Three years in, a developer should have an honest, evidence-backed record of every project, how their habits changed, and which advice worked for them, carried across every generation of AI tools they used. They would no more give it up than their git history.

Principles

1. The record is yours. Local, visible, exportable, dependent on no AI vendor.
2. Your own results are the evidence. Claims about you come from your own sessions and commits, in the project they came from; a model's impression is not evidence.
3. Facts with their confidence, never scores. Counts you can check, each with its coverage and method; no grades, streaks, badges or leaderboards.
4. Suggestions, never orders. Prudence never forces a mode, a workflow or a curriculum.

Install

Prudence needs Python 3.12 or later and uv.

uv tool install --python 3.12 "prudence-dev[mcp,model]"

Extras: mcp adds the MCP server the Claude Code plugin uses; model adds the Anthropic SDK for review --explain and the prose half of ask. Without model, everything else works and no model is ever called.

The macOS menu-bar app is a separate download: the DMG on the latest release (unsigned until the Developer ID certificate exists; right-click, Open, on first launch). Build it yourself from apps/mac.

Quick start

prudence init --scan                      # list the repositories in your agent history
prudence init --enable <repo> --level full
prudence ingest                           # read what the agent recorded; first run prints a "first look"
prudence sessions --last 30d
prudence outcomes --project <repo>        # what became of each session's lines
prudence usage --last 30d                 # tokens and hours by purpose
prudence observations --project <repo>   # your behaviours against your own outcomes
prudence review --project <repo>          # a stored review of the period since the last one
prudence review --explain                 # plus a model-written paragraph, checked against the numbers
prudence ask "what did I spend tokens on last week"
prudence hooks install                    # optional: turn-level git state through Claude Code hooks
prudence export

init --enable turns recording on for one repository at a time, at full capture or metadata-only (shape without content, for a repository whose code you would rather not store). hooks install edits Claude Code's settings file, shows the diff first, and prudence hooks uninstall reverses it byte for byte. Before every model call Prudence prints what it is about to send: sections, number of figures, no transcript content, size, and the estimated cost.

Claude Code plugin

claude --plugin-dir ./plugin

Skills /prudence:sessions, /prudence:outcomes, /prudence:usage, /prudence:recall, /prudence:review, /prudence:ask, and an MCP server an agent can query directly (there, ask returns the evidence only, because the agent calling it is already a model). See plugin/README.md.

The macOS app

A menu-bar icon whose dropdown shows today, this week's tokens by purpose, the latest observation and the last review; a window with Overview (tokens by purpose per week, survival and rework per project with coverage, where the hours went), Review (the stored review as cards and charts), Observations and Settings. Swift and Swift Charts, reading the same SQLite store through a versioned set of app_* views; the app never computes a number of its own. English and Simplified Chinese. See apps/mac/README.md.

What it records and what it never records

Raw session data is archived unmodified in a local store with owner-only permissions. Derived tables hold counts, classes and keyed line hashes, never message text, at any capture level. metadata-only withholds file paths and line hashes as well. Nothing is uploaded anywhere; observations compare you only with yourself. If you plan to enable Prudence on a work repository, check your employer's policy first.

How it works

AI coding-agent transcripts and hooks ──► one local SQLite store (raw archive + derived tables)
        ──► attribution (which session made which commit, with confidence)
        ──► outcomes (survival, rework), facts, observations, reviews
        ──► CLI · Claude Code plugin and MCP · macOS app (app_* views)

ARCHITECTURE.md has the layout and the rules that keep it easy to change.

Status

0.4.0. Supported agent source: Claude Code (the source layer is one module per agent). Windows is untested. See RELEASES.md.

Contributing

Issues and pull requests are welcome; see CONTRIBUTING.md (DCO sign-off, Conventional Commits, English only, AI-assisted contributions disclosed).

License

Apache-2.0. See LICENSE. The Prudence name and mark are not covered by the code licence; see assets/brand/README.md.