CodeAtlas

A Claude Code plugin that gives every project a persistent, searchable wiki knowledge base. Semantic search via Ollama, keyword search via TF-IDF, and full lifecycle management — all accessible as MCP tools and slash commands.

---

What it does

Ingest

• wiki_ingest — process raw sources into wiki pages via Claude
  • file / files[] — local files from RAW_ROOT
  • url / urls[] — fetch from web pages or GitHub file URLs directly (GitHub blob URLs auto-converted to raw)
  • Deduplication: embeds a sample of each source and surfaces similar existing pages before Claude writes anything
  • Sources truncated at 40k chars to prevent context overflow; truncation noted inline
• /wiki-ingest <file> — ingest shortcut

Search & retrieval

• wiki_search — hybrid semantic + keyword search; supports tags filter; degrades to keyword-only if Ollama is unavailable
• wiki_get — fetch a full wiki page by name
• wiki_list — enumerate all pages with title, tags, updated date; supports tag filtering
• wiki_context_for — given a source file path, extract filename + symbols and return the most relevant wiki pages automatically
• /wiki-search <query> — search shortcut

Write

• wiki_update — create or update a page and re-embed it
  • dry_run: true — preview changes without writing
  • git_commit: true — git add + commit after writing
  • Incremental re-embedding: unchanged chunks skip Ollama, only changed chunks re-embed
• wiki_delete — remove a page and its vectors
• wiki_rename — rename a page and rewrite all incoming [[links]] atomically

Maintenance

• wiki_lint — health check: broken links (with fuzzy suggestions), orphan pages, missing frontmatter, stale embeddings, missing concepts
  • fix: true — auto-fix missing updated dates in frontmatter
• wiki_reembed_all — batch re-embed stale pages (default) or all pages; returns {reembedded, skipped, errors, total}
• /wiki-lint — lint shortcut

Bootstrap

• /wiki-init — bootstrap the wiki in any project (creates wiki/, raw/, .mcp.json)

The wiki skill auto-triggers: Claude searches before starting a task, updates after implementing or deciding something, records gotchas and debugging findings as they surface, and ingests when you provide a spec or notes.

---

Requirements

• Claude Code
• Ollama running somewhere accessible (local or homelab)
• nomic-embed-text model pulled in Ollama: ollama pull nomic-embed-text
• Node.js 18+

---

Installation

# 1. Install the CLI globally (builds native modules correctly)
npm install -g @synnode/codeatlas

# 2. Add the CodeAtlas marketplace
/plugin marketplace add synnode/codeatlas

# 3. Install the wiki plugin
/plugin install codeatlas@synnode

Then in any project you want to use the wiki:

/wiki-init

This creates wiki/, raw/, .mcp.json, and updates CLAUDE.md. Edit .mcp.json to set your Ollama URL, then restart Claude Code.

---

Wiki page format

Every page is a markdown file with YAML frontmatter:

---
title: "AuthMiddleware"
tags: [architecture, auth]
related: ["User", "Session"]
updated: 2026-05-02
---

# AuthMiddleware

One-paragraph summary.

## Overview
...

## Key Decisions
...

## Related
- [[User]]
- [[Session]]

Required frontmatter fields: title, tags, updated. Use [[PageName]] for cross-references.

---

Project layout

plugins/codeatlas/
├── src/
│   ├── index.ts              # MCP server entrypoint
│   ├── config.ts             # Env var loading
│   ├── db.ts                 # sqlite-vec singleton
│   ├── lib/
│   │   ├── embedder.ts       # Ollama client
│   │   ├── vector-store.ts   # sqlite-vec read/write/search
│   │   ├── tfidf.ts          # TF-IDF keyword index
│   │   ├── rrf.ts            # Reciprocal Rank Fusion
│   │   ├── chunker.ts        # Markdown-aware chunker
│   │   └── wiki-fs.ts        # Filesystem helpers
│   ├── tools/                # One file per MCP tool
│   └── prompts/              # Ingest prompt
├── skills/wiki/SKILL.md      # Claude Code skill
└── commands/                 # Slash commands

---

Configuration

Set per-project in .mcp.json (generated by /wiki-init):

Variable	Description	Default
WIKI_ROOT	Path to project's wiki/ folder	—
RAW_ROOT	Path to project's raw/ folder	—
OLLAMA_URL	Ollama base URL	—
OLLAMA_MODEL	Embedding model	nomic-embed-text
DB_PATH	sqlite-vec database path	{WIKI_ROOT}/.embeddings.db

---

License

MIT