ADR Tooling Comparison — adr-tools vs Log4Brains vs adr-log vs Hand-rolled

The two distinct jobs ADR tooling does

Before comparing tools, it is worth separating the two jobs that ADR tooling can do, because different tools do different subsets:

1. Creation tooling — scaffolds new ADR files with correct numbering, template, and initial status. adr-tools, adr-log, and hand-rolled scripts are creation tools. Log4Brains is not — it does not create files.
2. Publication tooling — renders the ADR directory as a browsable web interface with filtering, search, and status badges. Log4Brains is a publication tool. adr-tools generates a plain-text TOC but not a web UI. adr-log generates a Markdown index file.

Most teams that use Log4Brains also use adr-tools for creation — they are not competing options. The confusion arises because they're often mentioned in the same breath when teams are evaluating "ADR tooling," and teams assume they must pick one. In practice, the creation tool and publication tool are independent choices.

A third job — CI enforcement — is handled by the ADR GitHub Action regardless of which creation or publication tool the team uses. The GitHub Action validates format, checks supersession pointer integrity, and auto-generates an index on every PR. It is not listed in the comparison below because it is not a competing tool — it is a companion to any of them.

Feature comparison

adr-tools: the original, still the reference

adr-tools (github.com/natemoen/adr-tools, originally by Nat Pryce) is the most referenced ADR creation tool in tutorials, blog posts, and the adr-tools GitHub Discussions forum. Its three commands — adr init doc/decisions, adr new "Title of decision", and adr generate toc — cover the creation and indexing use cases. The format it produces is Nygard's original five-section template.

The practical limitation is what it does not do. adr-tools creates numbered files and generates a plain-text table of contents. It does not validate supersession pointers, does not detect format drift, and does not produce anything non-engineers can browse without navigating a git repository. Teams that need those capabilities add the ADR GitHub Action for validation and Log4Brains for publication — treating adr-tools as the creation utility only.

Maintenance-wise: adr-tools is stable in the sense that it does not break and its core commands still work. It is not actively maintained in the sense that open issues receive no response. This is fine for a Bash utility whose feature set is intentionally limited. If you need a specific feature (monorepo support, MADR format, web UI), look elsewhere rather than waiting for adr-tools to add it.

Log4Brains: the publication layer

Log4Brains (github.com/thomvaill/log4brains, by Thomas Vaillant) solves a different problem than adr-tools: it makes the ADR directory browsable by people who do not use git. log4brains preview starts a local Next.js development server; log4brains build generates a static site suitable for GitHub Pages or any static host. The generated site includes: a decision timeline, status badges (Proposed / Accepted / Superseded / Deprecated), a supersession graph showing which ADRs replaced which, and full-text search across all decision records.

Three non-obvious requirements for GitHub Pages deployment:

1. fetch-depth: 0 in the checkout Action step — Log4Brains extracts decision dates from git commit history; a shallow clone (the GitHub Actions default) produces wrong dates or fails date extraction entirely.
2. A .nojekyll file at the repo root or in the docs output directory — GitHub Pages runs Jekyll processing by default, which strips files and directories whose names begin with an underscore; the Next.js static output uses _next/ for its asset directory, which Jekyll silently removes.
3. Log4Brains reads Nygard-format Markdown natively. If your team uses MADR format with YAML frontmatter, it also reads that. If your files use a custom format, the title and status extraction may fail — check log4brains preview locally before deploying.

Three limitations teams hit most often, and their mitigations:

