WhyKit keeps every decision next to the sources behind it, as plain Markdown in your repo. Claude Code, Codex, Cursor and other MCP clients look it up before they act, and your CI flags a decision as soon as its evidence goes out of date.
uv tool install 'whykit[mcp]'
Three real questions, each answered through the WhyKit MCP server by the agent shown, on 7 Nov 2026, using the Northline example vault. Transcripts.
Five questions on 7 Nov 2026. Every answer cited the decision and its source.
Average of the three timed runs: 15.6, 16.2 and 18.9 seconds.
The server is read-only. The test suite runs it and checks the vault bytes did not change.
WhyKit ships a read-only MCP server. Add it to Claude Code, Codex, Cursor or any other MCP client, point it at your vault, and the agent can look up decisions and their sources instead of guessing from the code. It cannot change a single file.
Each setup was run on 7 Nov 2026. By default the server only returns records labelled
internal or lower; --max-sensitivity changes that.
MCP guide.
context · trace
impact · backlinks
query · pack
status
Explorer is an optional, read-only viewer built from the same Markdown files. This is the Northline example: its decisions, which record replaced which, the sources and what is due for review.
Recorded on 7 Nov 2026 in real time from a local build of Explorer for
examples/northline at commit 73d6833. Nothing is sped up.
List your sources, such as an interview, a report or a dashboard, and give each a short ID. A decision is a Markdown note that says what you chose and which sources back it. Nobody edits an approved decision: you write a new one that replaces it, so the history stays readable.
Say what it is and where someone can check it.
whykit new evidence
What you chose, why, and what you turned down, with the sources it rests on.
whykit new decision
The same check runs on your laptop and in every pull request.
whykit check --profile ci
Every decision has a review date, and WhyKit lists the ones that are due.
whykit review list
Sources get retired and decisions pass their review date. whykit check runs in every pull
request and fails when a decision still in force rests on something that no longer holds. Below, a
source is retired and the next check fails.
Staged animation. Records and messages are real WhyKit 0.4.0 output on the Northline example vault.
evidence.retiredevidence.missingwhykit historyreview_by.overduewikilink.missingsecret.detecteddecision.placeholder
The first six were produced by changing a copy of examples/northline; the last by the README
quickstart. The full rule list is in
docs/rules.md ↗.
The same check runs as a GitHub Action on every pull request. Set it up in your repository ↗
Everything lives in Markdown files in your repository. Explorer, the command line and the MCP server only read them, so there is no second copy to keep in sync. The folder also opens in Obsidian.
A static site with no server code. It can also be built as one HTML file that opens from disk.
$ whykit status --today 2026-09-17 documents 57 decisions 11 evidence 14 active / 1 retired lint 0 error(s), 0 warning(s) review queue 1 due within 30 day(s) --json on every vault command
Query, trace, impact and context commands, with versioned JSON output for scripts and CI.
$ whykit-mcp --root ./vault
tools query · context · impact
status · pack · trace
backlinks
resource whykit://decisions
ceiling --max-sensitivity internal
writes none
Gives an agent read-only access to the vault over stdio or loopback HTTP, filtered by a sensitivity ceiling.
Python 3.11 or newer and uv. These are the README's commands; they were run against WhyKit 0.4.0 from PyPI on 7 Nov 2026.
Install the CLI as a uv tool, then create a vault: a folder of Markdown files.
Register a source, then a draft decision that cites it.
See the link, then lint. Five warnings name the work the template still needs.
Apache-2.0 code, tests on every push, reproducible builds and a security policy that says what the tool does not protect.
The suite runs on Python 3.11, 3.12, 3.13 and 3.14 and again on Windows, and both example vaults are linted strictly.
The core package uses the standard library alone. CI builds an SBOM of the installed wheel and fails if anything else appears in it.
CI builds the wheel and source distribution twice from one commit and requires identical bytes.
A test breaks the socket layer and runs every vault command. There is no telemetry, account or service.
Releases reach PyPI from a tag-triggered workflow with PEP 740 attestations. No PyPI token is stored in the repository.
Every workflow action is pinned to a commit, workflows are audited with zizmor and history is scanned for secrets with gitleaks.
These limits are part of the product contract, not small print.
A clean check says a decision cites its sources. It cannot say the source is honest or the decision right, and an agent can still ignore what it reads.
WhyKit does not check external sources for changes. It reports passed review dates; the re-read is yours.
Sensitivity labels filter what the MCP server returns. Repository permissions are the only access control, so keep real vaults private.
Version 0.4 adds optional note types older clients do not understand. Read the feature status and the upgrade guide first.
Connect it to your agent, ask about a decision in the Northline example, then start a ledger for the decisions you will be asked about later.
