CSG - Code Structure with Graph

CSG is a local code intelligence tool for building a graph index of a source repository and exposing that index to AI coding agents through MCP.

It parses source code with deterministic AST tooling, stores symbols and relationships in an embedded Kuzu graph database, and provides MCP tools for code exploration, impact analysis, change review, and graph-aware navigation.

Install

uv tool install --python 3.12 --index-url https://pypi.org/simple --refresh code-knowledge-graph-tool

Upgrade later with:

uv tool upgrade code-knowledge-graph-tool

One-Time OpenAI Setup

Semantic embeddings use OpenAI embeddings. Configure your key once:

csg config set openai-api-key sk-your-openai-api-key

This key is stored in CSG's local user config and is reused by:

• csg analyze --embeddings
• csg watch
• csg mcp launched by Claude Code, Codex, or VS Code MCP clients

You can also use OPENAI_API_KEY or CSG_OPENAI_API_KEY as environment overrides. If no key is configured, CSG still builds the graph and skips embeddings with a clear reminder.

Basic Workflow

Run these commands from the repository you want to index:

cd /path/to/your/repo
csg analyze . --embeddings
csg setup .

csg analyze builds the local graph index. csg setup installs repo-local agent guidance files and registers the CSG MCP server for supported agent CLIs.

To keep indexed repositories fresh while you work:

csg watch

To open the local web UI:

cd /path/to/your/repo
csg web --open

The browser UI runs at http://127.0.0.1:8080 by default and can upload, analyze, and visualize repositories locally. If the directory where you launch csg web has already been analyzed, the UI loads that graph automatically.

MCP Usage

After setup, AI agents can use CSG MCP tools automatically:

• csg_list_repos: discover indexed repositories
• csg_explore: search and explore graph layers
• csg_context: inspect a symbol with callers, callees, and source context
• csg_impact: check blast radius before edits
• csg_detect_changes: map git changes to affected symbols and flows
• csg_rename: preview graph-aware symbol renames
• csg_analyze: index a repository from the MCP client

Manual MCP registration is also possible:

claude mcp add --transport stdio --scope user csg -- csg mcp
codex mcp add csg -- csg mcp

MCP clients that use JSON configuration can launch:

{
  "mcpServers": {
    "csg": {
      "command": "csg",
      "args": ["mcp"]
    }
  }
}

Common Commands

csg analyze .                    # Build graph index
csg analyze . --force            # Rebuild index
csg analyze . --embeddings       # Build graph plus OpenAI embeddings
csg setup .                      # Install agent files and register MCP
csg setup-agents .               # Install repo-local agent files only
csg status                       # Show index status for current repo
csg list                         # List indexed repositories
csg web --open                   # Start the local browser UI
csg watch                        # Watch indexed repos for changes
csg logs                         # Show MCP logs
csg clean                        # Delete current repo index

Data Storage

For normal local repositories, CSG stores graph data inside the target checkout:

<repo>/.csg/
  meta.json
  lbug/
  cache/

A small global registry is also maintained so MCP clients can discover indexed repositories.

Notes

• Indexing does not require an LLM.
• Embeddings require an OpenAI key.
• No local PyTorch, CUDA, or Hugging Face embedding model is installed by the package.
• If embeddings are skipped, graph navigation, context, impact analysis, and BM25 search still work.