Ledgerful

Ledgerful is a local-first Rust CLI for deterministic change intelligence, transactional provenance, and codebase governance. It turns repository edits into impact packets, risk summaries, hotspot rankings, and targeted verification plans.

The tool is designed to stay local and explain its work. It does not act as an autonomous coding agent. Optional ask can use a Gemini HTTP backend (GEMINI_API_KEY) or a local model; Gemini is an optional Ask backend, not the product name.

Existing ledgerful commands, hooks, and .ledgerful/ state directories keep working unchanged. New installs also provide ledgerful and the short ldg alias.

Daily 5

The same default path --help prints for agents:

ledgerful doctor --json
ledgerful change-context --json
ledgerful ledger status --compact
ledgerful search init --auto-index
ledgerful verify --scope fast

First run on an empty git init repo is honest: doctor may create .ledgerful/, change-context can be empty, search can rebuild an empty index, and verify can pass with nothing to map. That sequence is clap-valid; it is not a setup wizard (init / setup / demo live later in this file).

Captured 2026-09-26 with PATH ledgerful 0.2.15 (4fc51f263901) on git init only (execute tree a8ced425). Paths normalized to C:\dev\my-project. JSON is a real excerpt (… marks omitted keys and extra findings).

ledgerful doctor --json:

{
  "schemaVersion": 1,
  "readyForPublish": true,
  "summary": { "block": 0, "warn": 5, "info": 4, "…": "…" },
  "findings": [
    { "code": "graph-empty", "severity": "warn", "message": "Graph state: Empty (never indexed)" },
    { "code": "search-empty", "severity": "warn", "message": "Search index: present but empty (0 documents); full-text search unusable until populated" },
    { "code": "tool-gemini", "severity": "info", "message": "gemini NOT FOUND (optional CLI; not the Cloud Ask backend)" },
    "…"
  ],
  "environment": {
    "workRoot": "C:\\dev\\my-project",
    "binaryVersion": "0.2.15",
    "buildSha": "4fc51f263901"
  },
  "…": "omitted keys"
}

ledgerful change-context --json:

{
  "schemaVersion": 1,
  "status": "empty",
  "summary": "No file changes and no pending ledger transactions.",
  "riskLevel": "low",
  "…": "omitted keys"
}

ledgerful ledger status --compact:

Ledger [C:\dev\my-project]: 0 pending, 0 unaudited drift.

ledgerful search init --auto-index (stdout status lines):

WARN Search index empty after rebuild (0 documents). No indexable content found — check ignore patterns; empty repo or filters may leave the index empty.

ledgerful verify --scope fast quiet success ends with the assurance line, then the trailing pass line. A fmt/clippy-only plan looks like this. A plan that ran cargo nextest run says test commands attempted (case execution unproven) and still leaves the case count unavailable:

Assurance: 2/2 command results (results recorded); test commands not invoked; test-case count unavailable; affected-test completeness not established; exclusions not inventoried.
Verification passed

Install

Windows (PowerShell):

iwr https://raw.githubusercontent.com/Ryan-AI-Studios/Ledgerful/main/install/install.ps1 -UseB | iex

macOS and Linux:

curl -fsSL https://raw.githubusercontent.com/Ryan-AI-Studios/Ledgerful/main/install/install.sh | sh

cargo-binstall (prebuilt GitHub release binary; no crates.io, no full compile when assets match):

cargo binstall --git https://github.com/Ryan-AI-Studios/Ledgerful

Package managers:

• Homebrew: brew install Ryan-AI-Studios/tap/ledgerful
• Scoop: scoop bucket add ledgerful https://github.com/Ryan-AI-Studios/scoop-bucket then scoop install ledgerful
• winget: winget install Ledgerful.Ledgerful (accepted 2026-07-30; community package version may lag engine releases)
• Apt and other distro packages are not planned. Manifests and release-time bump automation live under packaging/; channel details in docs/package-distribution.md.

If ledgerful --version is older than the latest published release, you may have multiple installs on PATH — see the PATH / version FAQ.

Manual install from a checkout (compiles from source):

cargo install --path .

This default install does not embed the dashboard. See docs/installation.md.

The LSP daemon command and usage are optional Cargo features (not on default --help):

cargo install --path . --features daemon

See docs/installation.md for installer options, release assets, package managers, and agent bootstrap instructions.

First-time repo setup

Daily 5 is the day-to-day door. To create .ledgerful/ wiring, index, and a proof loop, see docs/golden-path.md and ledgerful demo. A one-time checkout sequence:

ledgerful init
ledgerful doctor
ledgerful index
ledgerful scan
ledgerful impact
ledgerful verify
ledgerful hotspots
ledgerful ask "What should I verify next?"

ledgerful setup is a guided wizard (welcome → init → doctor → first scan). It is not Daily 5.

Commands

Default-features --help names, in clap order. Hidden variants (bridge, search-trigrams, internal) stay off this table. services, deploy, and observability stay callable and are marked (gated).

daemon and usage are absent from default --help (--features daemon / usage-metrics; install snippet above).

MCP agent install (Top-N platforms)

