When a decision changes while AI agents are already working, trailstone gets the new rule to each of them at their next edit, and blocks the push of anything still built on the old one.
For anyone running more than one agent at a time: in separate worktrees, in a teammate’s clone, or across Claude Code, Codex and Cursor.
One script and one file in your repo. No server, no account, no telemetry.
You record a decision: sessions use JWT. Three files are built on it.
$ git push ✗ blocked: logout.ts is stale
Each agent works in its own worktree. Halfway through, a teammate commits “timestamps are epoch ms, not ISO” on main. Real Claude Code sessions at 3× speed.
So when you reverse it, trailstone knows exactly which work now rests on the old rule.
A line in .trailstone/decisions.yml, committed with your code.
$ trailstone decide "Sessions use JWT" \
--scope src/auth/
covers 3 tracked filesEvery running agent is told at its next edit, in any worktree or clone.
$ trailstone reverse d_5913723e \
"Signed HttpOnly cookie"
⚠ was “JWT” → now “cookie”Files last committed before the reversal block the push until someone re-checks them.
$ git push
⚠ STALE: 3 files
exit 1Small samples, all run by us, and every number says how many runs it rests on.
For rules that don’t change, agents followed a plain CLAUDE.md about as well as trailstone, and it costs less.
A change committed on main never reaches the CLAUDE.md an agent in another worktree or an unpulled clone is reading. trailstone reads the ledger on main and on origin: it reached 15 of 15 agents in separate worktrees and 9 of 9 in separate clones. A teammate’s pushed CLAUDE.md edit reached 0 of 3 clones.
trailstone tells agents what changed and blocks the stale push. An agent or a person still makes the change.
Reversing a decision flags every file in its scope. Most still comply and clear in seconds, which is why a narrow scope matters.
Prose that describes an old decision in a file no decision names will drift unseen. So will a governed file you rename.
Editing and committing a flagged file clears it, even for an unrelated change. The warning before the edit is what makes that safe.
Every decision lives in .trailstone/decisions.yml, plain YAML committed next to your code. The pull request that adds a line is the review. Decisions are never edited: changing your mind is a new entry that supersedes the old one.
The format is the contract, and the script is only its first implementation. Any agent can ask what governs a file through trailstone mcp. Telling an agent before it edits, unasked, works in Claude Code, Codex and Cursor today. A hook for Windsurf or Claude Desktop is the most useful thing anyone could contribute.
- id: d_6d0bf686
by: Dana
decision: Sessions use JWT headers, not cookies
why: a CLI calls the API too
scope: [src/auth/]
- id: d_259ab7a1
by: Dana
decision: Sessions use a signed cookie, not JWT
why: XSS token theft; the CLI gets a PAT
scope: [src/auth/]
supersedes: d_6d0bf686npm i -g trailstone cd your-repo trailstone install trailstone init --goal "what this project is"
Works with Claude Code, Codex and Cursor, and as a GitHub Action in CI. A repo without a ledger stays silent, so installing once for your machine costs nothing elsewhere.
install touchestrailstone uninstall removes every hook and the pre-push guard. It leaves your ledger and the lines it added to AGENTS.md, .gitignore and .cursor/rules, because those are your repo’s content.
No server, no account, no telemetry. The one network call is a background git fetch of your own origin’s default branch, to read the current decisions. TRAILSTONE_FETCH=0 turns it off.
trailstone is a decision ledger that lives in your git repo. When a decision is reversed while AI coding agents are already working, it gives each agent the new rule at its next edit and blocks the push of any file still built on the old one. It is one script and one YAML file, with no server, no account and no telemetry.
For rules that stay put, a CLAUDE.md works about as well and costs less. trailstone matters when a decision changes where an agent isn’t looking: in another worktree or in a clone that hasn’t pulled. In our runs it reached 15 of 15 agents in separate worktrees and 9 of 9 in separate clones; a teammate’s pushed CLAUDE.md edit reached 0 of 3 clones.
Claude Code, Codex and Cursor are told before they edit a governed file. Any MCP client can ask what governs a file through trailstone mcp, and other agents read the rules it writes into AGENTS.md. The push guard and the CI check work with any tool, because git does not care what wrote the code.
No. It tells agents what changed and blocks a push that still rests on a reversed decision. An agent or a person makes the change.
No. There is no telemetry. The only network call is a background git fetch of your own origin’s default branch, to read the current decisions, and TRAILSTONE_FETCH=0 turns it off.
Run npx trailstone demo. It shows three agents, one reversal and a blocked push on a throwaway repo in about ten seconds. It needs Node.js 20.17 or later.
Yes. It is open source under the Apache-2.0 license, on GitHub and npm.
A trailstone is a stack of stones a traveler leaves to mark the trail, so whoever comes after doesn’t lose the path.