codelore

Turn any code repository into a searchable Obsidian vault — then let Claude Code navigate it as a set of MCP tools.

codelore runs a two-phase pipeline:

1. Summarise — calls claude --print once per file and directory to produce structured markdown documentation

2. Index — chunks every file at the function/class level, generates developer questions for each chunk, and stores them in a ChromaDB vector index

The result is an Obsidian vault of linked markdown notes and a semantic search index that Claude Code can query as native tools.

How it works

your-repo/
    src/auth/middleware.py   →  AI summary + import graph
    src/db/pool.py           →  AI summary + import graph
    ...
           ↓  codelore ingest
your-repo_vault/
    INDEX.md                 overview + wikilinks to all modules
    src/auth/middleware.md   structured summary of every function
    src/db/pool.md           ...
your-repo_chroma/            ChromaDB: chunks indexed by developer questions

Claude Code reads INDEX.md → directory notes → file notes via the explore_repo tool, and answers "how does X work?" questions via search_code which hits the semantic index.

Related MCP server: obsidian-mcp

Prerequisites

• Python 3.11+

• uv — used to run the MCP server and manage dependencies

• Claude Code CLI — claude.ai/download

  claude --version   # must be on PATH

Install

git clone https://github.com/yourname/codelore
cd codelore
uv sync                        # creates .venv/ and installs all dependencies
source .venv/bin/activate      # Windows: .venv\Scripts\activate

Quick start

# 1. Ingest a local repo (or pass a GitHub URL)
codelore ingest /path/to/your-repo

# Preview cost before running on a large repo
codelore ingest /path/to/your-repo --dry-run

# Re-use cached summaries from a previous run (skips claude calls)
codelore ingest /path/to/your-repo   # prompted automatically if cache exists

# 2. Query from the terminal
codelore query "how does authentication work?" \
  --chroma /path/to/your-repo_chroma

# 3. Print MCP setup instructions
codelore init --vault /path/to/your-repo_vault \
              --chroma /path/to/your-repo_chroma \
              --repo /path/to/your-repo

CLI reference

codelore ingest <repo>

codelore query <question>

codelore init

Prints step-by-step setup instructions and a ready-to-paste MCP config block.

MCP server setup (Claude Code)

After ingesting, add codelore as an MCP server so Claude Code can call it as tools.

If you cloned the repo, it already includes a .mcp.json at the project root that launches the server via uv. Just make sure uv is installed and run uv sync — the MCP server will start automatically when you open the project in Claude Code.

To set it up manually for a different project, create a .mcp.json in the project root:

{
  "mcpServers": {
    "codelore": {
      "command": "uv",
      "args": ["run", "codelore-mcp"],
      "env": {
        "VIRTUAL_ENV": ""
      }
    }
  }
}

The "VIRTUAL_ENV": "" clears any activated venv so uv uses its own .venv/ without conflicts.

All tools accept vault_root, chroma_path, and repo_root as per-call parameters. To avoid passing them every time, add them to the env block:

{
  "env": {
    "VIRTUAL_ENV": "",
    "CODELORE_VAULT_ROOT": "/path/to/your-repo_vault",
    "CODELORE_CHROMA_PATH": "/path/to/your-repo_chroma",
    "CODELORE_REPO_ROOT": "/path/to/your-repo"
  }
}

codelore init will generate a ready-to-paste config with your actual paths filled in.

Available MCP tools

Obsidian MCP integration (recommended)

codelore generates an Obsidian-compatible vault, and several codelore tools are designed to hand off to the Obsidian Local REST API MCP for direct vault operations. Setting this up unlocks:

• vault_read — read any vault note directly (replaces the deprecated read_vault_node)

• vault_append — safely append notes to existing vault files without overwriting

• search_simple — plain-text search across your vault as a fallback when semantic search returns no results

Setup

1. Install the Obsidian Local REST API plugin in Obsidian.

2. Enable the plugin and copy the API key from its settings.

3. Add the following to your .mcp.json alongside the codelore entry:

{
  "mcpServers": {
    "obsidian": {
      "type": "http",
      "url": "http://127.0.0.1:27123/mcp/",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

Once both MCP servers are running, Claude will automatically use them together:

• search_code (codelore) → falls back to search_simple (Obsidian MCP) → falls back to raw file grep

• vault_append (codelore) resolves the right vault note, then calls vault_append (Obsidian MCP) to append safely

• explore_repo and find_todos direct Claude to use vault_read (Obsidian MCP) for follow-up note reading

Note: The Obsidian MCP vault_write tool overwrites files entirely and is not used by codelore tools. It will only be called if you explicitly ask for it by name.

Supported languages

Non-code files (.md, .json, .yaml, .toml, .sql, .proto, .graphql) are also indexed for context.

Incremental re-indexing

After code changes, sync only the modified files instead of re-running the full pipeline:

# via MCP tool (in Claude Code):
"sync the vault for /path/to/repo"   →  calls sync_vault(dry_run=True) first

# or directly:
sync_vault(repo_path="/path/to/repo", explanations_json_path="..._explanations.json", dry_run=True)
sync_vault(repo_path="/path/to/repo", explanations_json_path="..._explanations.json", dry_run=False)

Requires the repo to be a git repository (uses git diff against the SHA saved during ingestion).

Architecture

codelore/
  main.py          CLI entry point (ingest / query / init subcommands)
  ingest.py        build file/directory graph, write vault markdown
  explain.py       collect files, call Claude CLI for summaries
  llm.py           Claude CLI wrapper, prompt templates
  nodes.py         FileNode / DirectoryNode / IndexNode → markdown
  generate_questions.py  chunk-level question generation + ChromaDB indexing
  parsers/         language-specific import graph + chunk extraction
    _treesitter.py shared tree-sitter helper
    python.py      stdlib ast
    javascript.py  tree-sitter-javascript / tree-sitter-typescript
    go.py          tree-sitter-go
    jvm.py         tree-sitter-java / tree-sitter-kotlin / tree-sitter-scala
    csharp.py      tree-sitter-c-sharp
    haskell.py     tree-sitter-haskell
    elixir.py      tree-sitter-elixir
    lua.py         tree-sitter-lua
    shell.py       tree-sitter-bash
    ...
  query/
    retrieval.py   search_chunks, bfs_vault, grep_todos, git_file_log
mcp_server.py      FastMCP server exposing 9 tools

License

MIT