whycode 0.4.7

Verified decision provenance for AI-assisted development — memory, AST provenance, and quality verification.

WhyCode

Ask why any function exists. Get the decision that created it.

WhyCode is an MCP server that gives AI coding agents persistent memory, bidirectional code provenance, and independent quality verification. It works with Claude Code, Cursor, Windsurf, and any MCP-compatible client. Free forever for solo developers. Apache 2.0.

See it in action

$ provenance.reverse("backend/auth/auth_service.py", "hash_password")
decision   Use Argon2id for all password hashing
recorded   Apr 10 · claude-code · session sess_a1b2
rationale  OWASP 2024 recommendation, memory-hard, GPU-resistant
commit     a1b2c3d — [P1] Auth service with Argon2id hashing
changes    hash_password (added), verify_password (added)
verified   CI passed · run #9912 · Apr 10 10:12

$ drift.check("my-saas-project")
warning    backend/cache/redis.py imports asyncpg directly
violates   decision dec_007: "All DB access through db_backend.py"

Quick start

Requires Node.js 18+. Python 3.11+ installed automatically.

npx whycode@latest init-and-serve

Open http://localhost:8100 — a 5-step walkthrough gets you to your first provenance query in under 5 minutes.

Works with: Claude Code · Cursor · Windsurf · Any MCP client Runs on: Windows · macOS · Linux Backends: Git and non-git projects

What WhyCode does

Bidirectional code provenance

Every architectural decision links to the exact code it produced — down to the AST level. Ask why any function exists and get back the decision, the commit, and the CI verification.

Active context injection

Relevant decisions are injected automatically before every session and every file edit via Claude Code hooks. Your agent knows your architecture before it types a character. No manual prompting required.

Independent quality harness

Five sensors — coverage delta, complexity, import health, drift violations, decision density — running independently of what the agent reports. Catches tautological tests that prove implementation instead of specification.

Architectural drift detection

Compares your import graph against recorded architecture decisions in real time. Catches violations before they compound into a refactor.

Rollback impact planning

Before reverting any decision, see the full downstream dependency graph — which functions break, which decisions become orphaned, and the risk level.

How it works

1. Install once

npx whycode@latest init-and-serve

One command on any OS. Python venv, server, and MCP config handled automatically.

2. Init each project

whycode init

Creates config, git hooks, and a project CLAUDE.md that instructs the agent.

3. Work normally Open Claude Code or Cursor. Context is injected automatically. Record decisions when you make architectural choices.

4. Query anything

provenance.reverse("path/to/file.py", "function_name")
drift.check("project-name")
harness.score("session-id")

What makes WhyCode different

Most AI memory tools give agents session memory — the ability to recall past conversations and past context.

WhyCode does something different: it links decisions to code.

When your agent writes a function, WhyCode records why — and you can ask "why does this function exist" and get back the decision, the commit, and the CI result that verified it.

Capability	WhyCode	Typical AI memory tools
Semantic memory	✓	✓
Decision → code provenance	✓	—
Reverse trace: code → decision	✓	—
CI verification linked	✓	—
Drift detection	✓	—
Tautological test detection	✓	—
Rollback impact planning	✓	—
Auto context injection via hooks	✓	partial

Installation

One command (recommended)

npx whycode@latest init-and-serve

Requires Node.js 18+. Detects or installs Python 3.11+ automatically.

Custom port

npx whycode@latest init-and-serve --port 9000

Team mode

npx whycode@latest init-and-serve --mode team

Python directly

pip install whycode
cd your-project
whycode init
whycode serve
whycode connect

Per-project setup

Once the server is running, initialise each project:

cd your-project
whycode init

One server serves all projects simultaneously.

Configuration

WhyCode generates whycode.toml in each project directory. See whycode.toml.example for all options.

Key settings:

[server]
port = 8100        # change if 8100 is in use
mode = "solo"      # or "team" for shared server

[embedding]
backend = "local"  # or "ollama" for higher quality

[billing]
open_beta = true   # all features free during beta
enabled = false    # set true when Stripe configured

MCP client support

whycode connect auto-configures all detected clients.

Client	MCP tools	Auto context	File hooks	Auto session
Claude Code	✓ full	✓	✓	✓
Cursor	✓	✓ via tool	✓ via before_edit	✓ inactivity
Windsurf	✓	✓ via tool	✓ via before_edit	✓ inactivity
Claude Desktop	✓	✓ via tool	✓ via before_edit	✓ inactivity
Any MCP client	✓	✓ via tool	✓ via before_edit	✓ inactivity

OAuth login setup (optional)

WhyCode supports Google and GitHub OAuth for dashboard login. OAuth is optional — the solo bearer token works for both the dashboard and MCP clients without any additional setup.

Show your solo bearer token

whycode token show

Paste the token into the dashboard login form, or run whycode token write-config --client claude-desktop to wire it into Claude Desktop automatically.

Configure Google OAuth

1. Go to https://console.cloud.google.com
2. Create a project → APIs & Services → Credentials
3. Create an OAuth 2.0 Client ID → Web application
4. Add http://localhost:8100/api/auth/oauth/google/callback as an authorised redirect URI
5. Copy the client ID and secret, then run:

whycode config set-oauth --provider google

Configure GitHub OAuth

1. Go to https://github.com/settings/applications/new
2. Homepage URL: http://localhost:8100
3. Authorization callback URL: http://localhost:8100/api/auth/oauth/github/callback
4. Copy the client ID and secret, then run:

whycode config set-oauth --provider github

Restart the server after configuring: whycode serve.

Contributing

git clone https://github.com/whycodeAI/whycode.git
cd whycode
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pytest tests/ -v

Before submitting a PR:

• ruff check . must pass
• mypy --strict backend/ must pass
• pytest tests/ --cov=backend --cov-fail-under=82 must pass
• No new runtime CVEs (pip-audit)

See docs/CONTRIBUTING.md for full guidelines.

Security

WhyCode stores no credentials in its database. All secrets live in your OS keyring or an AES-256-GCM encrypted vault file. Passwords are hashed with Argon2id (64MB, 3 iterations, parallelism 4).

See docs/SECURITY.md for the complete security model.

To report a vulnerability: open a GitHub Security Advisory or email [e-mail]

Benchmarks

Retrieval quality measured against LongMemEval-S and LOCOMO datasets. Results in scripts/benchmark/README.md.

Run benchmarks yourself:

pip install whycode[benchmark]
whycode-benchmark run --dataset longmemeval --output results.json

Pricing

Solo — Free forever. Full capabilities. Apache 2.0. Self-hosted. All features available during open beta.

Team — $9/seat/month (min 2 seats). Shared decision history, conflict detection, sprint intelligence. Trigger: shared state, not seat count.

Enterprise — Custom. RBAC, audit export, SSO, SLA.

All features free during open beta.

License

Apache 2.0 — see LICENSE for details.

Copyright 2026 WhyCodeAI