computedWhat to computeHow it worksGitHub

Markdown sections that know when they are stale.

computed fills a marked region of a Markdown file from a directory tree, another file, the git history or a command, and writes down what it read and what it wrote. When the code moves on, computed check says so. It never runs the command to find out.

Built for CLAUDE.md and AGENTS.md. One binary, no runtime, no cache directory.

cargo install computed   # v0.3.0
computed run             # fill what moved
computed check           # exit 1 on drift

↑ a computed region of this page, rendered from Cargo.toml and checked in CI

CLAUDE.md

  1. 1The opener says what fills the region and what that reads, on one line. Paths resolve against the file holding the marker, so the region travels with the file. Touch anything it names and the region is stale.
  2. 2The body. computed run wrote it, and it belongs to the tool. If a person or an agent edits it, the next run refuses to overwrite the edit and exits 1.
  3. 3Two hashes in the closer, elided here because each is 64 characters. in= is what the tool read: the opener plus the bytes of every input. out= is what it wrote. Both live in the file, so a fresh clone can check them without running anything. The regions running in this repository carry theirs in the open — read CLAUDE.md.

Three numbers from this repository

8 of 41

Commits since this repo started using the tool in which the file-tree region's body changed. About one commit in five moved a fact a hand-written tree would have got wrong, silently.

