adr-tools vs WhyChose

Quick verdict

• Choose adr-tools if: you're starting a fresh project, you've decided to write ADRs at decision-time, and your team will keep the habit. The CLI is small, free, and proven; it has zero opinions you have to fight against.
• Choose WhyChose if: you have 6–18 months of accumulated ChatGPT or Claude conversations where you reasoned through stack picks, pricing calls, hiring, vendor choices — and your /doc/decisions/ folder either doesn't exist or only covers 10% of what actually got decided.
• Or: use both. They produce compatible artifacts at different ends of the lifecycle.

Side by side

Detailed differences

1. They run at different points in the decision lifecycle.

adr-tools is a writing-time tool. You decide; you run adr new; you write the five sections; you commit. The discipline is in the moment. The failure mode is forgetting to do it — which is why most ADR folders are sparse 90 days in. WhyChose is an extraction-time tool. You don't change anything about how you make decisions; you just keep using ChatGPT or Claude as your sounding board. Once a quarter you export and run the extractor. The discipline is at the cadence, not at every decision.

2. The input shape is different.

adr-tools takes prose you write deliberately. WhyChose takes raw conversation, including the clarification questions, the side-tracks, the "wait, but what about" detours, the dropped options, and the moment you said "OK I'll go with the second one." The extractor knows what to keep (the fork-in-the-road, the trade-offs, the chosen option, the rejected option) and what to drop (scratch thinking, formatting questions, syntax help). The output schema looks a lot like a Nygard ADR — it just got there from a different upstream.

3. They model the source-of-record differently.

adr-tools believes the source-of-record is the file in /doc/decisions/. Anything not in that folder didn't happen. WhyChose believes the source-of-record is the original chat — the Markdown extract is a reading view, with a backlink to the ChatGPT or Claude URL where you can see the full reasoning if you ever doubt the summary. That's why WhyChose works on a back-catalog: the original artifact (the conversation) already exists; we're just indexing it.

4. The team-sharing model is different.

adr-tools shares through Git: anyone with repo access can read the ADRs, no other tooling. WhyChose generates a private share-link for the decision log — the new CTO who doesn't have repo access yet can read why you picked Postgres before they merge their first PR. Both are reasonable; they just match different team shapes.

5. Maintenance posture.

adr-tools (npryce fork) hasn't shipped a release since 2018. That's not a knock — the tool is 200 lines of bash, and there isn't much to maintain. WhyChose is brand-new and actively shipping (build-in-public log at /changelog). If you want a tool that's frozen in time and unlikely to surprise you, adr-tools wins. If you want one that's improving, WhyChose.

When to use which (or both)

Use adr-tools alone when your team is small (≤5 engineers), you've established the discipline of writing ADRs at decision-time, and you don't have a back-catalog to recover. There's nothing for WhyChose to do here.

Use WhyChose alone when you don't have an ADR habit, you're not going to start one, and your decisions all happen in ChatGPT/Claude. Quarterly extraction is the only realistic capture mechanism for that shape of work.

Use both when you've decided to start writing ADRs going forward (use adr-tools for that) AND you have 6+ months of un-documented decisions buried in chat (use WhyChose to recover them). The output schemas don't conflict — a WhyChose record can be promoted to a hand-written ADR with a paste.