agentleFS
bonez-iobonez-io/re_gent/CLAUDE.md

re_gent

CLAUDE.md4 starsChanged 6 months agoApache-2.0View on GitHub

Version control for AI agents. A content-addressed, DAG-based version control system that captures what an agent did, why (which prompt), and lets you blame, log, and inspect steps across sessions. This document is the project's source of truth for context, vocabulary, and architectural decisions. It is the first file Claude (or any contributor) should read when working in this repo. Today, AI coding agents have no version control of their own. Devs have built workarounds: We gave agents write access…

  • Installs packages

The file

We split this CLAUDE.md into the rules it gives an agent

6 rules. About 0 are common, 5 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Keep Claude Code and Codex capture behavior aligned through internal/capture.

    line 205
  2. Distinctive:

    Add focused tests before extending hook payload handling or schema shape.

    line 206
  3. Distinctive:

    When working on this project:

    line 234
  4. Distinctive:

    Content addressing is the design discipline: When in doubt about whether two objects should be the same, ask: do they have identical bytes?

    line 239
  5. Distinctive:

    CAS for refs, transactions for SQLite: Never write a ref without compare-and-swap.

    line 240
  6. Distinctive:

    Tests over commentary: When implementing behavior, add focused tests next to the source.

    line 241

≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

re_gent

Version control for AI agents. A content-addressed, DAG-based version control system that captures what an agent did, why (which prompt), and lets you blame, log, and inspect steps across sessions.

This document is the project's source of truth for context, vocabulary, and architectural decisions. It is the first file Claude (or any contributor) should read when working in this repo.


Mission

Today, AI coding agents have no version control of their own. Devs have built workarounds:

  • /compact and pray
  • copy-pasting code into a fresh chat
  • screenshotting the "good" version before it changes
  • "that was working five minutes ago"
  • "go back to before the refactor"
  • "why did you change that file"
  • "i told you this already"

We gave agents write access to our codebases. We did not give ourselves git for it.

re_gent provides three primitives that should already exist for every agent-driven workflow:

  • blame — which prompt produced this line of code?
  • log — what did this session actually do, in causal order?
  • show — inspect the full tool and conversation context for any step.

These three turn the agent's activity into something inspectable and shareable. They also unlock the next layer (branch, merge, rewind, multi-session orchestration) once the foundation is solid.


Tool & CLI

  • Project name: re_gent
  • CLI binary: rgt (3 chars, ergonomic)
  • Storage directory: .regent/ at the project root (analogous to .git/)
  • License: Apache 2.0 — see LICENSE

The conceptual model in 90 seconds

Four primitive object types, three immutable and content-addressed:

  1. Blob — raw bytes (file content, message body, JSON payload). Identified by blake3(content). Identical content stores once (free dedupe).
  2. Tree — { path → blob_hash, blame_hash } map describing the workspace at one moment. Itself a blob.
  3. Step — analogous to a git commit. { parent, tree, transcript, causes, session_id, origin, turn_id, ... }. Itself a blob. Auto-generated by hooks, never hand-authored.
  4. Ref — the only mutable object. A named pointer (e.g. refs/sessions/<session_id>) holding a step hash.

Steps form a DAG through parent pointers. Each session has its own ref (its own branch tip). The DAG itself is shared across sessions: common ancestors dedupe and divergent work lives on parallel branches. Secondary-parent merge points are planned but not implemented yet.

The workspace on disk is shared across sessions by default. re_gent records each session's view of the workspace, but it does not currently isolate writes or resolve same-file conflicts between live agents. Use separate directories, git worktrees, or normal Git workflows when physical isolation matters.


Architectural decisions (with rationale)

Reimplement, don't fork git

We considered three options:

  1. Fork git's source. Rejected. Git is a 25-year-old C codebase with a deeply opinionated commit format. Adding our extra fields (transcript, cause, session_id) means either jamming JSON into commit messages (ugly, slow, fragile) or modifying the object format (permanent fork, can't pull upstream changes). Almost every git fork has died.
  2. Use git as a library underneath (libgit2, isomorphic-git). Rejected for v1. We'd still be expressing our model through git primitives, forcing awkward translations. Fine if the goal were to be a git client; we're building something different.
  3. Reimplement from scratch in a modern language. Chosen. The git data model itself is small (~1–2k lines in any modern language). Our differences are fundamental enough — Step has more fields, Transcript object doesn't exist in git, sessions/agents are first-class — that having full design freedom is worth the cost. We get modern hashing (BLAKE3 vs SHA-1), single-binary distribution, and zero coupling to git internals.

