Building Align. align-cli is a free, open-source CLI that checks your coding agent's edits against decisions in your tickets, chat, docs and git. Try it and tell me what breaks.
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? 😹
Building Align. align-cli is a free, open-source CLI that checks your coding agent's edits against decisions in your tickets, chat, docs and git. Try it and tell me what breaks.
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 obsidian command. 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) 😂
Building Align. align-cli is a free, open-source CLI that checks your coding agent's edits against decisions in your tickets, chat, docs and git. Try it and tell me what breaks.
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 docs from 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.
Creator of GithubStarsManager — an open-source, local-first tool that organizes GitHub stars with AI: auto-categorization, semantic search, release tracking, and an MCP server for star library.
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.
Building Align. align-cli is a free, open-source CLI that checks your coding agent's edits against decisions in your tickets, chat, docs and git. Try it and tell me what breaks.
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.
Creator of GithubStarsManager — an open-source, local-first tool that organizes GitHub stars with AI: auto-categorization, semantic search, release tracking, and an MCP server for star library.
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?
Building Align. align-cli is a free, open-source CLI that checks your coding agent's edits against decisions in your tickets, chat, docs and git. Try it and tell me what breaks.
Yes. A correction is kept separately from anything imported. align mark conflict <a> <b> false (or align mark <new> replaces <old>, with --undo to 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
Building Align. align-cli is a free, open-source CLI that checks your coding agent's edits against decisions in your tickets, chat, docs and git. Try it and tell me what breaks.
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?
Building Align. align-cli is a free, open-source CLI that checks your coding agent's edits against decisions in your tickets, chat, docs and git. Try it and tell me what breaks.
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...
Building Align. align-cli is a free, open-source CLI that checks your coding agent's edits against decisions in your tickets, chat, docs and git. Try it and tell me what breaks.
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.
Building Align. align-cli is a free, open-source CLI that checks your coding agent's edits against decisions in your tickets, chat, docs and git. Try it and tell me what breaks.
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.
Building Align. align-cli is a free, open-source CLI that checks your coding agent's edits against decisions in your tickets, chat, docs and git. Try it and tell me what breaks.
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?
We're a place where coders share, stay up-to-date and grow their careers.
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.
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?