strata
AGENTS.md1 starsChanged 8 days agoMITView on GitHub
Strata shows how Git-tracked AI-agent configuration changes through time. It analyzes a local repository and writes an offline report. Read README.md for what it does for users, docs/analysis-scope.md for recognized inputs, and docs/decisions.md for measurement and report contracts when those topics matter to a change. Unless the user says otherwise, work in a new Git worktree on a new branch from an up-to-date main: git fetch origin main, then git worktree add --no-track -b <type>/<name> .claude/worktrees/<name> origin/main, then pnpm install…
- Commits and pushes
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository4 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- pr-screenshotsSkill
- pr-screenshotsSkill
- strata-interpretSkill
The file
We split this AGENTS.md into the rules it gives an agent
4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 24
Keep the target repository read-only.
- Distinctive: line 27
Keep HTML usable offline and source text out of default HTML/JSON.
- Distinctive: line 28
When changing provider recognition, report fields, or measurement, update the scope/decision docs and cover the behavior in the matching …
- Very specific: line 36
Use gh, service APIs, and MCP integrations for project data.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Working in Strata
Strata shows how Git-tracked AI-agent configuration changes through time. It analyzes a local repository and writes an offline report. Read README.md for what it does for users, docs/analysis-scope.md for recognized inputs, and docs/decisions.md for measurement and report contracts when those topics matter to a change.
Where to work
Unless the user says otherwise, work in a new Git worktree on a new branch from an up-to-date main: git fetch origin main, then git worktree add --no-track -b <type>/<name> .claude/worktrees/<name> origin/main, then pnpm install inside it. Push with git push -u origin HEAD. Leave the main checkout on main and untouched. Remove the worktree once its branch is merged or abandoned.
Code map
- Analysis.
src/analyze.tsreplays first-parent history into revisions,src/inventory.tsmeasures them, andsrc/model.tsholds the report types.src/adapters.tsrecognizes provider paths.src/git.tsruns read-only Git commands.src/content-pass.tsreads each blob once and hands it to every step that needs it; each step is aContentUse.providerReadsinsrc/provider-view.tsis the single rule for whether a provider reads a component. The other measurement modules are named for what they measure (skill listings, rule loading, up-front context, MCP servers, Gemini settings, Claude imports, instruction age, submodules). - Token counts.
src/precise.tschooses each provider's counting methods: Codex is counted locally on every run, Claude and Gemini only with--precise.src/provider-counting.tsruns them with fallback for bothanalyzeanddiff. - Reports store no per-revision file list.
src/expand.tsrebuilds each revision's inventory from the component table and per-revision changes. strata diffissrc/pr-delta.ts, sharing the inventory code.src/limits.tshandles--limit-*andsrc/ignore.tshandles--ignore, for both commands.- Report.
src/report.tsassembles the HTML fromsrc/report: styles, markup, and the client script cut by panel undersrc/report/client. The client parts share one scope; panel parts only declare state and functions, andsrc/report/client/start.tsruns the startup last.src/svg.tsrenders the SVG image. Colors come fromsrc/palette.ts, the logo fromsrc/brand.ts. - Embedded as source text.
src/expand.ts,src/compare.ts,src/provider-view.ts,src/import-links.ts,src/treemap.ts,src/config-map.ts,src/timeline.ts,instructionAgesinsrc/instruction-age.ts, andupFrontContextinsrc/up-front.tsare copied into the HTML report as text, so each must stay self-contained. The exceptions, embedded beside them:viewRevisionmay callproviderReads,upFrontContextmay callproviderReadsandimportLinks, andexpandRevisionsmay callfillRevisions. - GitHub Action.
action.ymlinstalls the npm package when itsdist/source-digest.txtmatches the Action's source and its provenance checks out, and builds from source otherwise (test/action-install.test.mjs). Its compare step importslimitResultfrom the builtdist/limits.js, so renaming or moving that export breaks the Action although the typecheck passes;actionRunnerintest/cli.test.mjsruns the step.action.yml, every workflow that can write (awritepermission, or no top-levelpermissions), and the local reusable workflows they call pin actions to a commit SHA; read-only workflows use release tags (test/workflow-pins.test.mjs). - Demo site.
scripts/demo-site.mjsbuilds the gallery that.github/workflows/demo-site.ymlpublishes, from the npm release named inpackage.json. - Tests. Synthetic Git histories (
test/synthetic-repo.mjs) verify analysis and CLI behavior:test/analyze.test.mjs,test/cli.test.mjs, onetest/<provider>-adapter.test.mjsper Gemini, Cursor, and Copilot, and one file per feature.test/report-ui.mjsruns the report's script against a fake DOM. - Agent configuration.
skills/strata-interpretis the skill Strata ships to users. This repository's own agent files are plain copies, one per tool:.claude/agentsand.codex/agents,.claude/skillsand.agents/skills. Change both copies together (test/agent-config.test.mjschecks the skills). Do not use symlinks: Strata skips them, so its report on this repository would miss the file.
Changes that affect analysis
- Keep the target repository read-only. Analyze tracked Git blobs, not the working tree, and upload no repository content. The one exception is the Action, which may fetch commits a CI checkout lacks into its
.git; it changes no working-tree file, branch, or tag. - Distinguish stored instruction estimates from loaded context or billing tokens. Structured configuration and supporting resources stay source-only unless a change defines and documents a defensible text boundary.
- Label conditional loading, renames, and inferred relationships accurately. Do not infer active context or a refactor from path changes alone.
- Keep HTML usable offline and source text out of default HTML/JSON. Escape repository-derived strings before placing them in HTML.
- When changing provider recognition, report fields, or measurement, update the scope/decision docs and cover the behavior in the matching synthetic history test. Version report schema changes.
Verification
Use Node.js 22.13+ and pnpm 10.29.3. For code changes, run pnpm lint, pnpm typecheck, and pnpm test; pnpm format applies formatting. Use Conventional Commit subjects (fix:, feat:, docs:); the changelog and version come from them, so do not edit CHANGELOG.md. For packaging changes, run node scripts/smoke-package.mjs. Never modify a repository you analyze for a smoke check.
External tools and services
- Use
gh, service APIs, and MCP integrations for project data. Use browser automation only for visual checks or when no API or CLI can do the job, never by default for issues, pull requests, boards, or settings. - When a pull request changes anything visible (the HTML report, the SVG image, README or brand images), add before and after screenshots, at the same size and state, each captioned with what changed and where to look. Upload them with
gh --attach; do not commit images to display them. Thepr-screenshotsskill has the steps.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