reproduce
body() { git show "$1:CLAUDE.md" |
  awk '/^<!-- computed tree /{f=1;next}
       /^<!-- \/computed /{f=0} f'; }
for c in $(git log --format=%h 3624abc..65650a8); do
  [ "$(body $c)" = "$(body $c^)" ] || echo $c
done | wc -l

3.5 ms

computed check over this whole repository, executing nothing. Mean of 477 runs, ± 0.6 ms, on an Apple M4 Pro. That is the cost of knowing the answer, which is why it can sit in the same hook as rustfmt.

reproduce
cargo build --release
hyperfine --warmup 3 -N \
  './target/release/computed check'

1 of 4

Copies of this project's own command synopsis that are a computed region. The other three are hand-typed, in the README, the spec, and the page you would read next. We are not immune, and that is the point of the catalogue.

reproduce
grep -rl 'computed untrust' \
  README.md docs/ claude-code-plugin/

The file an agent reads first is the one nobody checks

A coding agent reads CLAUDE.md before every task and takes it as true. Most of the file is prose, and prose stays right. The part that goes wrong is the generated part. The directory tree, the module list, the index of decisions. The code moves, the list does not, and nothing notices. The agent starts each task with a map that was right a month ago, and it does not second-guess the map.

Everything else around an agent pushes back when it is wrong. Tests fail. The type checker complains. The context file gets no such signal. computed check is that signal, and it runs in the same hook and the same CI job as the others.

The guides-and-sensors framing is Birgitta Böckeler's, in Harness engineering for coding agent users, April 2026.

Three vendors, three answers, one missing option

Everyone writing guidance for agent context files is choosing between a fact that rots and a fact the agent does not have. Nobody offers the third thing, so the advice contradicts itself.

“Reference files instead of copying their contents — this keeps rules short and prevents them from becoming stale as code changes.”

Cursor, rules documentation

Requests to “refer to external resources” are listed among the instructions that “may not have the intended results.”

GitHub, custom instructions documentation

/doctor proposes cutting “directory layouts, dependency lists, and architecture overviews”, while the feature overview asks for project structure.

Anthropic, Claude Code documentation

Reference it and the agent has to spend a turn fetching it, if it can. Copy it and it is wrong within the month. A computed region is the copy, with the receipt attached: the agent reads it inline at no cost, and the moment the thing it was copied from moves, check fails.

Quoted from each vendor's own documentation, September 2026. Sources are numbered in docs/research.

Apache Airflow already built this by hand

Their AGENTS.md carries a marked region regenerated by a pre-commit hook, and a separate validator that introspects the live command tree to catch the region drifting. The validator's own docstring names the two bugs that made them write it: a documented command that never existed, and a rename that left the doc pointing at the old name.

That is run and check, in Python, for one repository, without the sums, and it cannot leave that repository. Home Assistant and LangChain have their own versions. The need is not hypothetical; it has been paid for several times, badly.

From the projects' own trees, September 2026. Sources in docs/research.

apache/airflow · AGENTS.md, abridged

<!-- START generated-commands, please keep … -->
…
<!-- END generated-commands, please keep … -->

A marker, a body the tool owns, and a hook. What is missing is the record of what the body was computed from — so the only way to ask whether it is still right is to install Python, install the project, and run the generator again.

Three steps, two commands

Every transcript below is copied from a real terminal, unedited.

Mark a region

<!-- computed tree src=. depth=2 -->
<!-- /computed -->

Two comments, anywhere in the file. The first names what fills the gap. tree lists a directory. exec runs a command and pastes its output. Seven more read a slice of a file, a version, an index, the headings, a function's signature, the history or a pinned document, and run nothing.

Run fills it

$ computed run CLAUDE.md:7 tree unrendered written $ computed run $ echo $? 0

run writes the body and the two hashes into the closer. The second run prints nothing and exits 0, because the bytes would be identical and nothing is written. That silence is the whole guarantee, and it is worth watching it happen once.

Check reads it

$ touch src/watcher.rs $ computed check CLAUDE.md:7 tree stale $ echo $? 1

check hashes the inputs again and compares. Nothing from the repository is executed, so it needs no trust and no runtime — a checkout you have not read is safe to check.

What a refusal looks like

$ computed run CLAUDE.md:7 tree edited refused; run with --force $ echo $? 1

Someone typed inside the body. The file is left untouched in full, not silently overwritten, because on CLAUDE.md the editor is usually an agent and a failed hook is the one signal that reaches it.

What a broken generator looks like

$ computed run NOTES.md:3 env exec stale failed; body kept exit status 3 $ echo $? 1

The command exited non-zero, so the last good body and both hashes stay exactly where they were and its stderr is printed under the region's line. A broken script never blanks a region.

What counts as an input, how a hand edit is told apart from drift, and who is allowed to run a command are on How it works.

Forty things you decided not to document

Every repository has a list of facts that would obviously help — every error the binary can emit, which test covers which module, what a fresh clone assumes is installed — and that nobody writes down, because a hand-maintained inventory costs forever and a wrong one is worse than nothing. That arithmetic is what changes. The marginal cost of the thirty-first region is one line and a script, and the cost of keeping it is a hash comparison.

Every error the binary can emit

agent
<!-- computed exec cmd=scripts/error-index.sh inputs=src/*.rs,scripts/error-index.sh name=errors as=fence -->

rustc generates its error index this way. curl's exit-code table is hand-maintained and admits its own drift. This repo has 28 distinct error sites in one module, listed nowhere.

Environment variables the code reads

agent
<!-- computed exec cmd=scripts/env-vars.sh inputs=src/*.rs,scripts/env-vars.sh name=env as=fence -->

Cargo's own environment reference is hand-written with no check that enumerates the env::var calls. A cargo issue puts it plainly: “There's an env var for it already sitting in the code.”

Which test covers which module

agent
<!-- computed exec cmd="cargo test -q -- --list" inputs=src/*.rs,tests/*.rs name=tests as=fence -->

Tells an agent which test to run for a change, instead of running everything or nothing. This repo has 56 tests and no such list.

The version dropdown in an issue template

both
<!-- computed exec cmd=scripts/versions-yml.sh inputs=Cargo.toml,scripts/versions-yml.sh name=versions as=raw -->

Not a documentation file at all. A whole GitHub Action exists just to keep this one dropdown current; a region does it in the file, with a check.

All forty, with the marker line for each

Why not cog, or mdsh, or markdown-magic?

They rewrite the span between two comments, and they do it well. None of them write down what the span was computed from. So the only way to ask “is this still right” is to run everything again.

There are three ways to keep a generated block honest, and only two of them are taken. You can regenerate on every build, which means the generator has to be present everywhere the docs are. You can commit the block, then in CI regenerate it and diff — which is what cog's --check, terraform-docs' --output-check, mdsh's --frozen, embedme's --verify and Kubernetes' seventy-six verify-*.sh scripts all do. Or you can store a fingerprint of the inputs in the file and compare it, which needs no generator, no runtime and no permission to execute anything. Nobody was doing the third one.

Knows what
it read
Checks without
running anything
Refuses a
hand edit
cog Python, any text file no no--check reruns yeswith -c
mdsh Rust, shell in the marker no no--frozen reruns no
markdown-magic Node, named transforms no nodryRun reruns no
embedme Node, file ranges no no--verify reruns no
terraform-docs Go, one module no no--output-check reruns no
computed Rust, one binary yesin= in every closer yes3.5 ms, no subprocess yesuntil --force

cog has run on any text file for twenty years, and markdown-magic already ships a file tree transform. Both have more users than we do. A rerun is fine for a table of contents. It is not fine for a shell command in a file an agent reads before every task, because the rerun needs the generator, its runtime, and permission to execute text from a checkout. CI usually has none of those, so nobody checks.

From each tool's own docs, September 2026. The survey with sources is in docs/research.

Get started

the tool, then the command that makes the artifact

cargo install computed   # v0.3.0
computed run

Without a Rust toolchain, take a prebuilt macOS or Linux binary from the latest release, checked against its published SHA-256.

the Claude Code plugin

/plugin marketplace add mitchellvanw/computed-files
/plugin install computed@computed
/reload-plugins
/computed-setup

/reload-plugins makes the skills live in this session. /computed-setup installs and wires the tool, then offers /discover-regions, which turns hand-written blocks into regions. The plugin also refuses an agent's edit to a region before it lands, and names the source to edit instead.

then, in a repository

computed trust   # once per clone, only for exec regions
computed run     # fill stale regions
computed check   # exit 1 on drift, runs nothing

With no paths, both commands walk the current directory for .md files and skip whatever .gitignore skips. An exec region only runs in a clone you have trusted on this machine, so a checkout cannot run commands on its own.

Wire it in

.pre-commit-config.yaml

repos:
  - repo: local
    hooks:
      - id: computed
        name: computed run
        entry: computed run
        language: system
        always_run: true
        pass_filenames: false

.github/workflows/ci.yml

- run: cargo install computed
- run: computed check . docs/index.html

The hook runs on every commit, not only when a Markdown file is staged. A new file under src/ makes the tree stale without touching CLAUDE.md. When the hook rewrites a file the commit stops and you stage again, the same as rustfmt.

That second path is not an illustration. Discovery walks .md, and a file you name is read whatever its extension — so the install block at the top of this page is a region, and the same CI job that checks CLAUDE.md checks it. If the crate's version moves and this page does not, the build fails.