waymark

waymark

MCP server exposing a codebase's OKFknowledge bundle (okf/) to Claude Code — three schema-enforced querytools instead of raw Read/Grep over hand-written docs.

Tools

• list_concepts(type?, tags?) — frontmatter-only summaries. tags matchesany-of the given tags.
• read_concept(path) — full frontmatter + body for one concept, by thepath a list_concepts call returned.
• find_concept_by_resource(file_path) — reverse lookup: which concept(s)describe a given source file.

The server is stateless — it re-reads okf/ from process.cwd() on everycall, so there's nothing to invalidate when concept files change.

Setup (per project)

npx -y @aleburrascano/waymark init

This registers everything a repo needs in one step:

• Adds a waymark entry to .mcp.json (creating it if missing).
• Installs a pre-commit hook at .git/hooks/pre-commit that blocks commitswhen a resource-mapped file changes without its okf/ concept beingupdated. Safe to re-run — it upgrades its own hook on later waymarkversions but never overwrites a hook it didn't install.
• Installs the okf-staleness-fix skill to .claude/skills/ — thewriter/judge playbook Claude Code uses to resolve a blocked commit.
• Adds (or refreshes) an ## OKF context section in the repo's CLAUDE.md.

Run it again any time to pick up updates from a newer waymark version.

Local development

npm install
npm test
npm run build && npm link   # then `waymark` runs the built CLI

npm test runs vitest against TypeScript source directly — no build steprequired for the test suite.