Agent Ledger Documentation

01 / INSTALL

Install in one command

Requirements: Git, Node 20+, and Codex or Claude Code. Run from the project root:

npx --yes github:sprintagency-it/agent-ledger#v0.3.0 setup --project .

Setup writes the shareable workflow to .agents/skills/agent-ledger/ for Codex and .claude/skills/agent-ledger/ for Claude Code, installs the private runtime under .agent-ledger/runtime/, and ensures .agent-ledger/ is ignored.

02 / FIRST TASK

Invoke the skill with a concrete outcome

# Codex
Use $agent-ledger to fix the signup validation bug, stay within src/signup and tests, and run the relevant tests.

# Claude Code
/agent-ledger Fix the signup validation bug, stay within src/signup and tests, and run the relevant tests.

The skill defines goal, scope, checks, and approval boundaries before editing. It then captures the task, renders findings, fixes safe true positives, and refreshes the review once.

Good task shape

Name the behavior to change.
Include likely path boundaries when known.
State the verification you expect.
Keep auth, secrets, deploys, and destructive actions explicit.

03 / OUTPUTS

Two readers, one evidence set

File	Primary reader	Purpose
`review.json`	Agent	Status, evidence counts, and structured findings.
`fix-brief.md`	Agent + human	Classification queue and safe automatic-fix boundary.
`executive-summary.md`	Human	Shortest run outcome and unresolved review items.
`pr-review.md`	Reviewer	Merge-facing PASS, WARN, or BLOCK record.
`replay.html`	Human	Offline visual timeline and risk context.
`share/`	Handoff	Smaller redacted bundle for deliberate sharing.

04 / BOUNDARIES

Correction is deliberate, not blind

Every critical or high finding is classified as true_positive, false_positive, or unresolved. The agent may automatically fix a true positive only when it is reversible, inside scope, and does not alter auth, secrets, permissions, billing, deployment, external data, or destructive behavior.

Risk rules are deterministic signals. Generic words such as API or credentials do not prove exposure; concrete paths, access behavior, and value-like evidence matter.

05 / DIRECT CLI

Use the lower-level runtime when needed

LEDGER=".agent-ledger/runtime/src/cli.mjs"
SESSION="$(node "$LEDGER" start --project . --name "my-run" --goal "Concrete outcome" --scope "src,tests" --out .agent-ledger/runs/my-run)"

# Make changes and run checks.
node "$LEDGER" ingest --type git --session "$SESSION"
node "$LEDGER" render --session "$SESSION"

Calling Git ingest again refreshes the final file evidence instead of duplicating it. Command evidence remains available across the correction pass.

06 / GITHUB ACTION

Capture an agent command in CI

- id: agent-ledger
  uses: sprintagency-it/agent-ledger@v0.3.0
  with:
    command: "node scripts/run-ai-agent-task.mjs"
    goal: "Review this AI-generated change before merge"
    scope: "src,tests"
    fail-on-critical: "true"

The Action attributes only changes created after its command starts. It does not yet review an arbitrary existing PR diff.

Install once. Use your agent.