GraphoCode

Turn any codebase into a queryable knowledge graph — zero LLM, pure AST.

GraphoCode scans your source code, builds a full call graph and search index, and exposes it through a CLI and MCP server. Ask questions like "How does createUser work?", "What causes error 7002?", or "What breaks if I change the User model?" — and get instant structured answers without any LLM calls.

What's New in v6.0.0

🖥️ Server Mode — shared team graph via HTTP API

GraphoCode now runs as a persistent HTTP server so every developer on your team queries the same graph without regenerating locally.

graphocode serve --port 4000 --workspace ~/coderepo

All 10 query operations are available as REST endpoints:

| Endpoint | Equivalent CLI command | |----------|----------------------| | GET /api/search?q=auth | graphocode search "auth" | | GET /api/flow/:fn | graphocode flow <fn> | | GET /api/trace/:fn | graphocode trace <fn> | | GET /api/error/:code | graphocode error <code> | | GET /api/impact?file=... | graphocode impact <file> | | GET /api/path?from=...&to=... | graphocode path <from> <to> | | GET /api/stats | graphocode stats | | GET /api/query?q=... | graphocode query "..." | | GET /api/projects | list all workspace apps | | POST /api/generate | trigger re-generation (CI/CD) |

Every endpoint accepts ?app=<name> to scope to a single service in a multi-project workspace.

CI/CD integration — trigger a graph rebuild on every push:

# In your CI pipeline (GitHub Actions, Jenkins, etc.)
curl -X POST "http://graphocode-server:4000/api/generate?app=my-service&branch=main&commit=abc123"
# Returns immediately (202 Accepted) — generation runs in the background

🔍 Git Metadata in the Knowledge Graph

Every function, class, and module in the graph is now enriched with git history. When you run graphocode generate, GraphoCode calls git log once per file and attaches:

| Field | What it tells you | |-------|------------------| | git_author | Who last modified this file | | git_contributors | Everyone who ever touched it | | git_churn | Total commit count (high churn = risk indicator) | | git_commit | Short SHA of the last change | | git_date | ISO date of the last change | | git_branch | Branch active at generate time |

Each OKF concept file gains a Git History table and frontmatter fields:

---
git_author: "[email protected]"
git_contributors: ["alice", "bob", "carol"]
git_churn: 17
git_branch: "main"
git_commit: "a1b2c3d4"
---
# Git History
| Field | Value |
|-------|-------|
| Author | alice ([email protected]) |
| Churn  | 17 commits ⚠️ high churn |
| Contributors | alice, bob, carol |

Functions with git_churn >= 10 are automatically flagged with ⚠️ high churn — warning that this file changes frequently and is high-risk to modify.

What this unlocks:

• "Who owns this function?" → git_author in the flow output
• "Is it safe to refactor this?" → churn score + complexity together
• "Who should review this PR?" → git_contributors list
• "What branch was this generated from?" → git_branch

⚡ --no-git Flag — faster generation for large repos or CI

Skip git metadata extraction when you need speed:

graphocode generate --no-git
graphocode generate-all /path/to/microservices --workspace ~/coderepo --no-git

Use --no-git when:

• Generating graphs in CI on a shallow clone (no git history)
• Working in repos with 100+ files where git log adds significant time
• Running a quick local scan without needing ownership data

Features

• 17 languages — Python, JavaScript, TypeScript, Java, C#/.NET, Go, Rust, Ruby, PHP, Kotlin, Swift, C, C++, Dart, Scala, Lua, Bash
• Zero LLM — no AI costs, works offline, instant results
• Multi-project workspace — auto-discover applications, generate and query across all
• 17 CLI commands — generate, generate-all, serve, search, flow, trace, error, query, impact, path, connects, stats, analyze, and more
• 15 MCP tools — plug into Cursor, Claude Code, or any MCP-compatible AI assistant
• Server Mode (new v6) — run as an HTTP API so your whole team queries one shared graph
• Git metadata (new v6) — author, contributors, churn risk, branch embedded in every concept
• --no-git flag (new v6) — skip git extraction for faster CI or large-repo generation
• Typed edges with confidence — calls, imports, contains, inherits edges tagged EXTRACTED/INFERRED/AMBIGUOUS
• Graph-aware search — find what connects any two concepts by keyword
• Multi-modal ingestion — docs, SQL schemas, and config files included in the graph
• Interactive visualizations — graph.html (dependency graph) and tree.html (file tree with complexity)
• Auto-init — .cursorrules and CLAUDE.md are auto-copied on first generate, so AI assistants use GraphoCode rules immediately

Why GraphoCode?

For developers — understand unfamiliar codebases instantly. Trace how any function works, find what breaks before you refactor, and search across all your microservices in one command.

