Agent Run Ledger

Local-first run history and reporting for AI agents, scripts, and automation workflows.

Most AI automation projects start as a pile of prompts, scripts, screenshots, and half-remembered fixes. Agent Run Ledger gives each run a simple audit trail: what was attempted, which steps passed, what failed, how long it took, what artifacts were produced, and what should be checked next.

It is intentionally small:

• no cloud account required
• no database setup
• plain JSONL storage
• readable HTML reports
• useful for LLM agents, content pipelines, browser automation, and internal tools

Why This Exists

AI workflows are easy to demo and hard to keep stable. The painful part is usually not the first prompt. It is answering basic questions later:

• Which run produced this result?
• What input was used?
• Where did the pipeline fail?
• How much time did the agent spend on each step?
• Which artifacts were created?
• Is the workflow getting more reliable over time?

Agent Run Ledger is a lightweight way to keep those answers close to the project.

Quick Start

cd agent-run-ledger
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .

agent-ledger record examples/content_pipeline_run.json
agent-ledger report --open

The report is written to reports/agent-run-report.html.

Architecture

See docs/architecture.md for the internal flow and extension points.

Example Run File

{
  "name": "daily-content-pipeline",
  "workflow": "ai-visual-production",
  "status": "success",
  "started_at": "2026-04-28T09:00:00",
  "finished_at": "2026-04-28T09:08:30",
  "summary": "Generated, checked, and exported a batch of visual materials.",
  "tags": ["python", "stable-diffusion", "automation"],
  "metrics": {
    "items_in": 24,
    "items_out": 24,
    "manual_minutes_saved": 160
  },
  "steps": [
    {
      "name": "load input",
      "status": "success",
      "duration_sec": 12,
      "details": "Loaded source data from CSV."
    }
  ],
  "artifacts": [
    {
      "name": "final batch",
      "path": "output/final_batch.zip",
      "type": "archive"
    }
  ]
}

CLI

agent-ledger record examples/content_pipeline_run.json
agent-ledger list
agent-ledger report
agent-ledger report --workflow ai-visual-production --open

Good Use Cases

• AI content production pipelines
• Telegram or browser automation bots
• LLM agent prototypes
• SEO or data enrichment workflows
• Internal scripts that need a readable run log

Design Notes

The tool uses boring storage on purpose. JSONL is easy to inspect, commit, sync, archive, or import somewhere else later. The report is static HTML, so it can be opened locally or attached to a task without running a server.

Engineering Decisions

• JSONL instead of a database for simple local inspection and append-only history.
• Static HTML reports so the output can be shared without running a service.
• Standard-library tests to keep setup light.
• No required LLM provider because the ledger should work with any agent or script.

Roadmap

• diff two workflow runs
• cost tracking for LLM calls
• prompt/version metadata
• screenshot and artifact gallery
• GitHub Actions summary export
• optional FastAPI dashboard