Coding agents are good at reading code. They're bad at knowing why the code is like that.
The why is usually somewhere else. A ticket where someone explained the edge case. A PR comment saying "we tried this, it broke billing". A Slack thread where the team picked Postgres over Mongo. The agent never sees any of it, so it "simplifies" the weird condition, or brings back the library you removed last month.
This isn't a hunch. Oliver Zehentleitner ran 20 fresh agent sessions on the same codebase with the same request: simplify a retry wrapper. With no recorded reason, 7 of 10 suggested the change that had already been rejected. With one written-down reason in the repo, none did. (his write-up)
CLAUDE.md and AGENTS.md help, but they're a file the model can choose to skip, and nobody keeps them current.
What I built
align-cli is a free, open-source CLI. It pulls the decisions out of where they already live (git history, ADRs, CLAUDE.md and AGENTS.md, PRs, and if you connect them, Jira, Linear, Notion, Slack and others) into a graph on your machine. Then, before your agent edits a file, it checks the change against those decisions. If the edit rewrites lines a decision wrote, it stops and asks you.
Try it in a few seconds, nothing installed, no account, no API key:
npx @aligndottech/cli demo
On your own repo:
npm install -g @aligndottech/cli
align
Same prompt, two real runs on Align's own repo. The GIF replays them, so it isn't a live session. Without Align the agent plans to skip signature checks. With it, the agent stops and cites the decision that ruled that out.
It plugs into Claude Code, Codex and Cursor, or runs as its own agent with your key or a local model. The graph is one SQLite file in ~/.align. Imports are read-only.
Where it falls short today
- Telling "this decision replaced that one" from "these two conflict" needs an AI key. Without one, related decisions just show up as related.
- The edit check is most battle-tested in Claude Code.
- It can't know a decision is out of date until someone makes the newer one. A lot of the devs I've talked to this week are fighting that same problem.
It's MIT and on GitHub: https://github.com/aligndottech/align-cli
Try it and tell me what breaks. I read every issue.

