WhyKit, open source
Keep the decision. And the reason behind it.
A month later, you still know why. WhyKit connects sources, evidence and decisions in plain Markdown. Your team and AI agents return to the reasoning instead of reconstructing it from conversations.
git clone https://github.com/CometWeb-io/whykit.git Source preview, no release yet Licence Apache-2.0 Python 3.11+ and uv, no runtime dependencies
What it does
What you decided. And why.
A decision without sources quickly becomes an opinion. WhyKit keeps the path from source material to evidence, a choice and the next review.
E-001
Trace a conclusion to its source.
Connect a claim to evidence and its source. Separate verified facts from assumptions so the next person or agent knows what they can rely on.
- Readable Markdown files
- References to specific evidence
- Explicit assumptions and missing information
D-001, D-004
Keep the reasoning in history.
Leave an accepted decision as it was. When circumstances change, record a new decision and name the one it supersedes.
- Link previous and replacement decisions
- Rejected options beside the chosen approach
- CLI and CI checks
review_by
Revisit decisions before they go stale.
A review_by field sets the next review date. The linter flags overdue reviews and structural issues, so the ledger stays in use.
- A review date on each decision
- Overdue review findings
- Checks locally or in CI
How it works
From an empty folder to a checked ledger.
- Create a ledger whykit init sets up a folder with the template and an AGENTS.md beside the checkout.
- Add evidence Each source gets a stable E-NNN ID in the evidence register.
- Record a decision A D-NNN decision names its source_ids and a review_by date.
- Check the structure whykit lint runs the same way on your machine and in CI.
Installation
Run it from a checkout.
Until the first release, install WhyKit from a copy of the repository. The ledger is created beside the source, so private notes stay out of the WhyKit repository.
- Python 3.11 or newer
- uv to sync the environment
- Git with full history for change checks
git clone https://github.com/CometWeb-io/whykit.git
cd whykit
uv sync --locked
uv run whykit init ../my-ledger
uv run whykit lint --root ../my-ledgerCheck your ledger.
uv run whykit lint --root ../my-ledgerLimits
The linter checks structure. You assess the evidence.
A new ledger has zero lint errors. Its warnings point to questions in AGENTS.md that you answer before relying on agents.
- Checks structure and links; you judge whether a source is true
- No GitHub or PyPI release yet, install from a checkout
- History checks need the full Git history
Code and docs
Everything lives in the repository.
Yes, from the public GitHub repository. It is a source preview with no release or PyPI package yet, so you install it from a checkout with uv.
In Markdown files inside your own ledger. Change history uses Git. WhyKit does not require a hosted database.
It works beside them. WhyKit organizes sources, evidence and decisions in readable files that agents can use, while vector search and chat history stay in your other tools.
From website analysis
to action.
CometWeb Insight checks five quality areas, prioritises fixes and re-tests the site after you ship.