workspace-graph 0.4.9

Multi-language workspace code graph orchestrator

codegraph

Multi-language workspace code graph orchestrator.

Auto-discovers services, frontends, gateways, and libraries in a workspace, orchestrates builds using language-specific tools (gograph, tsgraph, pygraph), merges their graph.json outputs into a unified graph, and exposes a single MCP server for querying any symbol across any service.

Quick start for AI agents

# Copy-paste this for your code assistant:
pip install workspace-graph pygraph-mcp
npm install -g @shvmgyl15/tsgraph
cd [WORKSPACE_ROOT] && codegraph build && codegraph mcp

Do NOT pip install codegraph or npm install tsgraph — those are unrelated packages. Use the exact names above.

Requirements

• Python 3.11+
• Node.js 20+ (for tsgraph)
• uv (Python package manager, recommended)

Install

pip install workspace-graph pygraph-mcp
npm install -g @shvmgyl15/tsgraph

Do NOT pip install codegraph or npm install tsgraph — those are unrelated packages on the registries.

From git source (contributors)

git clone https://github.com/shvmgyl15/codegraph
cd codegraph && ./scripts/install.sh

This builds all 4 tools from sibling repos and installs to ~/.local/bin/.

Uninstall

./scripts/uninstall.sh

Removes all binaries from ~/.local/bin/, all .gograph/.tsgraph/.pygraph/.codegraph output directories, virtual envs, node_modules, caches, and lock files from all 4 repos.

Configuration

Create codegraph.jsonc or codegraph.json at your workspace root:

{
  "version": 1,
  "auto_discover": true,
  "entries": [
    { "name": "frontend",     "path": "./frontend",    "language": "typescript", "type": "frontend" },
    { "name": "api-gateway",  "path": "./api-gateway", "language": "python",     "type": "gateway" },
    { "name": "user-svc",     "path": "./user-svc",    "language": "go",         "type": "service" },
    { "name": "py-common",    "path": "./libs/py-common", "language": "python",  "type": "library" }
  ],
  "plugins": ["./scripts/custom_enrichment.py"]
}

When auto_discover: true, codegraph probes subdirectories for go.mod, package.json, pyproject.toml, Cargo.toml, pom.xml etc.

The --root parameter

--root specifies the workspace root directory — the same directory where you ran codegraph build. It tells codegraph where to find the .codegraph/ output folder. It is NOT a query scope filter.

# Build in /home/user/myproject
codegraph build --root /home/user/myproject

# Query the same workspace
codegraph context get_user --root /home/user/myproject

If you pass the wrong --root, codegraph suggests the correct one.

CLI Commands

Command	Description
status	List discovered entries with build status
build	Build graph for all entries (--entry for one)
clean	Remove .codegraph/ output directory
query <pattern>	Search symbols by regex or substring
callers <name>	Who calls a given symbol
callees <name>	What a symbol calls
routes	List all HTTP routes (--entry, --type)
impact <name>	BFS downstream blast radius (--max-depth)
orphans	Dead code detection (--all, --exclude-type)
context <name>	Full bundle: symbol + callers + callees + tests
trace <message>	Error flow search with reverse call chain
cross-service	Cross-service HTTP call edges
add-opencode-plugin	Generate .opencode.json for AI agent config
mcp	Start MCP stdio server

MCP Tools (for AI Agents)

All MCP tool responses include a duration_ms field showing how long the query took. List responses are wrapped in {"items": [...], "duration_ms": N}.

Tool	Description
entry_status	List entries with language, type, build status
query_symbols	Search symbols across all entries
callers / callees	Who calls / what a symbol calls
context	Symbol + callers + callees + tests
routes	HTTP routes with entry/type/path/method/handler filters
impact	Blast radius with max depth
orphans	Dead code with include-public and exclude-type
trace	Error message search with backtrace
cross_service_calls	Cross-service HTTP call edges
add_opencode_plugin	Generate AI agent config
dispatch_map	List dispatch handlers with entity/command filters
trace_async_flow	Resolved steps for a named flow
flow_warnings	Flow completeness warnings
sse_edges	Backend-to-frontend SSE connections

