Agent Ledger Documentation

01 / INSTALL

Install in one command

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

npx skills add sprintagency-it/agent-ledger --skill agent-ledger --yes --copy

The CLI detects the active agent. Add --agent codex or --agent claude-code if needed. The skill bundles its runtime and prepares the ignored local evidence workspace on first use.

Prepare both agents immediately

npx --allow-git=all --yes github:sprintagency-it/agent-ledger#v0.3.3 setup --project .

npm 12 requires explicit permission for a Git package fetch. The official skills CLI records anonymous installation telemetry by default; prefix the directory command with DISABLE_TELEMETRY=1 to opt out. Agent Ledger sends no run data.

02 / FIRST TASK

Invoke the skill with a concrete outcome

# Codex
Use $agent-ledger to fix the signup validation bug.

# Claude Code
/agent-ledger Fix the signup validation bug.

That is enough. The skill derives goal, scope, checks, and approval boundaries from the task and repository, and asks only if an ambiguity blocks safe execution.

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

Chat first, evidence when you need it

The final chat reply gives the human the concise result, status, fixes, and unresolved decisions. The saved files provide deeper evidence for people and other agents.

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.3
  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.