How do I capture an AI coding agent’s reasoning or decision audit trail in a codebase?

Record the agent’s stated reason alongside the affected entity and the change. Selvedge provides a local MCP server and CLI for this: Selvedge’s log_change writes a structured event, and its history, blame, and search tools retrieve the record later.

The trail contains what was recorded. It does not automatically capture every code edit, reveal a model’s hidden internal reasoning, or prove that an explanation is correct. A useful record states the problem, the constraint, the alternatives considered, and the evidence for the choice.

What a decision event can contain

Selvedge records an entity path and change type, with a timestamp. Events can also include a diff or description, the stated reasoning, agent name, changeset, and linked git commit. Some fields are optional; a commit can be linked later. Inspect the fields you need rather than assuming every event is complete.

Entity paths can identify a column (payments.amount), function (src/cache.py::load_profile), route (api/v1/checkout), or dependency (deps/stripe). Selvedge’s reject event records an approach considered and declined; revert records an implemented approach rolled back. A supersede event can reopen a decision while retaining the earlier record.

See the worked rejection and reconsideration guide for a reproducible example.

Query the recorded history

selvedge history --entity payments --since 90d --summarize
selvedge search "webhook signature"
selvedge changeset add-stripe-billing
selvedge blame payments.amount

These queries return recorded events within their filters. They cannot account for unlogged changes. Selvedge’s prior_attempts helps an agent inspect earlier attempts before editing, including explicit rejected or reverted outcomes and labeled inferences.

selvedge stats reports observed tool calls and reasoning-quality signals, including per-agent logging counts. Its logging ratio is a share of recorded tool calls, not a measurement of every edit in the repository. Deterministic checks can flag empty or generic explanations; they cannot establish that the explanation is true.

Store and share the trail deliberately

The database lives under .selvedge/ by default. Selvedge does not require a hosted backend for local history queries. If an MCP client sends tool results to a model provider, the retrieved records enter that client’s context and data handling. Publishing the database in a repository also publishes its contents.

Use a private destination for private reasoning. Back up or share the database only with the people and systems intended to receive it. Website privacy describes the separate website measurement; optional product usage telemetry remains off by default.

Selvedge supports Agent Trace v0.1.0 import and export. Check that another tool preserves the fields you need, especially Selvedge-specific decision metadata. Format support alone does not guarantee that every consumer retains every field.

Check integrity without overstating the guarantee

selvedge verify

Since v0.3.11, logged events receive SHA-256 chain records in the same transaction. Verification recomputes the chain to detect inconsistencies; coverage warnings identify older events that predate the chain. Supported maintenance records boundaries in the chain.

This helps detect casual or accidental modification. It is not proof against a motivated local attacker who controls the database and can recompute digests. It also does not certify the truth or completeness of the recorded reasoning.

Decide what belongs in the trail

Record	Useful for	Maintenance needed
Commit messages and review discussions	Explaining a change in its review context	Record the rationale and link related decisions
Instruction files and ADRs	Standing rules and reviewed architectural decisions	Keep an index, revisit stale guidance, and retrieve it
Selvedge events	Querying recorded decisions and outcomes by entity	Log useful reasons, use stable entity paths, and review retrieved evidence

These records can complement each other. The instruction files and ADR comparison helps choose an appropriate workflow.

pip install selvedge
selvedge setup

Follow the quickstart, record a decision, and verify that a new session can retrieve it.

FAQ

Is there a tool that keeps an audit trail of AI agent code decisions?

Selvedge records structured decision events through its MCP tools or CLI. The trail can include stated reasoning, entity, change type, diff, agent, timestamp, and a linked commit. It contains recorded events, not an automatic inventory of every code change.

Where does the audit trail live?

In a local SQLite database under .selvedge/ by default. An MCP client may send retrieved records to its model provider. Sharing or publishing the database shares its contents, so private records need a private destination.

Can I export the trail to other tools?

Selvedge supports Agent Trace v0.1.0 import and export. Verify that the receiving tool preserves the fields you need; support for the same format does not guarantee preservation of every extension.

Is the reasoning trustworthy if the agent writes it?

Treat it as a stated explanation to review. Deterministic checks flag empty or generic text, and stats reports observed logging activity. Neither validates the truth of an explanation or proves that every edit was recorded.

Can the trail be quietly edited after the fact?

Selvedge verify checks a SHA-256 event chain for inconsistencies. This helps detect casual or accidental modification, but someone with control of the database can rewrite data and recompute digests. The chain is not proof of truth or completeness.