Go as the implementation language

Chosen for: gentle learning curve relative to Rust, single static binary distribution, excellent tooling, strong stdlib for I/O and concurrency. Reference projects in the same niche (Docker, Kubernetes, Hugo, GitHub CLI, Prometheus) all chose Go for the same reasons. If a hot path eventually needs Rust-level performance, individual modules can be swapped to Rust later via cgo or as separate processes.

BLAKE3 for hashing

Faster than SHA-256, parallelizable, modern security margin. Pure-Go implementation available (lukechampine.com/blake3). 256-bit output, hex-encoded.

Object store and index responsibilities

The object store and refs on disk are canonical for step, tree, blob, blame, and ref state. SQLite owns the current normalized conversation rows, message-to-step links, session metadata, and query indexes used by log, show, and sessions. Raw transcript snapshots are also stored as blobs when the host exposes a transcript path, but they are not available for every host/event.

Some hook recovery paths can repair missing index rows for recorded steps; a full rgt reindex command is still planned. This split means:

  • Storage layer stays simple (just files in objects/aa/aabbcc...)
  • Query layer can evolve independently for derived step/file views
  • Backup/sync of recorded workspace state is objects/ + refs/, while current conversation views also require index.db or archived raw transcripts

Per-session branches, shared workspace

The DAG has multiple tips, one per active session. Refs at refs/sessions/<origin>:<escaped-session-id> are independent. Steps from different sessions live in the same object store; common ancestors dedupe naturally.

The disk is not isolated per session by default — multiple Claude Code or Codex sessions can write to the same project directory, and re_gent's hooks capture each session's view independently. This matches how people often run concurrent agents today, but file-level conflict detection and resolution are not implemented yet.

Worktrees-per-session remain a planned escape hatch for cases that need true physical isolation: long autonomous runs, sessions with different env/dependency setups, or genuinely contested files.

Annotated-blob blame (compute at write time, not query time)

Two viable blame algorithms:

  • On-demand: walk steps backward, diff each adjacent tree's version of the file, attribute lines as you go. O(history depth) per query. Simple but slow.
  • Annotated: at write time, compute per-line provenance and store as a sidecar BlameMap blob next to each (step, file) entry. O(1) blame queries.

Chosen: annotated. Storage cost is bounded (per-line hash arrays compress well, can be RLE-encoded later) and blame becomes a single object lookup.

Which derived data is stored and which is recomputed. The two commands that read a diff read it at different times, and the difference decides what a bug in the diff costs:

CommandWhen the diff runsWhat a diff fix reaches
rgt showQuery time (internal/treediff calls LineDiff per invocation)Every step, immediately — rebuilding the binary is the whole fix
rgt blameWrite time (sidecar per (step, file), written during capture)Only steps recorded after the fix; maps already on disk keep whatever the old diff believed

That asymmetry is the price of O(1) blame, and it is why rgt repair blame exists: it walks each session ref from its root and rewrites every stored blame map with the current diff, leaving history, workspace, and every canonical object untouched. It is the remedy for the LineDiff bug that named the line after the one an edit changed — the alternative was deleting .regent/, which is not a remedy. Repair is idempotent (a map that already matches is not rewritten) and safe to interrupt (sidecars are written atomically; a cancelled run is re-runnable, not resumable, because a step's blame is derived from its parent's).

Any future change to the diff or to ComputeBlame inherits this: it fixes show on rebuild and requires a rgt repair blame for blame.

Conversation capture

We store conversation metadata alongside the file state. Current Claude and Codex hooks write normalized message rows into the SQLite index, store tool payloads as content-addressed blobs, and keep raw agent transcript snapshots as blobs when the host exposes a transcript path. Older data may still use the chained Transcript blob: { prev: hash, new_messages: [hash...] }.

