⚠️ This repository has moved

CodeGB is no longer maintained.

The project has been renamed and continued as Tally.

➡️ New repository: https://github.com/Killian-Filippov/Tally

This repository is archived and kept only for historical reference.

CodeGB is a code knowledge graph tool for local developer environments. It provides an MCP Server that runs on your machine and can be called by MCP Clients (such as Claude/Cursor).

Feature Overview

• Java code parsing and graph construction (classes, methods, fields, calls, inheritance, imports)
• Tree-sitter-first Java extraction, with regex kept only as a compatibility fallback
• MCP tools:
  • query
  • context
  • impact
  • cypher
  • list_repos
• Local-first storage and querying
• Switchable graph storage backend (WASM / Native)

Requirements

• Node.js 18+
• pnpm

Install Dependencies

pnpm install

Build

pnpm build

Local Usage (CLI)

# 1) Initialize the repository index directory
pnpm exec tsx packages/cli/src/index.ts init /path/to/your/repo --storage .javakg

# 2) Build index
pnpm exec tsx packages/cli/src/index.ts index /path/to/your/repo --storage .javakg

# 2.1) Incremental indexing (only process changed Java files in git diff)
pnpm exec tsx packages/cli/src/index.ts index /path/to/your/repo --storage .javakg --changed-files

# 3) Query
pnpm exec tsx packages/cli/src/index.ts query "payment" --storage .javakg --limit 10

Start MCP Server (stdio)

JAVA_KG_DB_PATH=.javakg pnpm exec tsx packages/mcp-server/src/cli.ts

Notes:

• This process communicates with the MCP Client via stdio.
• In your MCP Client, configure this command as the MCP Server startup command.

MCP Client Config Template (Minimal Working Setup)

Use the following template consistently:

• command: pnpm
• args: ["exec", "tsx", "packages/mcp-server/src/cli.ts"]
• env.JAVA_KG_DB_PATH: your index directory (must match --storage)
• env.CODEGB_AUTO_INDEX_INTERVAL_MS: polling interval (ms) for MCP background incremental indexing (default 3000, set to 0 to disable)
• env.CODEGB_MCP_CACHE_TTL_MS: cache TTL (ms) for MCP query/context (default 60000, set to 0 to disable)
• env.CODEGB_MCP_CACHE_L1_MAX_ENTRIES: in-process L1 cache size (default 256, set to 0 to disable)
• env.CODEGB_MCP_CACHE_L2_MAX_ENTRIES: persistent L2 cache size (default 4096, set to 0 to disable)

Replace "/ABS/PATH/TO/CodeGB" and "/ABS/PATH/TO/.javakg" with absolute paths.

Claude Desktop

The config file (macOS) is usually at ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "codegb": {
      "command": "pnpm",
      "args": ["exec", "tsx", "packages/mcp-server/src/cli.ts"],
      "cwd": "/ABS/PATH/TO/CodeGB",
      "env": {
        "JAVA_KG_DB_PATH": "/ABS/PATH/TO/.javakg"
      }
    }
  }
}

Cursor

Workspace file .cursor/mcp.json:

{
  "mcpServers": {
    "codegb": {
      "command": "pnpm",
      "args": ["exec", "tsx", "packages/mcp-server/src/cli.ts"],
      "cwd": "/ABS/PATH/TO/CodeGB",
      "env": {
        "JAVA_KG_DB_PATH": "/ABS/PATH/TO/.javakg"
      }
    }
  }
}

VS Code

Workspace file .vscode/mcp.json:

{
  "servers": {
    "codegb": {
      "type": "stdio",
      "command": "pnpm",
      "args": ["exec", "tsx", "packages/mcp-server/src/cli.ts"],
      "cwd": "/ABS/PATH/TO/CodeGB",
      "env": {
        "JAVA_KG_DB_PATH": "/ABS/PATH/TO/.javakg"
      }
    }
  }
}

First-Time Indexing (Required Before MCP)

MCP only provides queries. For first-time usage, run init + index first:

pnpm exec tsx packages/cli/src/index.ts init /ABS/PATH/TO/REPO --storage /ABS/PATH/TO/.javakg
pnpm exec tsx packages/cli/src/index.ts index /ABS/PATH/TO/REPO --storage /ABS/PATH/TO/.javakg

Java Parser Runtime

• The indexing pipeline uses tree-sitter as the primary Java parser and extraction path.
• JAVA_QUERIES is the authoritative query template used by the tree-sitter extractor for symbol and relation capture.
• The legacy regex extractor is still present only as a compatibility fallback when the tree-sitter runtime is unavailable or a single-file tree-sitter parse fails during indexing.
• Operationally, you should treat CodeGB as a tree-sitter-based Java indexer, not as a dual-parser system.

FAQ

• Q: MCP connects successfully, but returns empty results? A: Usually initial indexing was not completed, or JAVA_KG_DB_PATH does not match index --storage.
• Q: Startup fails with JSON error codes? A: E_NODE_VERSION (Node < 18), E_STORAGE_PERM (directory not writable), E_WORKER_UNAVAILABLE (worker unavailable), E_BACKEND_INIT (backend initialization failed).
• Q: pnpm not found? A: Ensure pnpm is available in the client runtime PATH, or use an absolute path to pnpm.
• Q: list_repos shows old repositories? A: Re-run init + index for the new repository and update JAVA_KG_DB_PATH.

Fallback Behavior

• Backend fallback: when CODEGB_DB_BACKEND=auto, wasm is preferred, and if it fails it automatically falls back to native, with a one-time diagnostic log.
• Cypher fallback: the cypher tool prefers backend execution; when backend is unavailable or returns incompatible results, it automatically falls back to the in-memory graph compatible execution path.
• Data fallback: if the index directory is empty or graph loading fails, the service starts with an empty graph and tools return empty results instead of crashing the process.

Graph Database Backend Selection

The current implementation supports two paths:

• kuzu-wasm: better cross-platform compatibility and installation experience, suitable for default distribution.
• kuzu (native): may be faster on some machines, but has higher installation/compatibility cost.

Unified switch:

• CODEGB_DB_BACKEND=wasm|native|auto
• Default: wasm (compatibility first)
• auto: try wasm first, automatically fall back to native on failure, and print a one-time diagnostic log.

Note: backend switching has been implemented in the core layer. The concrete runtime strategy can be managed uniformly through startup configuration.

Tests

# Core tests
pnpm exec tsx --test packages/core/test/*.test.ts

# E2E tests
pnpm test:e2e

Release Gate

Before publishing a developer-trial version, run:

pnpm run release:gate

Gate conditions:

• Core e2e passes (pnpm test:e2e:phase1)
• benchmark.md exists
• docs/release-notes.md contains the current version heading (## v<version>)

Project Structure

• packages/core: parsing, graph models, storage adapters, search, MCP tool logic
• packages/mcp-server: MCP Server startup and protocol integration
• packages/cli: local init/index/query commands
• tests/e2e: end-to-end tests