@leanlabsinnov/codegraph

Live, queryable knowledge graph for your codebase. Indexes JS/TS/Python into an embedded graph database with vector embeddings, then exposes a local MCP server that Claude Code, Cursor, and Windsurf can call to answer structural questions about your code.

Zero infrastructure. The graph lives at ~/.codegraph/. No Docker, no external services.

Install

npm i -g @leanlabsinnov/codegraph

Requires Node.js 20+.

Quickstart

# 1. Pick an LLM provider
codegraph config llm set byo-openai        # also: byo-anthropic, byo-google, local-ollama
export OPENAI_API_KEY=sk-...

# 2. Verify the wire-up (5-token gen + 1 embedding round-trip)
codegraph config llm test

# 3. Index a repo
codegraph index ~/my-project

# 4. Boot the MCP server
codegraph serve
# → http://127.0.0.1:3748/mcp

Point Claude Code / Cursor / Windsurf at http://127.0.0.1:3748/mcp with the bearer token from ~/.codegraph/config.json.

See client setup docs for copy-paste config snippets.

Commands

| Command | Description | |---|---| | codegraph index <path> | Walk, parse, embed every symbol, write to graph | | codegraph index <path> --no-embed | Parse only — faster, semantic search disabled | | codegraph status <path> | Node/edge counts and embedding coverage | | codegraph wipe [path] | Delete a repo's graph rows (--yes skips prompt) | | codegraph serve [--port N] [--host H] | Boot the MCP server (default :3748) | | codegraph doctor | Health check: Node, config, API keys, Kuzu, LLM | | codegraph update | Check npm for a newer release and upgrade the global CLI | | codegraph update --check | Show installed vs latest without installing | | codegraph config show | Print resolved ~/.codegraph/config.json | | codegraph config llm set [preset] | Switch LLM preset (interactive picker if no arg) | | codegraph config llm test | Round-trip the configured provider |

LLM Providers

| Preset | Generation | Embeddings | Required env var | |---|---|---|---| | byo-openai | gpt-4o-mini | text-embedding-3-small | OPENAI_API_KEY | | byo-anthropic | claude-3-5-haiku-latest | text-embedding-3-small | ANTHROPIC_API_KEY + OPENAI_API_KEY | | byo-google | gemini-1.5-flash-latest | text-embedding-004 | GOOGLE_GENERATIVE_AI_API_KEY | | local-ollama | qwen2.5-coder:14b | nomic-embed-text | Ollama running locally |

What you can ask

Once connected, ask your AI assistant:

• "What calls useAuth?"
• "Show the component tree rooted at App."
• "What's the blast radius of renaming formatPrice?"
• "Find symbols semantically similar to 'JWT auth helper'."
• "What are the transitive imports of src/lib/db.ts?"

Configuration

Config is stored at ~/.codegraph/config.json (auto-generated on first serve):

{
  "llm": {
    "mode": "byo",
    "generation": { "provider": "openai", "model": "gpt-4o-mini" },
    "embeddings": { "provider": "openai", "model": "text-embedding-3-small", "dimension": 1536 }
  },
  "server": {
    "port": 3748,
    "bearerToken": "<32-hex-chars>"
  }
}

You can also override via environment variables — see .env.example in the repo root.

Troubleshooting

Run codegraph doctor first. For client-specific config issues, see the full docs.

License

MIT