<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="assets/wordmark-dark.png"> <source media="(prefers-color-scheme: light)" srcset="assets/wordmark-light.png"> <img alt="lockwire" src="assets/wordmark-light.png" width="420"> </picture> </p>

lockwire

Catch stale CLAUDE.md, AGENTS.md, and docs before your coding agent acts on them.

The mark is literal, not a metaphor: lockwiring is the aviation-maintenance technique of threading wire through two fasteners so neither can work loose under vibration — the same idea applied to a doc claim and the code it depends on.

A sentence in your docs is a claim about a specific state of your code. Nothing binds the two together, so the claim rots and nobody notices — until an autonomous agent reads the stale sentence and acts on it. lockwire fingerprints the code a claim depends on, checks that fingerprint at write time inside Claude Code and Codex, and keeps a tamper-evident history of every time the claim broke.

$ lockwire check
CLAUDE.md
  DRIFTED   src/auth/session.ts#createSession (sig)

2 anchors · 1 ok · 1 drifted · 0 orphaned
single-hash would flag 1 · lockwire flagged 1 · noise −0%

$ lockwire history k7q2m9xv
2026-09-25T10:00:11.579Z  anchor.created
2026-09-25T14:12:03.656Z  anchor.drifted       sig
2026-09-25T14:15:40.726Z  anchor.resolved       re-stamped via link

Each event records which tier moved, the commit it happened on, and who ran the check that noticed (the agent and session for a hook, the person or CI job for the CLI) — see docs/ledger.md.

---

The problem, specifically

1. Coding agents change code faster than humans reconcile prose. Drift that used to accumulate over quarters now accumulates over an afternoon.
2. CLAUDE.md and AGENTS.md are read by an agent on every request. A stale line doesn't just mislead a person reading it later — it silently redirects an autonomous process right now. Stale agent context is a correctness problem, not a hygiene problem.
3. Wrong documentation is worse than no documentation. Macke & Doyle (NAACL 2024) found that incorrect documentation "can greatly hinder" an LLM's ability to understand code, while missing documentation barely affects it at all — see docs/research.md. A confidently wrong CLAUDE.md is actively harmful in a way an empty one isn't.

And the tools built to fix this have a shared failure mode: one hash per symbol. Hash a whole function, and a one-line body tweak invalidates a doc that only ever claimed something about the signature. Teams get flooded with false staleness, the CI gate gets marked continue-on-error, and the tool gets uninstalled. This is the specific failure lockwire is built to not have.

How it's different

lockwire fingerprints four aspects of a symbol separately, and a claim only binds the aspects it actually depends on:

flowchart LR
    SYM["Symbol<br/><b>createSession()</b>"] --> P & S & B & D

    P["<b>path</b><br/>file location"]
    S["<b>sig</b><br/>name · params · types<br/>return · modifiers"]
    B["<b>body</b><br/>normalized AST<br/>of the implementation"]
    D["<b>deps</b><br/>sorted set of<br/>outbound calls"]

    P --> C1["<i>structural claim</i><br/>'sessions are created in<br/>src/auth/session.ts'"]
    S --> C2["<i>contractual claim</i><br/>'takes a UserId,<br/>returns a Session'"]
    B --> C3["<i>behavioral claim</i><br/>'retries 3x with<br/>exponential backoff'"]
    D --> C4["<i>architectural claim</i><br/>'delegates token minting<br/>to the KMS client'"]

A contractual claim binds only sig — a body refactor never touches it. This is the whole mechanism.

A doc claiming "takes a UserId, returns a Session" binds sig only, and stays silent through every internal refactor of createSession. The P0 test suite proves this on a real example: a body-only edit that adds a logging call produces zero drifted anchors and a noise line reading single-hash would flag 1 · lockwire flagged 0 · noise −100%.

System view

flowchart TB
    subgraph SRC["Inputs"]
        direction LR
        CODE["Source tree<br/>TS · TSX · JS · Python"]
        DOCS["CLAUDE.md · AGENTS.md<br/>docs/**/*.md"]
    end

    subgraph L1["Fingerprint"]
        direction LR
        TS["tree-sitter<br/>parse"] --> EX["Tier extractor<br/>path · sig · body · deps"] --> HASH["BLAKE3<br/>fingerprint"]
    end

    subgraph L2["State"]
        direction LR
        LF[("lockwire.lock<br/>anchors")]
        LG[("ledger.jsonl<br/>history")]
    end

    subgraph L3["Three gates"]
        direction LR
        G1["write-time<br/>PreToolUse hook"]
        G2["commit-time<br/>pre-commit"]
        G3["merge-time<br/>GitHub Action"]
    end

    CODE --> L1
    DOCS -->|"&lt;!-- lockwire ... --&gt;<br/>markers"| L2
    L1 --> L2
    L2 --> L3

    classDef store fill:#1f2937,stroke:#60a5fa,color:#e5e7eb
    class LF,LG store

Anchor lifecycle