Top comments (23)
what a fantastic idea!
Thanks Anna! If you try it, tell me what breaks. I read every issue.
I am mostly a solo developer, but I can see how this would be useful for teams. I was wondering if you had any plans on integrating obsidian at some point? That is what I use most. My issue isn't that I have a bunch of people on a team, but moreso multiple devices I might work from. XD
Any thoughts about reading unpushed commits on different devices? 😹
No Obsidian import built in yet. But the connector SDK is open source (MIT): github.com/aligndottech/align-conn...
A source is one fetcher class: read the vault's .md files and return each note with its path, text, and date if the note has one. The CLI doesn't load outside fetchers on its own yet, so it also needs a small
align import obsidiancommand. If you fancy building the fetcher, open an issue and I'll do the CLI side.Until then, your agent can save a decision from a note: the align_capture tool takes plain text in local mode.
On devices: the graph is one SQLite file per machine and it doesn't sync. The git import reads that machine's checkout, unpushed commits included, so each device knows its own work but not the other laptop's.
I am genuinely curious about this. You have sparked a side quest for me to enable my own laziness. 😹 I work from different machines and want to be able to grab data from any of my personal devices. Just over here, reinforcing bad habits! 😂 Basically, I like the idea of agents all on the same page via the fetched data, but I want to add a layer here for my own personal nonsense.
That's good to have the plain text capture as a fail safe for edge cases. But I could imagine this could be tedious if there is a lot of documentation? Looks like it's typescript heavy, personally not something I have too much experience with. (Runs and hides) 😂
Ha, a laziness side quest is the best kind. No TypeScript needed for this one.
If the vault is a git repo, make a docs/decisions folder in it and put one decision per .md file there. Then run
align import docsfrom the vault on each machine. It reads every .md in that folder, so every device's agents get the same decisions. When you add one, pull and re-import on the other machines.It only reads that folder, so the rest of the vault stays out of it.
I think I see what you are saying.
Shout if you try it and get stuck. Happy to help you set up the folder.
This nails the failure mode I've run into most: the agent reads the code fine, then "simplifies" away a decision whose reason lived in a PR comment from months ago. Pulling the why out of git history instead of asking the model to guess it feels like the right layer to fix it at.
Curious about the 20-session experiment — did the agents mostly re-litigate the same one or two decisions, or was it spread across the codebase? And the date point in the replies is interesting: a decision with no date is basically un-auditable.
One decision, on purpose. Oliver gave all 20 sessions the same request against the same retry wrapper, so it measured one decision under controlled conditions, not a sweep of the codebase. The write-up is worth reading for the setup. And yes on dates. Since 0.77.1 every decision the edit hook shows carries the date it was made, not the date it was imported.
That clears it up, thanks — one decision, measured under controlled conditions, makes the 20-session setup much more legible than a sweep would have been. And the date point is exactly what I was hoping for: since 0.77.1 the decision carries the date it was made, not the date it was imported, so it stays auditable. I'll read the write-up for the setup details.
The 7 of 10 versus none result is a strong case for writing the reason down, and Hiten's question about stale decisions is the one I would worry about too. A record that confidently blocks the right change is its own kind of bug, so showing the date and naming the decision that replaced it feels like the right default.
We ran into the same gap when building memory for our own coding tools at Ascendra Ventures. An audit of roughly 7,000 prompts over three months showed the same context being typed again and again, and reasoned decisions disappearing between sessions. Memory fixed the repetition. It did not fix trust. One handwritten parser read every field one column off, and the numbers it produced looked perfectly reasonable. That taught us that a confident wrong answer is worse than a blank, so anything that extracts a decision has to be allowed to say "I don't know".
Your choice to stop and ask instead of hard-blocking fits that well. When the model links two decisions wrongly, can a user correct it in a way that survives the next import?
Yes. A correction is kept separately from anything imported.
align mark conflict <a> <b> false(oralign mark <new> replaces <old>, with--undoto take one back) saves your judgement in its own table, tied to the two decisions. A re-import updates a decision in place, so it keeps the same id and your mark still applies. If the model suggests the same pair again, the check shows "marked false alarm by you on " instead of raising it again.The gap I haven't fixed: if the source changes enough to come back as a different decision, like a doc whose title was rewritten, the mark doesn't follow it.
Your parser story is the failure I worry about most. A neat wrong number is worse than a blank.
the out of date decision problem feels like the hard one. a stale decision that confidently blocks the agent could be worse than no record at all, does it show when a decision was last touched or who made it
Yes, that's the hard one. Two things help today. Every decision the hook shows carries the date it was made. And if a newer decision replaced it, the hook shows it as superseded and names the newer one. It doesn't show who made it yet. Also, a match doesn't hard-block the edit: the agent stops and asks you, so a stale decision costs you one "that's out of date, carry on". It can't tell a decision is stale until someone writes the newer one, though. That part is still open.
fair, one extra confirm is a cheap price for a stale decision. does the superseded link get created automatically or does someone have to write the newer decision by hand?
Bit of both. The newer decision usually isn't written by hand. It gets picked up from wherever it was actually made: a PR, a commit, a ticket, an ADR, a chat thread or a meeting transcript etc.
The link is the part that needs care. A model can say two decisions clash, but whether the newer one replaces the older one is worked out from the dates and who made each one. Anything ambiguous comes out as a conflict, not a replacement. In the CLI a suggested replacement stays marked as AI-suggested until someone confirms it with
align mark <new> replaces <old>. Wrongly retiring a decision that still holds is the worse mistake, so I'd rather it asked.Also, your earlier question shipped today in 0.78.0. The edit check now shows who made each decision and flags anything over a year old or with no date.
@tom-at-align Finer than per turn, but per turn is part of it. The public benchmark runs real end-to-end Claude Code sessions on 7 long tasks (over 200k tokens), 10 runs each, and reports the mean cost reduction with input, output and cache tokens in separate columns. Method and numbers: pi-infected.github.io/token-harnes...
That's a proper benchmark, thanks. Splitting cache tokens out is the bit most people skip. The date fix I mentioned shipped today in 0.77.1.
Regression loops are one of the most frustrating aspects of long agent sessions. Without persistent architectural decision logs or test-driven boundaries, the agent simply treats its immediate local context as ground truth. Maintaining explicit project invariants in a pinned context file helps mitigate this significantly.
Agreed. A pinned file is the cheapest first step. Where it ran out for me is that nobody keeps it current, and the reasons sit in PRs and tickets the file never gets.
Coding agents read the code, not the reasons behind it, so a decision with no date or cause gets argued again in the next session. I'm building Tokenade, and the cost side is plain: the instructions go out again at each turn. A dated reason on one line protects the rule for less than a paragraph of history.
Agreed. The date turned out to matter more than I expected. Someone trialling it this week found our edit hook showed decisions with no date, so the agent couldn't tell an old rule from the one that replaced it. The fix is in review now: every decision the hook shows carries its date.
How are you measuring the cost side in Tokenade? Tokens per turn, or something finer?