WhyKit

The layer that remembers why.

Git-native evidence and decision ledger for teams and AI agents.

WhyKit keeps sources, decisions, their reasoning, and review events together in plain Markdown and Git. It gives people and tools a shared, inspectable record of what is known, what was decided, and what still needs checking.

Python 3.11+ · No runtime dependencies · Apache-2.0

Status: 0.3.1 release preparation. No GitHub Release and no public PyPI release yet. Install from a source checkout until publication is verified. This checkout is not a tagged release.

60-second quickstart

You need Python 3.11+ and uv. WhyKit is not on PyPI yet, so run it from a checkout. The vault goes next to the checkout, never inside it.

git clone https://github.com/CometWeb-io/whykit.git
cd whykit
uv sync --locked

# 1. Create a vault.
uv run whykit init ../my-ledger

# 2. Register a source, then a decision that cites it.
uv run whykit new --root ../my-ledger evidence \
  --source "Support ticket export, Q3" --type dataset \
  --location "https://example.com/exports/q3-tickets.csv" \
  --claims "Most onboarding tickets mention SSO"
uv run whykit new --root ../my-ledger decision "Ship SSO before audit logs" \
  --owner Platform --status draft --source E-001

# 3. Check the vault and see what is due for review.
uv run whykit lint --root ../my-ledger
uv run whykit review --root ../my-ledger list --due-days 120

What you should see:

created E-001: 00-context/evidence-register.md
created D-001: 06-decisions/d-001-ship-sso-before-audit-logs.md
...
24 files — 0 error(s), 5 warning(s)
0 review(s) overdue or due by <date> (120 day(s) from <today>)

The vault now holds an evidence row (E-001), a decision record that cites it (D-001), and a matching decision-log entry. The record is a draft until you complete and approve it. Four of the warnings are the questions in the vault's AGENTS.md that only you can answer (reply language, branching rule, tone-of-voice owner, safety rules). The fifth, decision.placeholder, says the new record still holds the scaffold's prompts: open it and write the real context, decision, rationale, alternatives and consequences. Do both before you let an agent write in the vault, or before you turn on the strict ci gate.

--root can go before or after the subcommand (whykit new --root ../my-ledger decision ... and whykit new decision ... --root ../my-ledger both work). Inside the vault directory you can drop --root altogether.

Next: write the real context and rationale into 06-decisions/d-001-*.md, preview and approve the completed record, git init the vault, and commit it. Choose a complete workflow:

• Import an ADR, review changed evidence and export public data: keep source provenance, find the affected decision and retain its review warning in a filtered export.
• Record, check and supersede a decision: replace an accepted choice without rewriting its reasoning.
• Gate pull requests in GitHub Actions: check changes against a trusted Git baseline.

Why WhyKit

Teams can find old documents but rarely tell which evidence supported a decision, what replaced an earlier choice, or when anyone last checked that the reasoning still holds. WhyKit makes those links explicit and checks them:

source (E-001) → decision (D-001) → dated review events

Use that record to answer three questions: which decision applies, which sources support it, and what needs review when an input changes. Public exports keep permitted records and their known warnings while filtering non-public data.

• Evidence stays traceable. Each source gets a stable ID and a location a person can inspect.
• Accepted reasoning stays intact. You supersede a decision instead of rewriting it, and CI rejects a diff that edits accepted reasoning.
• Reviews have dates. Every approved decision carries a review_by date, and overdue ones fail the strict gate.
• The same rules run everywhere. One whykit.toml drives local runs, CI, the pre-commit hook and agents, with a versioned JSON contract and a read-only MCP server for tools.

WhyKit checks structure and traceability, not whether a source or conclusion is true. It is not an AI memory service, a vector database or an access-control boundary; Positioning says when plain ADRs are the better choice.

Documentation

Start at the documentation index. The most used pages:

• Concepts: evidence, decisions, supersession and the review cycle.
• How-to guides: adopt existing Markdown, manage evidence, hand context to agents.
• CI integration and troubleshooting.
• Command reference, configuration and lint rules.
• Automation (JSON contract) and the MCP server.

The example vaults show the format at two scales: tiny and the fully linked, fictional Northline.

Contributing · Code of Conduct · Security policy · Release checklist

Copyright 2026 Maciej Zmitrukiewicz (hello@cometweb.io), licensed under Apache-2.0. CometWeb is the product name, not the copyright holder.