Your AI instruction files, as each agent will actually read them — and what it will silently drop.
Every AI coding host reads instruction files its own way: CLAUDE.md, AGENTS.md,
.cursor/rules/*.mdc, .github/copilot-instructions.md, GEMINI.md, .goosehints,
.kiro/steering/… not the same names, not the same places, not the same limits, not the same
order. And when a limit is crossed, the host cuts or ignores without saying so: Codex
truncates its AGENTS.md chain mid-file past 32 KiB and writes a line in a log nobody reads;
Claude Code reads AGENTS.md only when there is no CLAUDE.md above it; Cursor ignores a
.md in .cursor/rules and a rule whose front matter is broken; Warp wants AGENTS.md in
capitals.
Linstruct rebuilds, for each host present on your machine and each project you work in, the stack of files the host would load — in its order, references expanded, budget simulated — and says what it would cut, ignore or shadow. Read-only, no network, secrets masked, every rule sourced from the host's documentation or source code. Part of the Blackberrylabs family; the control tower reads its report.
| Severity | Kinds |
|---|---|
| 1 · act now | cut — a host cuts or skips content, and its docs or source prove it (Codex past 32 KiB, Claude Code past 4 MiB, Goose past its import budget) · secret — a credential in clear, sent with every request |
| 2 · review | over-limit — past a documented limit with undocumented consequence (Devin 12,000 / 6,000 chars) · ignored — a file this host never reads · dead-import — an @path that brings nothing in · frontmatter — a rule that does not apply as written |
| 3 · good to know | shadowed — another file takes its place · over-length — past the host's recommendation or near its budget · duplicate — the same text loaded twice · comments — HTML comments sent to the model · legacy — an older name still read |
| 4 · information | empty · unreadable |
Nineteen hosts, each from a sourced sheet in hosts/: Claude Code, Codex CLI,
Cursor, GitHub Copilot, Gemini CLI, Qwen Code, Cline, Roo Code, Kilo Code, OpenCode, Goose,
Zed, Kiro, Amp, Aider, Devin Desktop, JetBrains Junie, JetBrains AI Assistant, Warp, Trae.
Hosts that are not on your machine are still computed and shown in the app as "what if" —
useful for an AGENTS.md shared with people who use other tools — but never counted in the
summary nor sent to the tower.
linstruct # the findings, most serious first, for the projects your machine knows
linstruct -p ~/code/myrepo # one project (several: -p ~/code/*; put a subcommand before -p)
linstruct stacks # what each host loads, file by file, with its budget
linstruct stacks --host codex
linstruct hosts # the hosts, their presence, where their rules come from
linstruct folders # where your projects live (see below)
linstruct --all-hosts # include the hosts not on this machine
linstruct --json # everything, for scripts
linstruct report # bbl-report/1 for the Blackberrylabs control tower
linstruct-app # the desktop appProjects: the ones you name with -p; otherwise the folders you remembered plus the
projects Claude Code knows on this machine (~/.claude.json); else the current directory.
A remembered folder is a project itself when it carries a .git or an instruction file;
otherwise each of its direct subfolders that does is one.
linstruct folders # the remembered folders and the projects they yield
linstruct folders add ~/code ~/work # remember folders (the app has the same, with a cross to forget)
linstruct folders remove ~/workThis list lives in ~/.config/linstruct/settings.json, next to the app's preferences — the
only file Linstruct writes. The host's working directory is taken as the project root; files
in subdirectories are shown as "on demand" or "when started there".
It does not judge the meaning of your instructions (no semantic contradictions, no style review), does not change any file, does not fetch the remote instructions some hosts accept (it lists them), and does not read the rules that are not files (Cursor User Rules, Warp Global Rules). What the host does with a broken front matter or past an undocumented limit is said to be undocumented, not guessed.
Read-only (nothing written outside ~/.config/linstruct/, the app's preferences); no network;
secrets masked the moment a line is read and never written; actions shown, never run; every
host rule cites its source, its date and the words it was read from (docs/hosts.md).
#![forbid(unsafe_code)]; tests/promises.rs checks the source for writes and network calls
and the report for conformance.
Linstruct is a module of the Blackberrylabs family —
read-only tools that show what AI coding agents do to your machine. Want only Linstruct?
It is complete on its own. Want several? The
control tower gathers what every
module finds in one list, most serious first: linstruct report is what it reads, linstruct-app --select
is how it opens Linstruct at a finding.
cargo test
cargo build --release # target/release/linstruct, linstruct-app
./packaging/build.sh # .deb, .rpm, AppImage in dist/Depends on bbl-hostrules (locations,
readers, secret masking), bbl-report (the
tower's contract) and bbl-ui (the family's face).
0.1.0 — first release. Packages (.deb, .rpm, AppImage, x86_64) on the
releases page. License MIT — Alexandre Do.