computedWhat to computehow it worksGitHub
The rules, in the order the tool applies them.
What a marker may say, what goes into each hash, what a region can be, and what run and check do about it. Everything here is decided from the file and its inputs. The full spec is computed-v0.md.
The markers
A region is the span between two comments, each on a line of its own. In Markdown they are HTML comments; a code file uses its own comment, below. The first names what fills the region. The second carries the hashes. Anything between them is the body, and the tool owns it.
<!-- computed tree src=. depth=2 name=layout | do not edit; run computed -->
```text
.
├── docs
└── src
```
<!-- /computed in=9f3a1c0b… out=41c0d9e8… -->
| In the opening comment | Meaning |
|---|---|
| tree · exec · file · … | The first word picks what fills the region. There are ten, below. |
| name= | Optional. Reports use it instead of the line number. Unique per file. |
| as=fence · as=raw · as=table · as=comment | How the text lands in the file. fence wraps it in a code block, raw pastes it as Markdown, table turns CSV or JSON Lines into a Markdown table, comment writes each line as a comment in a code file. Tree defaults to fence, exec to raw, and outside Markdown every default is raw. |
| lang= | The language on the code fence. Empty by default. |
| max-lines=N | Keep the first N lines of the output and a note of how many were cut. |
| on-stale=warn | check reports the region when it is stale, and does not fail on it. |
| | do not edit; run computed | The tool adds this suffix when it renders. You do not write it, and the parser ignores it. |
A closing comment with no hashes means the region has never been rendered. A closing comment with one hash, an unknown word, a duplicate name, or a region inside another region is a parse error. The file is left alone and the exit code is 2. Markers inside a fenced code block are ignored, which is how this page's examples survive.
A region can sit inside a line. In Markdown and HTML, an opener and a closer on the same line hold one value of a sentence: The current release is <!-- computed value src=Cargo.toml key=package.version -->0.2.0<!-- /computed in=… out=… -->. The text must be one line, and it goes in as it stands. The closer still carries both hashes in full, so the source line is long and the rendered page hides it. In Markdown, markers inside backticks are prose, as they are inside a fence. Reports name the column too: README.md:3:24. The install lines on this site's front page are two of these, reading the version from Cargo.toml.
A marker is one line. Wrapping a long opener across two lines is an error — unterminated marker: the line does not end with -->, exit 2 — and that is deliberate rather than laziness. In CommonMark a line beginning <!-- opens an HTML block that runs until a line containing -->, so a marker that opened on one line and closed on another would swallow every line in between and hand it to the HTML parser. Keeping both markers to a single line makes each one a self-contained block, and leaves the body between them to parse as ordinary Markdown.
The old advice that an HTML comment may not contain -- no longer holds: the HTML Standard forbids the text starting with > or ->, containing <!--, --> or --!>, or ending with <!-. So cmd="cargo tree --depth 1" is a conforming comment, and only --> is a real hazard — which the parser rejects inside a quoted value. XML is the stricter one, where any -- is illegal, so a region in an .xml or .svg file should keep -- out of its opener.
The two hashes
in= is a SHA-256 over the opening comment and a snapshot of the inputs. For tree, the snapshot is the list of paths it printed. For exec, it is the bytes of every file named in inputs=. For a region that reads part of a file, such as one section or one key, it is only that part. If any of it changes, the region is stale.
out= is a SHA-256 over the body, byte for byte. If it no longer matches, someone edited the body.
Both live in the closing comment, so a fresh clone carries everything check needs. There is no cache and no sidecar file. The binary's version is not part of either hash, so upgrading does not make every region stale.
depth=2 to depth=3 is a changed input, not a hand edit.The loaders
tree
<!-- computed tree src=. depth=2 all dirs -->
Lists a directory the way tree does, without sizes or dates. src= defaults to the file's own directory and depth= to unlimited. all includes dotfiles, dirs lists only directories.
Inside a git repository it skips what .gitignore skips, with no flag to turn that on or off. Names are sorted by byte order so two machines print the same listing.
exec
<!-- computed exec cmd="cargo tree --depth 1" inputs=Cargo.lock -->
<!-- computed exec cmd=date volatile -->
Runs cmd= with /bin/sh -c and pastes its standard output. You must say what the command reads. inputs= takes comma-separated globs, and every matched file's bytes go into the snapshot. volatile says the command has no inputs and should run every time.
The command runs with the file's directory as its working directory, a 30 second limit you can change with timeout=, and LC_ALL=C and TZ=UTC set so its output does not depend on the machine. An exec region only runs in a repository you have trusted. See who may run a command.
file src=docs/shared.md pastes one file as it stands, so a section shared by CLAUDE.md and AGENTS.md is written once. section=Install, lines=10-40 or anchor=example takes one part of it, and only that part goes into the snapshot. With as=fence lang=markdown it shows a file as code, markers and all.
Six more read without running anything. value src=Cargo.toml key=package.version takes one field of a TOML, JSON or YAML file. index src="docs/adr/*.md" lists files as links titled by their first heading. toc lists the file's own headings. symbol src=src/lib.rs item=parse part=signature takes one item of a Rust, Python or Go file. git log, git tags and git contributors read the history. remote url=… sha256=… renders a document pinned by its hash. None of them needs trust. transcript runs a shell session and shows each step with its output, and needs trust as exec does.
A computed.toml can name an opener once, as a recipe, and a region writes use recipe=NAME for it.
Relative paths resolve against the directory of the file holding the marker, not the repository root or the shell's working directory. So a region reads the same from a hook, from CI, and from a terminal, and moving the file moves its regions with it. A path that leaves the repository is an error, because such a region would render differently on every machine.
Before the text lands in the file, line endings become LF and trailing newlines are stripped. A command that prints invalid UTF-8, a control character, or a line that looks like a marker outside a fence has failed. A region indented inside a list item gets its body indented to match. When a command fails, times out, or exits non-zero, the old body and both hashes stay, its stderr is printed under the region's line, and the run exits 1. Deleting an input does not blank a region.
The states
Four questions, asked in this order. The first one that says no names the state. check asks them and reports. run asks them and then renders every region that is not fresh.
| State | What it means | check | run |
|---|---|---|---|
| fresh | Both hashes match. | silent, exit 0 | left untouched |
| stale | The inputs or the opening comment changed. | reported, exit 1 | rendered |
| edited | The body no longer matches out=. | reported, exit 1 | refused, exit 1 |
| stale+edited | Both. | reported, exit 1 | refused, exit 1 |
| volatile | An exec region with no inputs and an unedited body. | silent | rendered every time |
| unrendered | The closing comment has no hashes. | reported, exit 1 | rendered, whatever the body holds |
| untrusted | Not a state of the region but of the clone: an exec region in a repository you have not trusted. | not a concern, check runs nothing | skipped, exit 1 |
Because check never runs a command, a command whose output changes for the same inputs is invisible until you pass --force. That is the price of a check that needs no runtime and no trust. computed doctor runs every loader twice and names such a region, and computed trace names the files a command reads that its inputs= leaves out.
Hand edits
The file you commit is the file the tool edits. Outside a marker pair everything is yours and a run never touches it. Inside, the body is the tool's, and an edit there is refused rather than overwritten. The region stays as edited, the whole file is left unwritten, and the run exits 1.
To regenerate, pass --force, which overwrites every edited region in the files you name, or delete both hashes from the closing comment. Editing the opening comment is not a hand edit. It changes in=, so the region is stale and renders on the next run.
The reason to refuse rather than warn is the pre-commit path. A warning from a hook that still writes and exits 0 is an overwrite with a line nobody reads. On CLAUDE.md the editor is usually an agent, and a failed hook is the one signal that reaches it. In Claude Code the plugin gets the signal there sooner: a hook refuses the edit before it lands.
Who may run a command
An exec region runs only in a repository you have trusted on this machine. The model is the one direnv and git's safe.directory use.
computed trust # this repository, on this machine
computed untrust # take it back
computed run --trust # this one invocation, for CI
The grant is stored in ~/.config/computed/trust.toml, keyed by the repository root. Nothing inside a checkout can grant itself. In an untrusted clone, run skips every exec and transcript region, reports it as untrusted, still renders every other region, and exits 1. check never runs a command, so it needs no trust at all.
Only a region that runs a command from the repository needs a grant. The git loader runs git to read history, and that runs nothing the repository controls. A remote region fetches only under a url prefix this machine has allowed with computed allow, and a grant allows no url.
This defends against one thing: cloning a repository and having computed run execute its commands before anyone has read them. A malicious branch pulled into a clone you already trust runs on the next run, the same as a Makefile or a pre-commit hook would.
Commands and exit codes
| run [paths] | Render every region that is not fresh and write the files. Exit 1 when it wrote, refused, or a command failed. |
| run --dry-run | Print the diff each file would get, write nothing. The only place the pending diff is shown. |
| run --force | Also overwrite edited regions, and re-render fresh ones. |
| run --trust | Treat every file as trusted for this invocation. |
| check [paths] | Report the state of every region. Runs no command. Exit 1 on anything but fresh. |
| clean [paths] | Empty every body and strip the hashes, leaving the markers. The next run rebuilds them. |
| trust · untrust [path] | Grant or revoke exec for the repository containing the path. |
| update · allow · disallow | Pin each remote region's document by its SHA-256; keep the url prefixes this machine may fetch. |
| doctor · trace | Render every region twice to find output that is not stable; trace each command to find what inputs= misses. |
| affected · graph · why | Which regions a path feeds, what every region reads, and why one is stale, from git history. |
| stats · dupes · adopt | How much of each file is computed; blocks copied between files; a hand edit written back into its source. |
| merge · guard · watch · lsp | A git merge driver, the Claude Code edit guard, a watcher, and a language server. |
| --only NAME | Only the regions with that name. Repeat for more. |
| -v | Also print the regions that are fine. |
| --format json | One JSON document on stdout instead of the report. |
With no paths, a command walks the current directory for .md and .markdown files, .claude/ and .github/ included, skipping what .gitignore skips, plus the code files a [discover] table asks for. A file you name is read whatever its extension.
one line per region, on stderr
CLAUDE.md:12 layout tree stale written
CLAUDE.md:40 deps exec edited refused; run with --force
CLAUDE.md:58 exec untrusted skipped; run `computed trust`
exit 0Nothing to report. Everything is fresh.exit 1The content said no. Drift, a written file, a refused edit, a failed command, an untrusted region.exit 2The tool could not answer. A usage error, a parse error, a path outside the repository, aninputs=glob that matches nothing. A region the tool cannot answer is skipped on its own; the rest of its file is still kept current.
How files are written
Every write goes to a temporary file that is then renamed over the original, keeping its permissions. A symlink is written through, so AGENTS.md linked to CLAUDE.md stays a link. A file edited while its commands ran is not overwritten. When one file's inputs= read another, run renders again until both settle, so one run leaves check passing. Nothing is written when the bytes would be identical, so running twice changes nothing and the file's modification time does not move. A file with one refused region is not written at all, even if other regions in it are merely stale. Other files in the same invocation still are.
computed watch runs run again whenever a template or a file its regions read changes. It knows its own writes by their bytes, so a pass it made does not start another.
Files that are not Markdown
A region in a code file is written in that file's own comment, chosen by its extension or name. HTML, XML and SVG use <!-- --> as Markdown does. Rust, Go, TypeScript, C and their neighbours use //, and Rust's //! and /// work too. Python, shell, TOML, YAML, a Makefile or a Dockerfile use #, SQL and Lua use --, and CSS uses /* */ on one line. The hashes, the states and every loader are the same.
What ports
The markers, in the file's comment. The two hashes, unchanged. as=raw, which pastes the loader's text as it stands, and as=comment, which writes each line behind the comment's leader. With lang=, it fences the text first, so a Rust doc comment holds a code block.
//! computed tree src=. depth=1 as=comment lang=text | do not edit; run computed
//! ```text
//! .
//! └── main.rs
//! ```
//! /computed in=… out=…
What does not
The fence sink. Outside Markdown three backticks are three backticks, so a loader that would fence its text writes it raw there. An explicit as=fence in an HTML file still writes the backticks, and a < or & in the text is read as markup. Let the generator emit the markup until an escaping sink exists. toc and dupes read Markdown only.
"computed" is a common word in code. In a // or # comment, a line opens a region only when computed is followed by a loader the tool knows. // computed values are cached stays a comment. In HTML, the text of a <script> or <style> element holds no markers.
Discovery reads code only when asked. A bare computed check walks Markdown, as it always did. A path you name is read in its own syntax. To have the walk read code too, list it in the computed.toml at the repository root, so the hook, CI and the editor all read the same files:
[discover]
extensions = ["rs", "html"]
names = ["Makefile"]
A formatter will fight a region. Prettier or markdownlint running over CLAUDE.md will reformat a body and turn it edited, and the two tools will then undo each other forever. Until computed emits the range-ignore comments itself, wrap the region the way all-contributors does — inside prettier-ignore-start and markdownlint-disable fences.
There is no file-level DO NOT EDIT banner and no linguist-generated attribute, because both are the wrong granularity. A file with three regions and two hundred lines of prose is not machine output, and marking it as such would hide hand-written changes from diffs. The warning belongs in the marker, which is where the opener's | do not edit; run computed suffix puts it. ADR 0003.