Hosts only hand us the final assistant message of a turn, so the narration and reasoning produced between tool calls is recovered by reading the host transcript. Every assistant text and reasoning block becomes a message row (message_type of assistant or reasoning) with a deterministic id derived from its identity and text, which makes the scan idempotent — it runs on each tool batch and again at Stop without duplicating rows. rgt show renders reasoning under a dimmed Reasoning: label.

This makes re_gent robust to host transcript churn: even if the live JSONL is rewritten or wiped, the SQLite index plus the content-addressed object store keep captured step context reconstructable. Because assistant and reasoning blocks are captured eagerly, a later /compact or /clear cannot take back what was already recorded.

Hook-driven capture

re_gent is invoked by agent-host hooks. Claude Code uses UserPromptSubmit, PostToolBatch, and Stop; Codex uses SessionStart, UserPromptSubmit, PostToolUse, and Stop. Hooks are thin adapters into the shared capture service: normalize payloads, store messages/tool blobs, snapshot workspace on turn completion, write a step, and CAS the session ref forward.

Other agent tools can add small adapters that produce the same internal capture events. The shared engine handles storage, indexing, snapshots, blame, and transcript archives.


Vocabulary

TermMeaning
StepThe unit of recorded agent action. Roughly equivalent to a git commit, but auto-generated per tool-using turn and carrying conversation + cause references.
CauseOne tool call in a step: { tool_use_id, tool_name, args_blob, result_blob }. A step may have multiple causes.
TreeA snapshot of the workspace at one step. { path → (blob_hash, blame_hash, mode) }.
BlameMapA parallel array to a file's lines, where each entry is the step hash that introduced or last modified that line.
TranscriptLegacy chained delta object: pointer to previous transcript + list of new message blob hashes. Current hooks primarily use SQLite messages plus optional raw transcript archive blobs.
UsageThe API accounting attached to a step: input/output tokens, cache-creation and cache-read tokens, and API-call count, read from the host transcript (including subagent transcripts, recursively). Stored per step as a delta plus the cumulative reading the next step measures against.
EffectAn "uncompensated side effect" attached to a step — something that happened (HTTP call, db write) that a rewind cannot undo. Logged for transparency.
SessionA continuous stream of agent activity from one host (one Claude Code process, one SDK run). Has its own ref (branch).
AgentAn identity within a session. Sub-agents (e.g. spawned via Task tool) get their own agent_id but share session lineage.
HookThe integration point with the agent host. Claude and Codex adapters normalize host payloads into shared capture events.
Object storeThe content-addressed blob directory at .regent/objects/. Source of truth for recorded workspace state and payload blobs.
IndexThe SQLite database at .regent/index.db. Stores query indexes, sessions, normalized conversation rows, and message-to-step links.
WorktreeA planned per-session physical working directory for cases needing true filesystem isolation between concurrent sessions.

Technical stack

  • Language: Go 1.22+
  • Hashing: BLAKE3 (lukechampine.com/blake3)
  • CLI framework: Cobra (github.com/spf13/cobra)
  • Diff: github.com/sergi/go-diff (Myers + line-mode)
  • Gitignore parsing: github.com/sabhiram/go-gitignore
  • SQLite: modernc.org/sqlite (pure Go, no CGO)
  • Config: TOML (github.com/pelletier/go-toml/v2)
  • Build: single static binary, no CGO required
  • Distribution (planned): homebrew, cargo install-style, GitHub Releases

Reference projects

These are projects worth reading the source of when designing or implementing parts of re_gent. Read, don't fork.

  • Jujutsu (jj) — https://github.com/jj-vcs/jj. From-scratch git-compatible VCS in Rust. Excellent reference for the shape of building a from-scratch object model. Their handling of operation logs (a parallel concept to our Step lineage) is particularly relevant.
  • isomorphic-git — https://github.com/isomorphic-git/isomorphic-git. Pure TypeScript reimplementation of git's data model. The codebase is small enough to read in a weekend and demystifies how little code the core actually needs.
  • gitoxide — https://github.com/Byron/gitoxide. Pure-Rust git implementation. Useful for understanding atomic operations, ref management, and pack file design (relevant when we eventually need GC).
  • libgit2 — https://libgit2.org/. C library for git operations. Useful as a reference for object encoding and edge cases.
  • Pijul — https://pijul.org/. Patch-based VCS with a fundamentally different theoretical foundation. Worth reading their docs on patch theory if we ever consider a non-snapshot model.
  • Mercurial — https://www.mercurial-scm.org/. Alternative to git with cleaner internals in places. Their handling of revsets is interesting for query design.

