flightrec 0.2.2

Git-like filesystem observability for AI agents. Snapshots, diffs, and narratives of what actually happened.

Why

AI agents narrate their intent, not their actions. There is a difference. An agent may log "refactoring the auth module" while it deletes a config file, rewrites a test fixture, and leaves a half-edited function in place. The narrative is a summary the agent wrote about itself.

The filesystem does not have this problem. Every create, modify, and delete leaves an objective record. Content-addressed blobs do not lie about what changed, and a unified diff does not editorialize.

flightrec sits outside the agent. It requires no SDK, no tracing call, and no cooperation from the code under observation. It watches directories, snapshots file state, computes diffs, and optionally asks an LLM to narrate what it found — from the filesystem's perspective, not the agent's.

The result is a structured, replayable record of what your agent actually did.

Quickstart

Install

cargo install flightrec

Initialize

$ flightrec init --root ~/my-agent
Config written to ~/.flightrec/config.toml

Next steps:
  flightrec watch --once   # take a snapshot of your watch roots
  flightrec tui            # explore recorded diffs in the TUI

Take a baseline snapshot

$ flightrec watch --once
[2026-06-12T19:17:24.413557+00:00] snapshot 20260612T191724-413 — 0 files → ~/.flightrec/snapshots/20260612T191724-413.json

Make a change, capture it

$ echo 'Planning to refactor auth module' > ~/my-agent/notes.md

$ flightrec watch --once
[2026-06-12T19:17:24.425324+00:00] snapshot 20260612T191724-425 — 1 files → ~/.flightrec/snapshots/20260612T191724-425.json
  1 changes:
    + ~/my-agent/notes.md

Replay what happened

$ flightrec replay
[2026-06-12T19:17:24.425554+00:00] diff-20260612T191724-425 — 1 changes
  [Added] ~/my-agent/notes.md

For an interactive view of the full timeline: flightrec tui

Features

How it works

The watch loop takes a snapshot of each configured root, computes a diff against the previous snapshot, persists both to $FLIGHTREC_HOME, and optionally calls an LLM provider to summarize the changes. Storage is content-addressable: blobs are written once and deduplicated by SHA-256 hash, git-style.

Full pipeline, storage layout, and data schemas: docs/architecture.md

Configuration

flightrec init writes a starter config.toml in $FLIGHTREC_HOME (default ~/.flightrec).

[watch]
roots = ["~/my-agent"]

[filter]
include = ["**/*.md", "**/*.rs", "**/*.toml", "**/*.json"]
exclude = ["**/.git/**", "**/target/**", "**/node_modules/**"]

[daemon]
interval_seconds = 60

[llm]
enabled = false
provider = "anthropic"
model = "claude-haiku-4-5"

Full reference: docs/config-reference.md — runnable examples: examples/

Positioning

flightrec records ground truth without touching the agent.

Examples

Development

cargo fmt --all --check && cargo clippy --all-targets -- -D warnings && cargo test --all-targets

Development workflows are defined as executable skills in skills/ (Skills-Driven Development).

ROADMAP.md · CONTRIBUTING.md · SECURITY.md · LICENSE