• Build time scales with git history depth. A repository with 5+ years of history may take 2–4 minutes for log4brains build because it walks the full log for date extraction. Mitigation: cache the build output between deployments; use a paths filter in the GitHub Action to only rebuild when doc/decisions/** changes.
• Custom ADR templates require forking. Log4Brains renders templates it knows about (Nygard, MADR). A team that added custom frontmatter fields (e.g., a Risk-level field or a Decision-by field) will see those fields not rendered in the web UI. Mitigation: use the custom fields in the Markdown file and accept they won't surface in the web view; or contribute a template PR to the Log4Brains repo.
• The generated site requires JavaScript. Log4Brains produces a Next.js SSR-style site that requires JS for search and navigation. Environments with strict CSP policies or restricted network access (some enterprise intranet proxies) may block the Next.js runtime. Mitigation: for restricted environments, consider Docusaurus or MkDocs with the Material theme, which produce server-renderable HTML.

adr-log: MADR-native, Markdown-output

adr-log (github.com/adr/adr-log, maintained by the MADR project contributors) is a Node CLI designed for teams using the MADR (Markdown Architecture Decision Records) format. Its primary output is a Markdown index file rather than a web UI — adr-log -d docs/decisions writes a formatted index.md listing all ADRs with status, date, and title. This file can be rendered by GitHub's native Markdown viewer, making the decision log browsable without any build step.

The trade-off is scope. adr-log does one thing (generate a Markdown index) well. It does not generate a web UI, does not validate pointers, and does not support monorepos. Maintenance is minimal — the last release was 2022. For teams committed to MADR format who want a simple index file that renders in GitHub without dependencies, adr-log is useful; for teams that want more, the ADR GitHub Action's auto-index job (job 4) produces the same Markdown table via a standard Action without any separate package installation.

Hand-rolled: the zero-dependency option

Many ADR practices that are described as "using adr-tools" actually use nothing but a template file and the convention that filenames start with a zero-padded four-digit number. The hand-rolled approach is this: copy a template.md into the repo, document the naming convention in the README, and rely on humans to increment the number and update the index table.

The failure mode is predictable: numbering collisions on merge (two engineers open PRs with 0042-*.md on the same day), an index table that goes stale, and no validation that Superseded-by pointers point to files that exist. These are the three exact problems that adr-tools and the ADR GitHub Action respectively solve.

The hand-rolled approach works in three specific contexts:

1. Teams with very low ADR creation rate (fewer than one per month) where the manual overhead is genuinely negligible.
2. Environments where installing any runtime (Bash scripts, Node packages) requires a security review that would take longer than the ADR practice's first quarter.
3. Teams adopting ADRs retrospectively by extracting past decisions from AI chat exports — where the numbering starts from a specific historical date rather than zero and the auto-numbering assumption does not match the retrospective ordering.

If you go hand-rolled, the minimum viable safeguard is a CI check that asserts all filenames match the ^\d{4}- pattern and that no two files share the same four-digit prefix. This catches numbering collisions at PR time without requiring any tooling installation.

Decision tree: which tool for your situation

Start here and follow the first matching branch:

1. Do non-engineer stakeholders (PMs, executives, new hires without git access) need to browse decisions?
   → Yes: add Log4Brains as your publication layer. Also add adr-tools or hand-rolled for creation unless Log4Brains' log4brains adr new subcommand (which delegates to adr-tools) is acceptable.
   → No: skip Log4Brains.
2. Are you using MADR format specifically (with YAML frontmatter and the Options Considered section)?
   → Yes: consider adr-log for its native MADR awareness and Markdown-index output. Pair with the ADR GitHub Action for validation.
   → No: use Nygard format.
3. Do you need consistent auto-numbering without manual tracking?
   → Yes: use adr-tools (adr new handles numbering). No Node required, works in any CI with Bash.
   → No (low ADR rate, retrospective import, or managed manually): go hand-rolled.
4. In all cases: add the ADR GitHub Action for CI enforcement regardless of your creation tool. The Action's supersession integrity check (job 3) and auto-index job (job 4) work with Nygard or MADR format, and with adr-tools-, adr-log-, Log4Brains-, or hand-rolled ADR directories.

The gap all four tools share

Every tool in this comparison helps you manage ADRs you have already written. None of them surfaces the decisions that never reached the ADR directory in the first place — made in a ChatGPT or Claude tab during an implementation sprint and never formalized.

The pattern is common: a team adopts adr-tools or Log4Brains, writes ADRs diligently for a quarter, then velocity drops as newer decisions get made conversationally in AI sessions that feel too small or too uncertain to warrant a formal ADR. Six months later, the decision log has 20 ADRs and 80 undocumented calls. The new engineer asks why the team chose the message queue vendor, and the answer lives in a ChatGPT conversation that nobody exported.

The WhyChose extractor reads your AI chat exports (ChatGPT or Claude) and surfaces those informally-made decisions as structured records. The extracted records can be promoted to ADRs via any of the tools above — the WhyChose output includes the original chat snippet and trade-offs considered, which maps directly to Nygard's Context and Consequences sections. The tooling choice for creation, validation, and publication is orthogonal to the extraction step.

Get early access

Related questions

Further reading

• Log4Brains in depth — install, configure, and deploy to GitHub Pages — full setup guide for the publication layer: log4brains.yml config, workspace mode for monorepos, the fetch-depth and .nojekyll GitHub Pages requirements, and the three limitations teams hit most.
• The ADR GitHub Action workflow — the four-job CI pipeline (format validation, numbering, supersession integrity check, auto-index generation) that works alongside any creation or publication tool in this comparison. Adding it is the single highest-leverage ADR tooling decision for teams that already write ADRs inconsistently.
• The Nygard ADR template (2026 edition) — the five-section format (Title, Status, Context, Decision, Consequences) that adr-tools produces natively and that Log4Brains reads. Understanding the format is prerequisite to evaluating the tools that produce it.
• ADR adoption guide — rolling out the practice to a skeptical team — tooling is one dimension of adoption; the harder dimension is convincing the team to write ADRs at all. The guide covers the retrospective-first approach that works better than starting with a fresh template and hoping the team fills it.
• When to retire an ADR — deprecation, supersession, and the never-delete rule — the lifecycle endpoint that no tooling comparison covers: what to do with ADRs that are no longer operative, and why the tooling choice affects how clean the retirement protocol can be.
• ADR template in Obsidian — Dataview queries, auto-numbering, and the supersession Canvas — Obsidian + Templater is a distinct tooling combination that doesn't appear in the four-tool matrix above: it handles creation (Templater auto-numbering) and queryability (Dataview status dashboards) within a personal vault, but still needs adr-tools or a GitHub Action for CI enforcement and Log4Brains or Obsidian Publish for the non-engineer web view.
• ADR template in Linear — Documents, custom properties, and the graduated handoff — Linear occupies a different layer from the four tools above: it is a collaborative drafting surface (mutable, linked to Issues and Projects) rather than a creation or publication tool. The recommended pattern pairs Linear Documents for the drafting/review phase with adr-tools or a hand-rolled script for graduating the committed Markdown file, and Log4Brains optionally for publication. The graduated handoff pattern explains when and how to move an ADR from Linear to git.
• ADR template for Jira — custom fields, Confluence integration, and the graduated handoff — Jira occupies a similar layer to Linear in this landscape: a project management tool used as a drafting and review surface rather than a creation or publication tool. The Atlassian-stack pattern (Jira Issues for metadata + Confluence pages for body text) is the enterprise variant of the same graduated-handoff workflow. Neither adr-tools nor Log4Brains is aware of Jira Issues — the committed Markdown file in git is the integration point that all tooling in this comparison can read.
• ADR template for Azure DevOps — Repos, Wiki, and Work Items — the Azure DevOps variant of the same graduated-handoff pattern. adr-tools and Log4Brains integrate with ADO Repos identically to GitHub — both operate against local file paths and push via standard git, so the tooling comparison above applies unchanged. The ADO-specific additions are: Architecture Decision Work Items (custom fields for ADR lifecycle metadata, linked to triggering Epics via the Related link type) and an Azure Pipelines Build Validation policy that enforces ADR frontmatter structure on pull requests — the ADO equivalent of the GitHub Action referenced above.
• VS Code ADR template — extensions, snippets, and workspace setup — the editor-layer complement to this comparison: ADR Manager (mnater-dev.adr-manager) provides VS Code command-palette integration with auto-numbering that works alongside all four tools above; workspace snippets handle template expansion; markdownlint enforces the heading structure that Log4Brains and the GitHub Action rely on.
• The open-source extractor — surfaces the decisions buried in your ChatGPT and Claude exports, producing Nygard-compatible records that any of the tools above can ingest as starting-point ADRs.