Wire Ledgerful into supported agent hosts with one command (merge-only; never clobbers foreign MCP servers):

# Detect hosts, or pick one: claude-code | cursor | codex | copilot
ledgerful mcp install
ledgerful mcp install --platform cursor --dry-run --json
ledgerful mcp status --json
ledgerful mcp uninstall --platform cursor

Launcher: --launcher auto (default) prefers a PATH ledgerful binary with args ["mcp"]; falls back to npx -y @ledgerful/mcp-server (Windows prefers npx.cmd) with a pin-lag warning when the binary is missing. Prefer PATH over npx when both exist — published npm may lag the engine.

Written ≠ connected: a successful install updates config files only. Hosts may still require trust/approve prompts (Codex project trust, Claude Code approve, VS Code MCP trust). Reload the host after install.

Bare ledgerful mcp / ledgerful mcp serve still start the stdio server.

Manual / npm wrapper (optional):

npx @ledgerful/mcp-server

The npm wrapper downloads a checksummed GitHub release binary and launches ledgerful mcp. Set LEDGERFUL_MCP_BIN_OVERRIDE to a local binary for development or CI smoke tests.

Federation

Use federated intelligence across sibling repositories:

ledgerful federate export
ledgerful federate scan
ledgerful federate status
ledgerful impact

federate status lists live peers (one row per path; name = folder basename). Run federate scan to refresh discovery and prune dead/self cache rows.

Provenance

Track changes with transactional provenance:

# Start a transaction before editing
ledgerful ledger start src/main.rs --category FEATURE --message "Add auth module"

# After editing and verifying
ledgerful ledger commit --tx-id <id> --summary "Added auth" --reason "API needs authentication"

# Quick single-file change
ledgerful ledger atomic src/config.rs --category REFACTOR --summary "Extract config validation" --reason "SRP"

# Lightweight note for docs changes
ledgerful ledger note docs/api.md "Update endpoint docs"

# Check status and reconcile drift
ledgerful ledger status
ledgerful ledger reconcile --all --reason "Intentional local changes"

# Search and audit (ROLLBACK rows omitted by default; --include-rollback restores)
ledgerful ledger search "auth logic" --category FEATURE --days 30
ledgerful ledger audit --include-unaudited
ledgerful ledger adr --output-dir docs/adr

Configuration

Ledgerful stores repo-local state in .ledgerful/.

• .ledgerful/config.toml: runtime configuration, watch debounce, Ask timeout/context, temporal traversal, hotspot defaults, and ledger settings (enforcement, auto-reconcile, verification gating).
• .ledgerful/rules.toml: policy rules, protected paths, and required verification commands.

Examples live in docs/examples/config.toml, docs/examples/rules.toml, and docs/examples/LEDGERFUL.md.

Reports And State

Generated state is rebuildable and stays inside .ledgerful/.

• .ledgerful/reports/latest-scan.json
• .ledgerful/reports/latest-impact.json
• .ledgerful/reports/latest-verify.json
• .ledgerful/reports/fallback-impact.json
• .ledgerful/state/ledger.db
• .ledgerful/state/schema.json
• .ledgerful/state/current-batch.json

Impact packets are redacted before SQLite persistence. Ask prompts are sanitized and truncated before they leave the process.

Ask (optional Gemini HTTP backend)

Cloud Ask talks to the Gemini API over HTTP using GEMINI_API_KEY (process environment or a repo-local .env; .env is gitignored — use .env.example as the template). The gemini CLI is an optional local tool (doctor code tool-gemini); it is not the Cloud Ask backend.

• By default, routine analyze, suggest, and narrative requests use gemini-3.1-flash-lite.
• High-risk packets and review-patch requests use gemini-3.1-pro.
• Set gemini.model in .ledgerful/config.toml only when you want one explicit model for every ask mode.
• --mode analyze: blast-radius and risk reasoning
• --mode suggest: targeted verification recommendations
• --mode review-patch: patch review with live diff context
• --narrative: senior-architect risk narrative generated from one structured prompt

If Ask fails after an impact packet is available, Ledgerful writes a fallback impact artifact or reports why it could not.

Windows / WSL

• Windows 11 + PowerShell is the primary environment.
• Mixed Windows/WSL filesystem setups can be slower and may produce different tool availability.
• Keep git installed in the environment where you run Ledgerful. The gemini CLI is optional (see Ask above).

Architecture

See docs/architecture.md for module boundaries and current data flow.

Contributing

• Questions and setup help: GitHub Discussions.
• Bug reports: GitHub Issues.
• Security reports: see SECURITY.md — do not file public issues for security vulnerabilities.
• Keep changes phase-bounded and deterministic.
• Run cargo fmt --check, cargo clippy --all-targets --all-features -- -D warnings, and cargo test --all-features -j 1 -- --test-threads=1 before pushing.

License

Ledgerful is source-available under the PolyForm Noncommercial License 1.0.0, with additional permissions for qualified small entities in COMMERCIAL-EXCEPTION.md.

Required Notice: Copyright 2026 Ledgerful, LLC; additional permissions are stated in COMMERCIAL-EXCEPTION.md.