For teams — onboard new developers faster. Instead of reading thousands of files, ask natural language questions and get structured answers showing exact call chains, error scenarios, and dependencies.

For AI-assisted development — supercharge Cursor and Claude Code. GraphoCode gives your AI assistant deep knowledge of your codebase structure, so it answers code questions using actual call graphs instead of guessing from file contents.

Zero cost, zero setup — no API keys, no cloud services, no LLM tokens. Runs entirely on your machine, works offline, and produces results in seconds.

Install

npm install -g graphocode

Requires Node.js 18+.

Permission error? If you see EACCES: permission denied, your npm global prefix requires root access. Fix it once with these commands, then re-run the install:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc   # or ~/.bashrc
source ~/.zshrc
npm install -g graphocode

This is a one-time setup. All future npm install -g commands will also work without sudo.

Quick Start

Single project

cd /path/to/your/project
graphocode generate

This creates graphocode-out/ with documentation files, graph.html (interactive dependency graph), and tree.html (file tree with complexity stats).

Multi-project workspace

# Auto-discover and generate for ALL applications in a folder
graphocode generate-all /path/to/microservices --workspace ~/coderepo

# Preview what it finds (no generation)
graphocode generate-all /path/to/microservices --dry-run

This scans each subfolder for project markers (package.json, pom.xml, *.csproj, go.mod, Cargo.toml, setup.py, etc.), detects applications automatically, and generates a knowledge graph for each one.

Output:

~/coderepo/
├── .cursorrules              ← auto-copied, AI rules
├── CLAUDE.md                 ← auto-copied, AI rules
├── service-a/graphocode-out/
├── service-b/graphocode-out/
└── service-c/graphocode-out/

CLI Commands

# Generate
graphocode generate                          # single project
graphocode generate --no-git                 # skip git metadata (faster)
graphocode generate-all <folder>             # auto-discover + generate all
graphocode generate-all <folder> --no-git    # bulk generate without git metadata
graphocode init                              # copy AI rules to current folder
graphocode update                            # re-generate for changed files (via git diff)

# Server mode (new v6)
graphocode serve                             # start HTTP API on port 4000
graphocode serve --port 8080                 # custom port
graphocode serve --workspace ~/coderepo      # serve a multi-project workspace
graphocode serve --host 0.0.0.0 --port 4000 # bind to all interfaces (team access)

# Search
graphocode search "authentication" --expand  # full-text search
graphocode query "who calls login"           # natural language graph query

# Trace & Flow
graphocode flow createStepRule               # forward execution tree
graphocode trace handleError                 # backward caller chain
graphocode error 7002                        # find function producing error code

# Analysis
graphocode impact src/models/User.js         # blast radius
graphocode path <source> <target>            # shortest path between concepts
graphocode connects auth database            # find what connects two concepts by keyword
graphocode stats                             # codebase overview (includes git churn in v6)
graphocode lint                              # validate output conformance
graphocode analyze "signup"                  # consolidated search + flow + trace report

All query commands accept --workspace <path> and --app <name> for multi-project support:

graphocode search "authentication" --workspace ~/coderepo
graphocode flow createUser --workspace ~/coderepo --app my-service
graphocode error 404 --workspace ~/coderepo

MCP Server — AI Assistant Integration

GraphoCode includes an MCP server with 14 tools that plug into any MCP-compatible AI assistant.

Cursor IDE

Add to your mcp.json (Settings → search "MCP" → Edit in mcp.json):

{
  "mcpServers": {
    "graphocode": {
      "command": "graphocode-mcp",
      "args": [],
      "env": {}
    }
  }
}

Restart Cursor. Now just ask naturally:

• "How does createStepRule work?" → calls graphocode_flow
• "What scenario causes error 7002?" → calls graphocode_error
• "What breaks if I change User model?" → calls graphocode_impact
• "Show me all authentication code" → calls graphocode_search_code

Claude Code

claude mcp add graphocode -- graphocode-mcp

MCP Tools (14)

| Tool | Purpose | |------|---------| | graphocode_search_code | Full-text search with query expansion | | graphocode_search | Search by name/type | | graphocode_flow | Forward execution flow through callees | | graphocode_trace | Backward call chain to find error origins | | graphocode_error | Find functions producing a specific error code | | graphocode_query | Natural language: "who calls X", "impact of X" | | graphocode_impact | Blast radius analysis | | graphocode_path | Shortest path between concepts | | graphocode_connects | Graph-aware search: find what connects two concepts by keyword | | graphocode_stats | Codebase statistics | | graphocode_god_nodes | High-risk highly-connected functions | | graphocode_get_concept | Read full documentation for a concept | | graphocode_list_projects | List all projects in a workspace | | graphocode_analyze | Consolidated search + flow + trace report | | graphocode_discover_apps | Scan folder to detect applications |

