# agnetacount/agentledger architecture

> Architecture diagram of the GitHub repository agnetacount/agentledger, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/agnetacount/agentledger
- Repository: https://github.com/agnetacount/agentledger

## Overview

agentledger is a local, zero-dependency audit trail for AI-agent tool calls. Its main workflow is to capture a tool call, redact or omit sensitive payloads according to capture mode, hash and optionally sign the record, then append it to a JSONL ledger. Users can inspect the ledger through the API or CLI, compute statistics, create checkpoints, and verify integrity offline. The excerpts show the principal calls and file operations; README statements support documented capabilities such as wrapping tool functions and CLI tail/export commands.

Main entry points: [`src/ledger.ts`](https://github.com/AgnetAcount/agentledger/blob/main/src/ledger.ts) (Ledger and wrap), [`src/verify.ts`](https://github.com/AgnetAcount/agentledger/blob/main/src/verify.ts) (Ledger verification), [`src/cli.ts`](https://github.com/AgnetAcount/agentledger/blob/main/src/cli.ts) (CLI commands), [`src/index.ts`](https://github.com/AgnetAcount/agentledger/blob/main/src/index.ts) (Public API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_public_api["Public API<br/>[index.ts]"]
  node_cli_launcher["CLI launcher<br/>[agentledger.js]"]
  node_cli["CLI commands<br/>[cli.ts]"]
end

subgraph group_capture["Record capture"]
  node_ledger["Ledger and wrap<br/>[ledger.ts]"]
  node_redaction["Secret redaction<br/>[redact.ts]"]
end

subgraph group_integrity["Integrity and reporting"]
  node_canonical["Canonical JSON<br/>[canonical.ts]"]
  node_crypto["Hash and HMAC<br/>[crypto.ts]"]
  node_verification["Ledger verification<br/>[verify.ts]"]
  node_checkpoints["Checkpoint creation<br/>[verify.ts]"]
  node_statistics["Ledger statistics<br/>[stats.ts]"]
end

subgraph group_storage["Local persistence"]
  node_fileio["Secure file I/O<br/>[fileio.ts]"]
  node_ledger_file[("JSONL ledger")]
end

node_api_user(("API caller"))
node_cli_user(("CLI user"))

node_api_user -->|"uses API"| node_public_api
node_public_api -->|"creates ledger"| node_ledger
node_public_api -->|"exports verification"| node_verification
node_public_api -->|"exports statistics"| node_statistics
node_cli_user -->|"runs commands"| node_cli_launcher
node_cli_launcher -->|"runs CLI"| node_cli
node_ledger -->|"redacts payloads"| node_redaction
node_ledger -->|"canonicalizes records"| node_canonical
node_ledger -.->|"hashes records"| node_crypto
node_ledger -->|"reads and appends"| node_fileio
node_fileio -.->|"reads and writes"| node_ledger_file
node_ledger -->|"verifies ledger"| node_verification
node_ledger -.->|"computes stats"| node_statistics
node_cli -->|"reads and writes"| node_fileio
node_cli -->|"verifies ledger"| node_verification
node_cli -->|"computes stats"| node_statistics
node_cli -->|"builds checkpoint"| node_checkpoints
node_verification -->|"reads ledger file"| node_fileio
node_verification -->|"canonicalizes for checks"| node_canonical
node_verification -->|"checks hashes and signatures"| node_crypto
node_checkpoints -->|"signs checkpoint"| node_crypto

click node_public_api "https://github.com/AgnetAcount/agentledger/blob/main/src/index.ts"
click node_cli_launcher "https://github.com/AgnetAcount/agentledger/blob/main/bin/agentledger.js"
click node_cli "https://github.com/AgnetAcount/agentledger/blob/main/src/cli.ts"
click node_ledger "https://github.com/AgnetAcount/agentledger/blob/main/src/ledger.ts"
click node_redaction "https://github.com/AgnetAcount/agentledger/blob/main/src/redact.ts"
click node_canonical "https://github.com/AgnetAcount/agentledger/blob/main/src/canonical.ts"
click node_crypto "https://github.com/AgnetAcount/agentledger/blob/main/src/crypto.ts"
click node_verification "https://github.com/AgnetAcount/agentledger/blob/main/src/verify.ts"
click node_checkpoints "https://github.com/AgnetAcount/agentledger/blob/main/src/verify.ts"
click node_statistics "https://github.com/AgnetAcount/agentledger/blob/main/src/stats.ts"
click node_fileio "https://github.com/AgnetAcount/agentledger/blob/main/src/fileio.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_public_api,node_cli_launcher,node_cli,node_cli_user toneBlue
class node_ledger,node_redaction toneAmber
class node_canonical,node_crypto,node_verification,node_checkpoints,node_statistics,node_api_user toneMint
class node_fileio,node_ledger_file toneRose
```

## Components

### Entry points

- [Public API](https://github.com/AgnetAcount/agentledger/blob/main/src/index.ts): `src/index.ts`
- [CLI launcher](https://github.com/AgnetAcount/agentledger/blob/main/bin/agentledger.js): `bin/agentledger.js`
- [CLI commands](https://github.com/AgnetAcount/agentledger/blob/main/src/cli.ts): `src/cli.ts`

### Record capture

- [Ledger and wrap](https://github.com/AgnetAcount/agentledger/blob/main/src/ledger.ts): `src/ledger.ts`
- [Secret redaction](https://github.com/AgnetAcount/agentledger/blob/main/src/redact.ts): `src/redact.ts`

### Integrity and reporting

- [Canonical JSON](https://github.com/AgnetAcount/agentledger/blob/main/src/canonical.ts): `src/canonical.ts`
- [Hash and HMAC](https://github.com/AgnetAcount/agentledger/blob/main/src/crypto.ts): `src/crypto.ts`
- [Ledger verification](https://github.com/AgnetAcount/agentledger/blob/main/src/verify.ts): `src/verify.ts`
- [Checkpoint creation](https://github.com/AgnetAcount/agentledger/blob/main/src/verify.ts): `src/verify.ts`
- [Ledger statistics](https://github.com/AgnetAcount/agentledger/blob/main/src/stats.ts): `src/stats.ts`

### Local persistence

- [Secure file I/O](https://github.com/AgnetAcount/agentledger/blob/main/src/fileio.ts): `src/fileio.ts`
- **JSONL ledger**

### Other components

- **API caller**
- **CLI user**

## Connections

- API caller → Public API: uses API (evidence: `README.md`)
- Public API → Ledger and wrap: creates ledger (evidence: `src/index.ts`)
- Public API → Ledger verification: exports verification (evidence: `src/index.ts`)
- Public API → Ledger statistics: exports statistics (evidence: `src/index.ts`)
- CLI user → CLI launcher: runs commands (evidence: `README.md`)
- CLI launcher → CLI commands: runs CLI (evidence: `bin/agentledger.js`)
- Ledger and wrap → Secret redaction: redacts payloads (evidence: `src/ledger.ts`)
- Ledger and wrap → Canonical JSON: canonicalizes records (evidence: `src/ledger.ts`)
- Ledger and wrap → Hash and HMAC: hashes records (evidence: `src/ledger.ts`)
- Ledger and wrap → Secure file I/O: reads and appends (evidence: `src/ledger.ts`)
- Secure file I/O → JSONL ledger: reads and writes
- Ledger and wrap → Ledger verification: verifies ledger (evidence: `src/ledger.ts`)
- Ledger and wrap → Ledger statistics: computes stats (evidence: `src/ledger.ts`)
- CLI commands → Secure file I/O: reads and writes (evidence: `src/cli.ts`)
- CLI commands → Ledger verification: verifies ledger (evidence: `src/cli.ts`)
- CLI commands → Ledger statistics: computes stats (evidence: `src/cli.ts`)
- CLI commands → Checkpoint creation: builds checkpoint (evidence: `src/cli.ts`)
- Ledger verification → Secure file I/O: reads ledger file (evidence: `src/verify.ts`)
- Ledger verification → Canonical JSON: canonicalizes for checks (evidence: `src/verify.ts`)
- Ledger verification → Hash and HMAC: checks hashes and signatures (evidence: `src/verify.ts`)
- Checkpoint creation → Hash and HMAC: signs checkpoint (evidence: `src/verify.ts`)