stateDiagram-v2
    [*] --> Fresh: lockwire link<br/><i>anchor.created</i>

    Fresh --> Drifted: a bound tier changed, or the claim<br/>sentence was edited<br/><i>anchor.drifted</i>
    Fresh --> Fresh: symbol renamed in the same file,<br/>exactly one match<br/><i>anchor.relocated</i>
    Fresh --> Orphaned: symbol, file or doc marker gone<br/><i>anchor.orphaned</i>

    Drifted --> Fresh: doc updated + link --reviewed,<br/>or ack<br/><i>anchor.resolved / anchor.acknowledged</i>
    Drifted --> Waived: time-boxed waiver<br/><i>waiver.granted</i>
    Drifted --> Superseded: claim no longer applies<br/><i>anchor.acknowledged</i>

    Waived --> Fresh: waiver expires, nothing moved
    Waived --> Drifted: waiver expires, something moved<br/><i>waiver.expired</i>

    Orphaned --> Fresh: marker or symbol restored,<br/>then link (--reviewed if the code changed)

    Superseded --> [*]

    note right of Fresh
        Relocation is an event, not a state: after a
        rename the anchor is just fresh (or drifted,
        if a bound tier also moved) under its new
        name. Same-file renames only in P0; a symbol
        moved to another file reports orphaned — see
        docs/concepts.md limitations.
    end note

Write-time enforcement

sequenceDiagram
    participant A as Coding agent
    participant H as PreToolUse hook
    participant L as lockwire core
    participant D as Ledger

    A->>H: Edit src/auth/session.ts
    H->>L: which anchors cover this file?
    L-->>H: 1 claim, bound to sig

    alt advisory (default)
        H-->>A: inject claim as context —<br/>no block, no prompt
    else ask
        H-->>A: prompt: acknowledge or proceed anyway
    else deny
        H-->>A: block until acknowledged
    end

    A->>A: edits the file
    A->>L: PostToolUse — re-fingerprint
    L->>D: anchor.drifted (if the bound tier moved)
    D-->>A: additionalContext: which claim just broke

Install

Claude Code — hook, MCP server, and skill in one plugin:

/plugin marketplace add Reality-Ventures/lockwire
/plugin install lockwire@lockwire

Codex, Cursor, Gemini CLI, and other agents that read SKILL.md — the skill only; wire up the hook and MCP server per your agent (see docs/agents.md):

npx skills add Reality-Ventures/lockwire

CLI and CI — no agent required:

npm install -g lockwire
lockwire check

Or without installing anything, via npx:

npx lockwire check

GitHub Action — merge-time gate (and lockwire/autofix to fix what it finds):

- uses: actions/checkout@v4
  with:
    fetch-depth: 0   # --changed needs history to find the merge base
- uses: Reality-Ventures/lockwire@v0
  with:
    args: --changed

pre-commit — commit-time gate, as a plain git hook (.git/hooks/pre-commit, made executable):

#!/bin/sh
npx --no-install lockwire check --staged --no-write

Quickstart

$ lockwire init
lockwire initialized: lockwire.lock, .lockwire/config.json, .gitattributes (ledger merge=union)

Add a marker above a claim in CLAUDE.md:

<!-- lockwire src/auth/session.ts#createSession sig -->
`createSession` takes a `UserId` and returns a `Session` valid for 24 hours.

$ lockwire link CLAUDE.md
CLAUDE.md: 1 created, 0 refreshed

The marker is now stamped with an id:

<!-- lockwire src/auth/session.ts#createSession sig id=k7q2m9xv -->

Refactor the function's body without touching its signature, then check:

$ lockwire check
CLAUDE.md
  ok

1 anchor · 1 ok · 0 drifted · 0 orphaned
single-hash would flag 1 · lockwire flagged 0 · noise −100%

Now change the actual signature (add a parameter) and check again:

$ lockwire check
CLAUDE.md
  DRIFTED   src/auth/session.ts#createSession (sig)

1 anchor · 0 ok · 1 drifted · 0 orphaned
single-hash would flag 1 · lockwire flagged 1 · noise −0%

Update the doc, then re-stamp — --reviewed is required because the code changed since the claim was stamped:

$ lockwire link CLAUDE.md --reviewed
CLAUDE.md: 0 created, 1 refreshed

And ask what happened, whenever, from anyone:

$ lockwire history k7q2m9xv
2026-09-25T10:00:11.579Z  anchor.created
2026-09-25T14:12:03.656Z  anchor.drifted       sig
2026-09-25T14:15:40.726Z  anchor.resolved       re-stamped via link

Inside Claude Code, the hook does this automatically — before the edit, you'd see the claim injected as context; after, you'd see exactly which claim just drifted, with no check invocation needed. See docs/agents.md for the injected text.

Let your agent fix it

lockwire doesn't write docs and has no model of its own. It gives the agent you already run — Claude Code, Codex, anything that speaks MCP — a work queue: every claim that's wrong, the code or value it was checked against and what it is now, and a resolve step that re-checks the fix and refuses one that's still wrong (a number that still disagrees with its data, a marker pointing at nothing). Ask your agent to run the fix-docs prompt, or do it by hand:

lockwire tasks                 # what needs attention
lockwire task k7q2m9xv         # one task: the claim, the code as stamped and now
lockwire resolve k7q2m9xv --note "documented the new scope parameter"

Every resolution is recorded with who made it and why. See docs/agents.md.

To run it unattended, lockwire autofix starts Claude Code or Codex on your own key — only when a claim is actually wrong — then re-checks every claim and refuses a run that touched anything but docs. In CI, the Action does the same and opens a pull request:

- uses: Reality-Ventures/lockwire/autofix@v0
  with:
    agent: claude-code
    anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}

See docs/autofix.md.

What lockwire does not do

Hashes cannot catch semantic drift — a doc say