For the AI agent / observability side:

  • OpenTelemetry semantic conventions — useful framing for thinking about Step + Cause + Effects as a kind of trace.
  • Claude Code and Codex hook documentation — the host integration points we depend on. Host payloads should stay confined to adapter code.

Status

Active development. Core storage, hook capture, log, blame, show, sessions, and init are implemented. Claude Code and Codex are the reference host integrations.

Current artifacts:

  • README.md — user-facing overview and install notes.
  • TESTING.md — current manual and automated verification guide.
  • CLAUDE.md — this architecture context.
  • docs/server-mode.md — server mode: the consistency guarantee, the offline queue, and the failure-mode table. Read this before changing anything in internal/remote or the server-mode paths in internal/capture.

Server mode is the alternative to the local-first model described above: when a server URL and repo id are configured, the server is the source of truth, the repository keeps only its small .regent/config.toml binding, and internal/store is backed by a disposable machine-local cache outside the workspace. Capture spools to that cache when the server is unreachable so a live agent turn is never blocked. Local mode remains the default and is unchanged.


Next concrete steps

  1. Keep Claude Code and Codex capture behavior aligned through internal/capture.
  2. Add focused tests before extending hook payload handling or schema shape.
  3. Implement missing advanced commands (fork, rewind, reindex) only when their storage semantics are explicit.
  4. Improve snapshot performance for large repositories without weakening blame correctness.

Open design questions

These are real design tensions we have not yet resolved. Flag them when relevant to the work being done:

  1. Bash side-effect attribution. A single Bash tool call can produce arbitrary file changes. We snapshot after, so files are captured correctly, but blame becomes coarse: every line introduced by find . -delete or a multi-file sed -i gets attributed to a single step. Acceptable for v0; may want finer-grained tracking later (filesystem watcher during the bash exec).
  2. Sub-agent lineage. Codex sub-agents and forked threads are captured as separate sessions today. The schema records session fork metadata, but secondary-parent step linking is not implemented.
  3. Conversation rewind into the live agent. rgt rewind is not implemented. When it is, the file state and live agent transcript semantics must be designed together.
  4. Performance on monorepos. Snapshotting every step works for small/medium repos but will hurt on 50k-file monorepos. Optimization candidates: incremental snapshots (track inode mtimes via the index), bloom filters for "did this directory change," or watchman-style integration. v0 ignores this; v1 must address.
  5. Garbage collection. Non-destructive rewinds and abandoned exploration branches accumulate orphan steps. We need an analog of git gc and git reflog with grace periods. Out of scope for v0 but the storage layout should not preclude it (which it doesn't — content-addressed objects are trivially GCable by reachability).
  6. Cross-repo / monorepo subtree handling. Some users have multiple agent-driven projects in nested directories. Whether .regent/ should support subtree boundaries (like git submodule) is an open question.
  7. Multi-tool unification. Claude Code and Codex now share the same capture engine. Future adapters should preserve the same origin, session_id, and turn_id invariants.

Working notes for Claude

When working on this project:

  • Read current code before writing implementation code. Older design docs may lag the implementation; internal/capture, internal/store, and internal/index are authoritative for current behavior.
  • Keep canonical boundaries explicit. Steps, trees, refs, blame, and payload blobs go through the object store. Normalized conversation rows and message links live in SQLite, with raw transcript blobs archived when available.
  • Never break the user's agent. Hooks run during agent turns. If .regent/ doesn't exist, exit cleanly; if non-critical archival or blame work fails, log to .regent/log/ without interrupting the agent.
  • Content addressing is the design discipline. When in doubt about whether two objects should be the same, ask: do they have identical bytes? If yes, they should hash to the same value and store once.
  • CAS for refs, transactions for SQLite. Never write a ref without compare-and-swap. Never write a multi-row index update outside a transaction.
  • Tests over commentary. When implementing behavior, add focused tests next to the source. The tests are the spec made concrete.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.