adrkit
Decision memory for human- and agent-authored plans — architecture decision records that are machine-readable, enforceable in CI, and legible to agents, without leaving git.
Power your agent
The publisher's own command. Not a PlugMCP endpoint.
Host a copy with our keys and logs.
npx -y @adrkit/[email protected]Claude Code has no install link for a local command. Copy the command below and run it in a terminal.
claude mcp add adrkit-mcp -- npx -y @adrkit/mcp@0.20.0Run in a terminal.
{ "mcpServers": { "adrkit-mcp": { "command": "npx", "args": [ "-y", "@adrkit/[email protected]" ] } }}claude_desktop_config.json
Remote URL or a command on your machine? How the two installs differ
Run on PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
LaunchFrom the publisher
Most ADR tooling is a markdown template and a static site generator. That
records a decision; it doesn't make the decision do anything. adrkit treats a
record as typed data with a markdown body and adds one field — affects —
so a tool can answer "which decisions govern this pull request?" and put the
answer where the next decision is being made.
An 80-second tour, from the terminal to the pull request to the GitHub Copilot app:
A still of the final screen. Select it to watch the 15-second recording.
On a pull request, the governing-decisions Action posts that answer as a comment, and GitHub Copilot code review can cite a record because it lives in the repository:
mbeacom/adrkit-demo is a small
payments-ledger repository with these pull requests open, a managed ARB queue
issue, and recordings of every command.
Generated knowledge systems answer "how does the system work now?" adrkit answers "what did people decide, what alternatives were rejected, and which decisions govern this change?" ADR-0037 sets that boundary: generated knowledge systems are downstream read models of adrkit's human-reviewed decision corpus, never decision authorities.
Tools such as OpenWiki can consume ADRs as evidence and turn them into browsable current-state documentation. That is complementary to adrkit: the generated wiki is a downstream read model, while the reviewed records in git retain authority over decision lifecycle and typed relationships. Machine verification of generated content is not human ratification of a decision.
See the provisional generated-knowledge guide for the OpenWiki setup being evaluated and the ownership boundary ADR-0037 sets between the two tools.
The CLI is published as @adrkit/cli
and exposes the adr binary. Published artifacts target Node 22+:
npx @adrkit/cli lint # validate the corpus in docs/adr
npx @adrkit/cli explain src/payments/api.ts # which decisions govern this file?
Or add it to a project (Bun-first repos can use bun add -D @adrkit/cli / bunx):
npm i -D @adrkit/cli
The pure library surfaces install independently:
npm i @adrkit/core @adrkit/evaluator.
See the Quickstart guide and the full command reference.
Beginning with the first lockstep release containing
ADR-0032,
releases are published as a multi-architecture OCI image at
ghcr.io/mbeacom/adrkit. Pin an immutable vX.Y.Z tag in automation; vX
and latest move only after that lockstep release has completed:
docker run --rm --read-only --network none \
-v "$PWD:/workspace:ro" \
ghcr.io/mbeacom/adrkit:vX.Y.Z lint
docker run --rm --read-only --network none -i \
-v "$PWD:/workspace:ro" \
ghcr.io/mbeacom/adrkit:vX.Y.Z mcp
The MCP command keeps stdin open because MCP uses stdio. Its repository mount is
read-only, matching the server contract; use an absolute host path in MCP client
configuration. For CLI commands that intentionally write (new, accept,
approve, object, resolve, or migrate without --dry-run), omit
--read-only and the mount's :ro suffix. The image runs as the non-root
node user; on a host with a different UID/GID, add
--user "$(id -u):$(id -g)". On SELinux hosts, add the appropriate
bind-mount label (for example, :Z).
The default image treats an unrecognized selector as an adr subcommand.
Explicit selectors are cli/adr/adrkit, mcp/adrkit-mcp,
server/adrkit-server, ci/adrkit-ci, and
queue-action/adrkit-queue-action. The default
--help describes these selectors; cli --help opens the CLI command
reference. The container also reserves -h, container-help, and
--container-help; CLI help subcommands such as help lint otherwise pass
through unchanged.
Build the same source locally with Docker or Podman. Purpose-specific cli,
mcp, server, ci, and queue-action targets are isolated for local policy
and SBOM inspection; the registry publishes only the all-in-one adrkit target:
docker build -f Containerfile -t adrkit:local .
docker build -f Containerfile --target mcp -t adrkit-mcp:local .
docker run --rm --read-only --network none -i \
-v "$PWD:/workspace:ro" \
adrkit-mcp:local
The two CI entry points preserve the existing GitHub Actions runtime contract:
they expect GITHUB_WORKSPACE, the event payload and repository environment,
INPUT_* values, and a token. For hosted GitHub Actions, the repository-backed
Actions remain the simpler interface:
mbeacom/adrkit/packages/ci@v0 and
mbeacom/adrkit/packages/ci/queue@v0. Container publication and recovery are
documented in docs/RELEASING.md.
The governing-decisions Action also has a repository-root entry point for its
GitHub Marketplace listing. That root form is available beginning with
v0.13.0; the existing packages/ci form remains supported.
GitHub lists only root Action metadata, so the queue Action stays at its nested
path.
This server authenticates no one. Run it on localhost, or behind a gateway that authenticates every request. Anyone who can reach its port can read every corpus it serves, private repositories included.
The server selector serves a read-only REST API and the decision portal over
one or more corpora
(ADR-0055).
It answers GET and HEAD only, and every other method gets 405. Every data
response is { corpus, commit, data }. It runs no git, spawns no process, and
opens no outbound connection. It binds 127.0.0.1 unless ADRKIT_SERVER_HOST
says otherwise; inside a container that address cannot be reached from outside,
so publishing a port also takes ADRKIT_SERVER_HOST=0.0.0.0, and the server
then logs a warning. Routes, under /api/v1/corpora/{corpus}: records,
records/{id}, graph?kinds=, queue?asOf=, issues, and governing?path=.
governing matches a path against affects only and never reads the file, so
it has no @adr marker evidence. Also served: /api/v1/corpora,
/openapi.json, /healthz, and the portal at / (one corpus) or
/portal/{corpus}/.
Each corpus is a directory something else writes: the repository's records under
docs/adr (or another adrDir) and, at its top, .adrkit-corpus.json, a JSON
object holding at least { "commit": "<40 hex>" }. A corpus without a valid
sidecar is not served (503). When the sidecar's commit changes, the server
loads the new tree and swaps to it. Configure the corpora with environment
variables:
To serve a checkout of your own repository on your machine only, write the sidecar, then mount the checkout read-only:
printf '{"commit":"%s"}\n' "$(git rev-parse HEAD)" > .adrkit-corpus.json
docker run --rm --read-only -p 127.0.0.1:8080:8080 \
-v "$PWD:/workspace:ro" \
-e ADRKIT_SERVER_HOST=0.0.0.0 -e ADRKIT_SERVER_CORPORA=adrkit=. \
ghcr.io/mbeacom/adrkit:vX.Y.Z server
The -p 127.0.0.1: prefix keeps the published port on the host's loopback.
This server has no --network none mode, because it listens for requests, but
it never needs a writable mount.
adr queue emits the review backlog as a deterministic, read-only projection of
the corpus — byte-for-byte identical for identical inputs:
# ARB Queue — 2026-07-25
Corpus fingerprint: `96e7f3185c5bb89bd1c87e10a28dcbef66703f381d3f14ea486ceaf29903cb00`
7 item(s) | 0 corpus finding(s) | 0 item(s) with findings
## Queue Items
| # | ID | Title | Tier | SLA State | Deadline | Approvals | Objections |
|---|----|-------|------|-----------|----------|-----------|------------|
| 1 | `0005` | Gate proposals with a deterministic-first evaluator … | arb | within-sla | 2027-01-18 | 0/- | 0 |
| 2 | `0015` | Validate descriptors against Backstage field formats … | arb | within-sla | 2027-01-25 | 0/- | 0 |
That is what a pipe, a CI job, or an agent receives. In a terminal the same report prints as a list sized to the window, and each item ends with its next step — the command to accept it, or the reason it cannot be accepted yet:
1. 0044 within-sla · due 2027-03-31 (in 182 days)
Ratify a proposed record with adr accept and present the queue for terminals
async · asynchronous human review
approvals 0 · objections 0 · route @mbeacom
docs/adr/0044-ratify-a-proposed-record-with-adr-accept-and-present-the-queue-for-terminals.md
next: adr accept 0044 --by <identity>
adr accept 0044 --by @you then sets status, provenance.ratifiedBy, and
review.decidedAt, and changes no other line, for review in a pull request.
In CI, the @adrkit/ci Action comments the governing decisions on the PRs that
touch them — read-only, comment-only, no database, no approval. See
Use in CI.
The most differentiated hook: @adrkit/mcp is a local, read-only
Model Context Protocol server that lets an
agent retrieve prior decisions — including the rejected and superseded ones —
before proposing something already tried. No writes, no HTTP/auth, no model,
embedding, or network access, and no persistent index. It exposes exactly four
tools:
Run it against a repository's corpus:
npx @adrkit/mcp # or the adrkit-mcp bin
adrkit-mcp --cwd /path/to/repo --dir docs/adr
--cwd (env ADRKIT_MCP_CWD) must be a Git worktree root; --dir (env
ADRKIT_MCP_DIR, default docs/adr) is resolved within it. stdout carries only
JSON-RPC frames; diagnostics go to stderr; the graveyard is included by default.
See the MCP setup guide and
packages/mcp/README.md for the full tool contracts.
Spec Kit takes you from specify to
plan to tasks to implement. What it does not do is check the plan it just
produced against the decisions you already made, or record the new decisions
that plan contains — so every feature starts from an empty context and
re-litigates settled questions.
@adrkit/spec-kit closes that loop:
Plus one after_plan hook that offers to run the check. It is optional by
construction, and hooks can only reach commands that do not write — draft is
deliberately unreachable from any hook, because a plan-phase hook creating
records unprompted would manufacture decision memory rather than record it.
Pinned to Spec Kit >=0.13.0,<1.2.0 and tested against 0.13.0, 0.14.4, 0.15.1,
0.16.5, 1.0.0, 1.0.4–1.0.6, 1.0.13, and 1.1.0–1.1.3. It is listed in the Spec Kit community catalog,
which is discovery-only, so install it from its release archive with
specify extension add adrkit --from <zip URL>; see the package README for the
URL and setup. Under the Claude Code integration, and under Copilot from Spec
Kit 0.16.5 on, Spec Kit registers these as skills, so you type
/speckit-adrkit-check rather than /speckit.adrkit.check.
Spec Kit is one workflow. The place plans are actually written now is inside a coding agent that has no idea your decision corpus exists.
packages/adapters/agent-plugin
packages the same loop as portable agent components — installable into GitHub
Copilot CLI, Claude Code, opencode, and anything
APM targets:
copilot plugin marketplace add mbeacom/adrkit && copilot plugin install adrkit@adrkit
/plugin marketplace add mbeacom/adrkit # Claude Code, then /plugin install adrkit@adrkit
apm install mbeacom/adrkit/packages/adapters/agent-plugin --target opencode
Every component shells out to the adr CLI, so install that too if you have not
already — npm i -g @adrkit/cli, or add @adrkit/cli to the project. The
components resolve it from $ADRKIT_CLI, then ./node_modules/.bin/adr, then
PATH.
In the GitHub Copilot app, the plugin also adds two canvases. The
decision-review
canvas shows which decisions govern the session's uncommitted change and can
start an adr-review run. The
decision-board
canvas maps the corpus from adr graph and adr queue. Its approve and object
controls write only after the app's own confirmation dialog, and neither canvas
can ratify a record. Both are at rung 1.
It deliberately ships no MCP configuration: Copilot CLI spawns a plugin's
MCP servers outside the workspace, and outside any Git repository, so the adrkit
server exits during initialize. MCP is wired per project instead — see the
plugin README
for the host-specific setup and
ADR-0028.
The backfill expansion is authorized by
ADR-0034.
Status: installable today from this repository and versioned independently from the npm packages. It makes the context -> check -> backfill -> draft loop available inside current coding-agent hosts.
The backfill workflow is read-only until a human selects a candidate. See the
guide for source routing, evidence thresholds,
status treatment, and the /adr-backfill → /adr-draft handoff.
Independently versioned per ADR-0007. The original context/check/draft/queue workflow is at rung 1 of ADR-0014 — unit and contract coverage plus maintainer verification against the installed hosts. The v0.2.0 backfill addition is contract- and static-host-validated and has a fresh functional Copilot synthetic-consumer run proving candidate reconciliation and no writes. No persistent reference-repository run or external validation exists for the plugin.
Your organization decides something. Six months later nobody remembers, the decision gets re-litigated, and the code drifts from what was agreed. Now agents write plans too — faster than anyone can review them, with no memory of what was already decided and rejected.
Treat a decision record as typed data with a markdown body, and give it one
field that changes everything — affects, declaring what the decision governs:
---
id: "0042"
title: Use server-side rendering for authenticated routes
status: accepted
reversibility: one-way-door
blastRadius: cross-team
affects:
- type: path
pattern: "apps/web/app/\\(authed\\)/**" # ( and ) are glob syntax — escape them
- type: package
pattern: "next@>=16"
---
Now a tool can answer "which decisions govern this pull request?" — and put the answer where the next decision is actually being made.
adr lint — validate records, catch supersession cycles, find decisions
that silently contradict each other. Warns when markdown under the corpus
directory is not discoverable, so "checked 0 records" is never silent.adr migrate --from madr — adopt an existing MADR corpus in place,
additively, without breaking your current tooling. Reads status, date, and
deciders from MADR 3.x frontmatter, MADR 2.x * Status: bullets, and Nygard
## Status sections. --rename also renames each file to <id>-<slug>.md.adr explain <path> — print every decision governing a file, and why.
Decisions reach a file in two directions and the output keeps them apart: the
record's own affects pattern matched (via path: src/**), or the file
declared the decision itself with an @adr 0012 marker in a comment
(declared by src/sync.ts:3). Markers let affects stay narrow — the
defining files — while the surrounding code opts in one line at a time, in any
language, with no schema change. Only accepted records are reported as
governing; matched proposals and superseded/rejected/deprecated records are
listed separately.adr explain <path> --as-of <date|ref> — answer the same question for a
past date: which decisions governed this file when this code was written? A
record's window opens on its own date and closes on its successor's, so a
record superseded today is reported as governing then. Takes YYYY-MM-DD, an
ISO datetime with an explicit timezone, or a git ref resolved to its commit's
committer date. No schema change — the corpus already carries both halves.adr check <files...> — validate the changed records and list the decisions
governing a changed-file set, including inbound @adr declarations. Marker reads
are bounded to 3,000 files / 16 concurrent reads, 64 declarations per file, and
10,000 declarations per batch, all reported in --json; marker claims and scan
warnings never influence the exit code.adr evaluate <proposal> --snapshot <bundle.json> --date YYYY-MM-DD — run the
deterministic, model-free Pass 0 over a proposal ADR plus an immutable offline
snapshot bundle. It applies the eleven rubric rules, escalates on proven
triggers to one named active human (or an explicit unresolved), and returns
a rich Pass0Report plus a schema-compatible evaluationPatch. It reads no
model, network, clock, or (in the library) filesystem, and routes — it never
approves, persists, or writes.adr queue — emit the ARB operations queue: a read-only, deterministic
projection of the corpus's review metadata (tiers, SLA state, approvals,
objections) as Markdown or QueueReport v1 JSON, or as a list sized to the
window in a terminal; also a managed-issue Action.adr accept <id> --by <identity> — ratify a proposed record from the
queue. It changes only status, provenance.ratifiedBy, and
review.decidedAt, refuses a record with an unresolved objection, an unmet
quorum, or a result that would not validate, and never infers who ratified.@adrkit/ci GitHub Action surfaces the governing decisions
on the PRs that touch or explicitly declare them; pattern matches render as via
and PR-authored marker claims as declared by. The comment also distinguishes
marker files it could not inspect, marker declarations omitted at a safety cap,
claims it read but could not bind, and stale claims naming historical records.
All are advisory: they never fail the job.
It runs with only the default
GITHUB_TOKEN and degrades (never fails the job) on a read-only fork token.It never approves anything. It routes, and humans decide.
The root Marketplace entry point has shipped with every release since
v0.13.0. Pin its immutable root reference — currently v0.20.0 — for the
complete governing-decisions workflow (see
Use in CI):
name: ADR governing decisions
on:
pull_request:
permissions:
contents: read
pull-requests: write
jobs:
governing-decisions:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: mbeacom/[email protected]
Existing consumers of the nested form can stay on
mbeacom/adrkit/packages/ci@v0. The queue Action remains available at
mbeacom/adrkit/packages/ci/queue@v0.
A third, build-only Action, mbeacom/adrkit/packages/ci/[email protected] (pin an
immutable release tag; beginning with v0.19.0), builds a
static, read-only decision portal for GitHub Pages
(ADR-0054).
It holds no token and needs only contents: read; your workflow deploys the
directory it writes with actions/upload-pages-artifact and
actions/deploy-pages. On a private or internal repository it refuses unless
publish-private: 'true'. The full workflow is in
Use in CI.
adrkit's frontmatter is a strict MADR superset, so
this is not "instead of MADR" — you can adr migrate --from madr an existing
corpus in place. The distinction is what happens after the record exists.
A template — including a more structured MADR variant — standardizes how you write a decision. It does not:
affects and comments the governing
decisions on the PRs that change the files they govern;affects fields
(ADR-0009), not prose;rejected/superseded/deprecated records so an agent stops re-proposing them.A schema you can hand to a linter, a resolver, an agent, and a CI job is a different artifact from a heading convention. That is the whole thesis.
adrkit is still pre-1.0, but several surfaces are ready to use today. This table is the short version:
These are enforced, not aspirational. Each links to the record that decided it.
Every decision in this project is governed by this project. The repository's
first commit is its own decision corpus — see docs/adr/. The
evaluator rubric is itself versioned here too. The published evaluator currently
implements the deterministic Pass 0 only; later passes remain documented design
targets rather than released behavior.
Apache-2.0 — see LICENSE.
Exception: the contents of schema/ are additionally released
under CC0. The schema is intended to become a shared
contract; competing implementations should be able to adopt it with no license
consideration at all.
Built with Bun — see ADR-0010. Bun is a development dependency only. Nothing published by this project requires it: the CLI, the GitHub Action, and the MCP server are Node-targeted and smoke-tested under Node 22 and 24 in CI.
See CONTRIBUTING.md, including the "Your first PR" on-ramp. Contributions require a DCO sign-off, and must build from a clean clone with no credentials configured.
Local, read-only Model Context Protocol server exposing adrkit decision retrieval over stdio.
{ "mcpServers": { "adrkit-mcp": { "command": "npx", "args": [ "-y", "@adrkit/[email protected]" ] } }}Tools
No tool list yet. Remote servers get one after the first health check.
FAQ
Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.
No required environment variable is listed on this record.
@adrkit/mcp runs locally over stdio.
Last checked 2026-11-14. Local, read-only Model Context Protocol server exposing adrkit decision retrieval over stdio.