Catryna Wikinelli
A local-first code wiki that your AI coding agent writes and your team reads — docs live as MDX files in a .docs/ folder, versioned with your code.
Part of Sothis, the local-first suite for running a fleet of AI coding agents on one repo (suite repo). Catryna is its documentation layer.
Every project accumulates knowledge that lives nowhere: why the auth flow works the way it does, which module owns what, the diagram someone drew once on a whiteboard. Wikis in Notion or Confluence drift out of date because updating them is a separate chore from writing code. Catryna fixes the incentive problem: your coding agent (Claude Code, or anything that speaks MCP) creates and updates the docs as part of the coding session, and because the docs are plain files in your repo, the agent also reads them back before touching code — so the knowledge actually gets used, and stale docs get caught in review like any other diff.
How it works
- Docs are
.mdx files with YAML frontmatter in .docs/ at your project root — no database, no cloud, git-versioned with your code.
- Agents read docs directly as files (
Read .docs/backend/storage.mdx) — no tool round-trip needed.
- Agents write docs via MCP tools (
create_doc, update_doc, search_docs, coverage reports, diagrams).
- Catryna tells you which docs the code has outgrown. Each doc anchors to the
source files it describes;
catryna drift diffs those files since the doc was
last verified and reports exactly which docs are now contradicted — then hands
an agent the doc plus the diffs so it can propose the fix.
- Humans browse the same docs in a local React viewer at
http://localhost:1307, with search, Mermaid/React Flow diagrams, whiteboards, and a doc-coverage report.
Quickstart
Prerequisites: Bun v1.2+ and Git. Bun 1.2 is the floor because the repo's lockfile is the text bun.lock, which became Bun's default lockfile format in 1.2; package.json declares it in engines.
Claude Code plugin (recommended)
Inside Claude Code:
/plugin marketplace add Davidb3l/Catryna-Wikinelli
/plugin install catryna@catryna-wikinelli
Or, if you run the whole Sothis suite, install it from the suite marketplace instead (the catryna plugin is the same):
/plugin marketplace add Davidb3l/Sothis
/plugin install catryna@sothis
This registers the MCP server (it installs its own dependencies on first run and stores docs in the .docs/ folder of whichever project you're working in), an Agent Skill that teaches Claude to search .docs/ before coding and update docs after changing code, and a /catryna:viewer command that starts the human viewer.
Restart Claude Code, then run /mcp — you should see catryna connected.
Manual install (other MCP clients / development)
git clone https://github.com/Davidb3l/Catryna-Wikinelli.git
cd Catryna-Wikinelli
bun install
Register the server with your MCP client. For Claude Code, add .mcp.json to your project root (or the same block to ~/.claude.json for all projects):
{
"mcpServers": {
"catryna": {
"command": "bun",
"args": ["run", "/path/to/Catryna-Wikinelli/src/index.ts"]
}
}
}
The server stores docs in .docs/ under the directory it's launched from (your project), creating it on first write.
Human viewer
cd Catryna-Wikinelli/frontend
bun install
bun run dev # http://localhost:1307
The viewer scans for sibling projects with .docs/ folders (set PROJECTS_ROOT to point it elsewhere) and lets you switch between them.
What a session looks like
> search_docs query="storage"
{ results: [{ file: ".docs/backend/storage.mdx", title: "Storage Layer",
snippet: "...file-based storage resolves .docs/ from cwd..." }], count: 1 }
> Read .docs/backend/storage.mdx # plain file read, no MCP call
... make code changes ...
> update_doc path="backend/storage" content=[...]
{ success: true, file: ".docs/backend/storage.mdx" }
> get_doc_coverage
{ documentedModules: 12, totalModules: 18, coveragePercent: 67,
undocumentedFiles: ["src/tools/diagrams.ts", ...] }
Each doc is an MDX file your whole team can read, diff, and edit by hand:
---
title: "Storage Layer"
path: "backend/storage"
tags: ["backend"]
relatedFiles: ["src/storage.ts"]
---
# Storage Layer
Docs are written as blocks (text, code, mermaid, react-flow, whiteboard, ...)
Keeping docs true
Generating docs is solved; keeping them correct isn't. A doc that contradicts
the code is worse than no doc, because an agent will believe it.
Every doc records the commit it was last verified against. catryna drift
compares each doc's anchored source files against that baseline:
catryna drift # clean / drifted / broken / unverified — exit 3 if anything is wrong
catryna repair <path> # that doc's content + the git diff of each changed anchor
catryna verify <path> # re-baseline once the doc is accurate again
- broken — an anchored file was deleted or renamed away (highest severity).
- drifted — anchored code changed since the doc was verified.
- Anchors can be whole files, or precise:
{"file":"src/auth.ts","symbol":"login"}
so only changes to that symbol count.
- Exits 3 on drift, so it drops straight into CI. A Stop hook also reminds
you at the end of any session that left docs drifted.
- Adopting an existing corpus that was never verified? Give it a starting point:
catryna drift --since 2026-02-18. See
.docs/guides/drift-adoption-playbook.mdx.
If Hayvenhurst is running, drift
uses its code graph for symbol-level precision; otherwise it falls back to plain
git-diff. Zero dependencies either way.
MCP tools
| Tool | Description |
|---|
create_doc / update_doc / delete_doc | Write docs as .docs/{path}.mdx |
get_doc / list_docs | Fetch one doc as blocks / browse and filter all docs |
search_docs | Full-text search, returns paths + snippets |
check_drift / verify_doc / propose_doc_repair | Find drifted docs, re-baseline them, get repair context |
create_mermaid_diagram / create_diagram | Mermaid or React Flow architecture diagrams |
create_whiteboard | Freeform whiteboard canvas |
get_doc_coverage / get_undocumented_modules | Which source files have docs, which don't |
The catryna CLI exposes the same drift workflow plus catryna doctor (health
and suite discovery) and catryna consume — all with --json for scripting.
Docs
This repo documents itself with Catryna — browse .docs/ for real examples:
Platform support
CI runs the full gate (typecheck, tests, doc lint, drift) on Ubuntu, macOS and
Windows. The plugin needs only Bun and Git on every OS: the MCP server and both
hooks (SessionStart and Stop) run through bun directly, so no POSIX shell is
required, including on Windows outside Git Bash. .docs/ travels between
machines, so anchor paths always use forward slashes (git's format on every OS)
and CRLF checkouts are handled on read. The tests that need file symlinks are
skipped on a Windows host without Developer Mode (they still run in CI).
Status & license
Early-stage (v1.3.2) and moving fast; issues and PRs welcome. MIT licensed.
