Chronicle

Real behavior.Replayable evidence.

Record what an application actually does. Chronicle writes captured evidence to a durable local WAL, turns it into a canonical session, and replays it against an explicitly authorized loopback target.

Read the docsView source

Current surfaceLinux · plaintext HTTP/1.1 · local filesystem

observed trafficdurable boundaryauthorized target
One path from observed traffic to an explicitly authorized replay.

One path from observed traffic to an explicitly authorized replay. Capture → WAL → ETL → Canonical session → Replay

Real traffic is already regression-test evidence.

Hand-written fixtures describe what someone remembered to encode. Chronicle starts with behavior that happened: socket evidence, ordered bytes, and protocol-level request/response relationships. No application probes. No production destination carried into replay.

Capture around the workload, not inside its source.

From traffic to a recording you can carry.

Each handoff has one job. Capture observes. WAL makes the durable prefix authoritative. ETL reconstructs. The canonical model removes capture and storage mechanics from replay.

  1. Capture

    Attach to a supervised command, process, or cgroup. Chronicle observes socket lifecycle and plaintext payload evidence without application instrumentation.

    socket → evidence

  2. WAL

    Append evidence to segmented WAL v1. A commit marker and sync establish what downstream processing is allowed to trust after interruption.

    append → commit

  3. ETL

    Read the recovered committed prefix, reconstruct bounded HTTP/1.1 sessions, account for loss, and publish one deterministic canonical session per finalized epoch.

    recover → transform

  4. Canonical session

    Persist a protocol- and storage-independent recording with connections, operations, completeness, integrity, and replay attributes.

    publish → inspect

  5. Replay

    Plan first. Execute only against an authorized loopback target; explicit-target mode stays dry-run until `--execute`. Recorded production destinations are never a fallback.

    plan → verify

Durability before interpretation. Authorization before effects.

Durability is part of capture.

The WAL is not an internal queue that can disappear when a later stage crashes. Recovery treats the last valid in-WAL commit marker as authority; ETL works from that boundary.

Replay is deliberately harder than capture.

A plan can be inspected without sending traffic. Explicit-target execution requires loopback mapping, host agreement, effect authorization, and `--execute`; writes additionally require `--allow-write`.

Use the CLI you already have.

The shortest useful path is visible in the command surface. Start with a readiness check, record a workload, inspect the result, then replay into a fresh supervised copy.

chronicle / public commands

$ chronicle doctor
$ chronicle record --name checkout -- ./my-app
$ chronicle list
$ chronicle inspect checkout
$ chronicle replay checkout -- ./my-app

Commands below are the current public 0.1.x interface. Output is intentionally omitted; use `--format json` when a machine-readable contract is needed.

Small surface. Clear limits.

Works today

Live Linux capture for bounded plaintext HTTP/1.1; fixture recording on any platform; local filesystem recordings; safe loopback replay; `doctor` readiness probes.

Not implemented

TLS decryption, HTTP/2+, PostgreSQL/S3 persistence, encryption at rest, comprehensive redaction, Docker packaging, and Kubernetes packaging.

Read the boundary before you run the command.

Chronicle is early, runnable software. The docs keep the safe path, operational bounds, and exact CLI contract close at hand.

Open documentationGitHub repository