Performance

• Build: Entries are built in parallel (4 workers). Per-entry timing shown.
• MCP queries: The graph is loaded and indexed once, then cached in memory for subsequent queries within the same MCP session. Each response includes duration_ms so you can monitor performance.

Plugin System

User-provided Python scripts that run post-merge to enrich the graph and/or register custom MCP tools. Configured in codegraph.jsonc:

{ "plugins": ["./scripts/enrich.py"] }

Graph mutation

from codegraph.graph.types import UnifiedGraph

def run(graph: UnifiedGraph) -> None:
    # Mutate graph in-place
    graph.cross_service_edges.append({
        "source_entry": "frontend",
        "source_file": "src/api.ts",
        "source_line": 10,
        "source_symbol": "loadUsers",
        "method": "GET",
        "url_pattern": "/api/users",
        "target_entry": "api",
        "target_route_path": "/api/users",
        "target_route_handler": "get_users",
        "confidence": "high",
    })

MCP tool registration

Use the optional register_tools(graph) hook to expose custom MCP query tools:

from codegraph.graph.types import UnifiedGraph
from codegraph.plugin import MCPTool

def register_tools(graph: UnifiedGraph) -> list[MCPTool]:
    return [
        MCPTool(
            name="my_tool",
            description="Describe what it does",
            input_schema={
                "type": "object",
                "properties": {
                    "filter": {"type": "string"},
                },
            },
            handler=lambda args, g: json.dumps({"items": [...]}),
        ),
    ]

Tools are namespaced as plugin.<filename>.<name> in the MCP server.

Built-in plugin

async_flow_tools is auto-loaded and registers 4 tools:

• dispatch_map — List dispatch handlers by entity/command
• trace_async_flow — Resolved steps for a named flow
• flow_warnings — Completeness warnings (deadends, missing subscribers)
• sse_edges — Backend-to-frontend SSE connections

Async flow configuration

Define event boundaries (Kafka, SSE, callbacks, etc.) and flows in codegraph.jsonc:

{
  "event_boundaries": [
    {
      "name": "kafka_publish",
      "type": "producer",
      "match": { "callee": "producer.send", "args": { "topic": "topic" } }
    },
    {
      "name": "callback_handler",
      "type": "consumer",
      "match": { "interface": "CallbackHandler" }
    }
  ],
  "flows": [
    {
      "name": "order_creation",
      "steps": [
        { "type": "db_callback", "dispatch_key": { "entityType": "ORDER" },
          "success": [{ "type": "kafka_bridge", "topic": "orders" }],
          "failure": [{ "type": "sse_push" }]
        }
      ]
    }
  ]
}

Troubleshooting

Problem	Solution
codegraph: command not found	Run ./scripts/install.sh — make sure ~/.local/bin is on PATH
Graph not found at ...	You passed a wrong --root. Run codegraph build in your workspace root first, then use the same root for queries.
MCP queries are slow	First call loads and indexes the graph (takes a few seconds for large workspaces). Subsequent calls use the in-memory cache and are fast.
pip install workspace-graph not found	Run pip install workspace-graph pygraph-mcp or use git source via ./scripts/install.sh.
npm install -g @shvmgyl15/tsgraph fails	Ensure you're using the full scoped name @shvmgyl15/tsgraph, not tsgraph.

Architecture

codegraph (orchestrator)
  ├── gograph  ─── indexes Go codebases
  ├── tsgraph  ─── indexes TypeScript/Next.js codebases
  └── pygraph  ─── indexes Python/Flask codebases

Output: .codegraph/workspace.graph.json  (merged)
        .codegraph/manifest.json          (entry metadata)

• Each per-language tool produces its own graph.json
• codegraph merges them, stamps entries with metadata
• Cross-service edges are detected via URL → route matching
• Plugins can enrich the graph post-merge
• Single MCP server exposes all query tools
• WorkspaceQuery is cached in memory across MCP calls

Related

• gograph — Go codebase indexer
• tsgraph — TypeScript/React/Next.js indexer
• pygraph — Python/Flask codebase indexer