RepoCodex

Git-native why next to code — with a pin check that proves it still matches.

Coding agents write syntax well and forget why. Comments rot. Instruction files (CLAUDE.md, AGENTS.md, Cursor rules) never prove they still describe live text. Tests check behavior you remembered to assert; they do not keep institutional why attached to the lines that implement it.

RepoCodex stores that why in git beside the code. Agents retrieve it before they edit. A deterministic pin check (ripgrep + git) attests the attachment. Built for repositories where coding agents make the changes.

demo.mp4

Not a test suite. Not another instruction file. Not a linter.

Experimental. Requires Python 3.11+ and ripgrep (rg) on PATH.

Install

pip install "repocodex==<engine_version>"
# or from a local clone: pip install -e .
repocodex install

repocodex install writes the pre-commit hook, GitHub Action, agent skills, and .repocodex.toml pinned to the installed package (ENGINE_VERSION). Hook, local CLI, and CI must run that same version. The product is that loop: agents retrieve stored why before they edit, so they do not silently break existing behavior; the pin check fails the turn when why and code diverge, and a first substantive edit of an uncovered file is denied until a pinning concept is written.

repocodex context src/billing/PaymentGateway.ts   # retrieve why before edit
repocodex validate --diff                         # attest pins still hold

Pin the engine in .repocodex.toml. Hook, local CLI, and CI resolve that pin so verdicts agree.

What a concept looks like

Types are orthogonal — one change may write more than one. Three common shapes:

TechnicalDecision (decisions/…) — why this construct exists:

---
title: Capture streams enterprise retries instead of buffering
type: TechnicalDecision
verification:
  engine: ripgrep
  anchors:
    - path: src/billing/PaymentGateway.ts
      all_of: ["yield", "ENTERPRISE", "capturePayment"]
---
Enterprise capture is a generator so retries stay backpressure-aware. Do not
replace with an in-memory list of attempts.

InvariantContract (invariants/…) — must-hold token (requires claims):

---
title: Enterprise capture grace is three attempts
type: InvariantContract
verification:
  engine: ripgrep
  anchors:
    - path: src/billing/PaymentGateway.ts
      all_of: ["ENTERPRISE", "grace", "= 3"]
claims:
  - subject: enterprise_grace_attempts
    literal: "3"
---
Enterprise plans get three capture retries before failure. Do not silently shrink this window.

BusinessWorkflow (workflows/…) — thin cross-package flow (one anchor per site):

---
title: Checkout capture flows api → billing → ledger
type: BusinessWorkflow
verification:
  engine: ripgrep
  anchors:
    - path: src/api/checkout.ts
      all_of: ["capturePayment", "billing"]
    - path: src/billing/PaymentGateway.ts
      all_of: ["capturePayment", "ledger"]
    - path: src/ledger/posting.ts
      all_of: ["postCapture", "idempotency"]
---
Checkout capture crosses api, billing, then ledger. Keep that order; do not
post to the ledger from the API layer.

Docs

Doc	Job
How it works	Purpose, benefit, and the retrieve → read → edit → update why → pin-check loop
Memory	How to read .context/
Agents	How coding agents (and optionally humans) run the loop
Install	CLI, pin, hook, GitHub Action, optional MCP
Architecture	Current engine architecture (further reading)

License and contributing

MIT · Contributing · Security

Created by Ajay Lamba.