How It Works

1. Scan — finds all source files in your project
2. Parse — parses each file into an abstract syntax tree
3. Extract — pulls out functions, classes, methods, calls, error codes, parameters, return types, and inheritance
4. Build — constructs the full call graph and detects communities
5. Index — builds a search index over all concepts
6. Output — generates documentation files, interactive graph visualization, and stats

Supported Languages

| Category | Languages | |----------|-----------| | Web / Scripting | JavaScript, TypeScript, PHP, Ruby, Dart | | Enterprise / Backend | Java, C# (.NET), Kotlin, Scala, Swift | | Systems | Go, Rust, C, C++ | | Scripting | Python, Lua, Bash |

Application Detection

generate-all recognizes projects by these markers:

| Marker | Language/Framework | |--------|--------------------| | package.json | Node.js / JavaScript / TypeScript | | pom.xml, build.gradle | Java (Maven / Gradle) | | *.csproj, *.sln | C# / .NET | | go.mod | Go | | Cargo.toml | Rust | | setup.py, pyproject.toml | Python | | composer.json | PHP | | Gemfile | Ruby | | pubspec.yaml | Dart / Flutter | | Package.swift | Swift | | build.sbt | Scala | | CMakeLists.txt, Makefile | C / C++ |

Configuration

Create .graphocode.yml in your project root to customize (or run graphocode init):

output: ./graphocode-out
languages:
  - javascript
  - typescript
  - python
  - java
  - c_sharp
  # ... add/remove as needed
ignore:
  - node_modules
  - dist
  - build
  - target
  - bin
  - obj
visualize:
  maxNodes: 5000
  theme: dark
analysis:
  godNodeThreshold: 10
  complexityThreshold: 15

Server Mode (v6)

Server Mode turns GraphoCode into a shared team service. Start it once on a central machine (or as a Docker container), point it at your workspace, and every developer gets the same graph over HTTP — no local generation required.

Start the server

# Single project
cd /path/to/your/project
graphocode serve --port 4000

# Multi-project workspace
graphocode serve --port 4000 --workspace ~/coderepo

# Accessible from other machines on the network
graphocode serve --host 0.0.0.0 --port 4000 --workspace ~/coderepo

Query via HTTP

# Search
curl "http://localhost:4000/api/search?q=authentication"

# Flow analysis for a function
curl "http://localhost:4000/api/flow/createStepRule"

# Trace callers of a function
curl "http://localhost:4000/api/trace/handleError"

# Find functions producing an error code
curl "http://localhost:4000/api/error/7002"

# Scope query to one service in a multi-project workspace
curl "http://localhost:4000/api/flow/createUser?app=my-service"

# Stats overview
curl "http://localhost:4000/api/stats"

CI/CD — trigger rebuild on every push

# In GitHub Actions / Jenkins / any CI pipeline
curl -X POST "http://graphocode-server:4000/api/generate?app=my-service&branch=main&commit=$GIT_SHA"

The server responds immediately with 202 Accepted and regenerates the graph in the background. All subsequent queries automatically use the new graph once generation completes.

Run as a background service (pm2)

npm install -g pm2
pm2 start "graphocode serve --port 4000 --workspace ~/coderepo" --name graphocode
pm2 save
pm2 startup   # auto-start on reboot

Git Metadata (v6)

When you run graphocode generate inside a git repository, GraphoCode automatically enriches every function and class with its git history. No extra configuration needed.

What gets captured

graphocode generate   # git metadata is extracted automatically

Each concept in graphocode-out/ gains:

git_author: "[email protected]"          # who last changed this file
git_commit: "fc631e03"                   # short SHA of last commit
git_date: "2026-07-15T10:22:00Z"        # when it last changed
git_branch: "development"               # branch at generate time
git_contributors: ["dev1", "dev2"]      # everyone who ever touched it
git_churn: 17                           # total commits (high = risk ⚠️)

Functions with git_churn >= 10 are automatically flagged ⚠️ high churn in the rendered output.

Reading git data in flow output

When you run graphocode flow <function>, the OKF files backing each node in the call tree contain the git section — so you can trace ownership through the entire call chain, not just the entry point.

Skipping git metadata

If your repo has hundreds of files or you are on a CI shallow clone, use --no-git to skip metadata extraction entirely:

graphocode generate --no-git
graphocode generate-all /path/to/apps --workspace ~/coderepo --no-git

This reduces generation time significantly on large repos.

Publishing to npm

npm login
npm publish

Users can then install with:

npm install -g graphocode

License

MIT