{"id":48934687,"url":"https://github.com/cognitx-leyton/graphrag-code","last_synced_at":"2026-04-17T11:01:24.903Z","repository":{"id":351287182,"uuid":"1209646594","full_name":"cognitx-leyton/graphrag-code","owner":"cognitx-leyton","description":"🕸️ Code knowledge graph for Claude Code \u0026 AI coding agents — index TypeScript, NestJS, React into Neo4j and query architecture in Cypher","archived":false,"fork":false,"pushed_at":"2026-04-14T11:19:47.000Z","size":67,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-14T12:24:24.557Z","etag":null,"topics":["ai-agents","ast","claude","claude-code","code-analysis","code-knowledge-graph","codebase-search","coding-agents","cypher","dependency-graph","graphrag","knowledge-graph","mcp","neo4j","nestjs","python","react","retrieval-augmented-generation","static-analysis","typescript"],"latest_commit_sha":null,"homepage":"https://cognitx.leyton.com/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cognitx-leyton.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-13T16:30:43.000Z","updated_at":"2026-04-14T11:00:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cognitx-leyton/graphrag-code","commit_stats":null,"previous_names":["cognitx-leyton/graphrag-code"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/cognitx-leyton/graphrag-code","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cognitx-leyton%2Fgraphrag-code","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cognitx-leyton%2Fgraphrag-code/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cognitx-leyton%2Fgraphrag-code/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cognitx-leyton%2Fgraphrag-code/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cognitx-leyton","download_url":"https://codeload.github.com/cognitx-leyton/graphrag-code/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cognitx-leyton%2Fgraphrag-code/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31926260,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-17T10:35:34.458Z","status":"ssl_error","status_checked_at":"2026-04-17T10:35:09.472Z","response_time":62,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","ast","claude","claude-code","code-analysis","code-knowledge-graph","codebase-search","coding-agents","cypher","dependency-graph","graphrag","knowledge-graph","mcp","neo4j","nestjs","python","react","retrieval-augmented-generation","static-analysis","typescript"],"created_at":"2026-04-17T11:00:58.767Z","updated_at":"2026-04-17T11:01:24.876Z","avatar_url":"https://github.com/cognitx-leyton.png","language":"Python","readme":"# 🕸️ graphrag-code\n\n***A Neo4j code knowledge graph for TypeScript codebases — index NestJS and React code, then answer architecture questions with Cypher.***\n\n![License](https://img.shields.io/badge/license-Apache%202.0-D22128?style=flat-square)\n![Python](https://img.shields.io/badge/python-3.10+-3776AB?style=flat-square\u0026logo=python\u0026logoColor=white)\n![Neo4j](https://img.shields.io/badge/neo4j-5.24-008CC1?style=flat-square\u0026logo=neo4j\u0026logoColor=white)\n![TypeScript](https://img.shields.io/badge/typescript-ready-3178C6?style=flat-square\u0026logo=typescript\u0026logoColor=white)\n![NestJS](https://img.shields.io/badge/nestjs-aware-E0234E?style=flat-square\u0026logo=nestjs\u0026logoColor=white)\n![React](https://img.shields.io/badge/react-aware-61DAFB?style=flat-square\u0026logo=react\u0026logoColor=black)\n\n`graphrag-code` turns a TypeScript/TSX repository into a queryable **code knowledge graph** — a structured retrieval backend for **[Claude Code](https://www.anthropic.com/claude-code)**, **Claude**, and other **AI coding agents**. It walks the AST, recognises framework constructs (NestJS controllers, modules, DI; React components and hooks), and loads the result into Neo4j. Your agent can then ask *architectural* questions — dependency chains, endpoint inventories, component usage, hubs of DI — in Cypher, instead of fuzzy-matching code chunks with embeddings.\n\nBuilt at **[Leyton CognitX](https://cognitx.leyton.com/)** to make large TypeScript monorepos legible to humans, to Claude, and to LLM agents alike.\n\n## 🚀 Quickstart: use in your repo\n\n```bash\npipx install cognitx-codegraph\ncd /path/to/your-repo\ncodegraph init\n```\n\n`codegraph init` asks 4-5 short questions (which packages to index, which package boundaries to enforce, whether to install the Claude Code surface + GitHub Actions gate + local Neo4j) and then:\n\n1. Writes `.claude/commands/` (7 slash commands), `.github/workflows/arch-check.yml`, `.arch-policies.toml`, `docker-compose.yml`, and a `CLAUDE.md` snippet.\n2. Starts a local Neo4j container via `docker compose up -d`.\n3. Runs the first index.\n4. Prints what to query next.\n\nYou're fully set up in ~2 minutes. Want everything without prompts? `codegraph init --yes`. Want just the files and no Docker? `codegraph init --yes --skip-docker --skip-index`.\n\nFull walkthrough: [codegraph/docs/init.md](./codegraph/docs/init.md). Policy reference: [codegraph/docs/arch-policies.md](./codegraph/docs/arch-policies.md).\n\n## ✨ Highlights\n\n- **Framework-aware parsing** — not just imports: controllers, injectables, modules, entities, React components and hooks are first-class nodes.\n- **Neo4j-backed** — every relationship is a Cypher query away. Dependency walks, shortest paths, DI chains, orphan detection, all out of the box.\n- **Claude Code \u0026 AI agent native** — the typed graph is a structured retrieval backend for Claude Code, Claude, and other coding agents that need architectural context, not just nearest-neighbour code chunks.\n- **Monorepo-friendly** — scope indexing to specific packages (`twenty-server`, `twenty-front`, …) and exclude build/test artefacts by default.\n- **Batteries included** — a Typer CLI (`index`, `query`, `validate`), Docker Compose for Neo4j, and a library of example Cypher queries.\n\n## 📑 Table of Contents\n\n- [Why a code knowledge graph?](#-why-a-code-knowledge-graph)\n- [Using with Claude Code \u0026 AI agents](#-using-with-claude-code--ai-agents)\n- [Architecture](#-architecture)\n- [Quickstart](#-quickstart)\n- [Graph schema](#-graph-schema)\n- [Example queries](#-example-queries)\n- [Configuration](#-configuration)\n- [Roadmap](#-roadmap)\n- [Contributing](#-contributing)\n- [Contributors](#-contributors)\n- [Star history](#-star-history)\n- [License](#-license)\n\n## 🧠 Why a code knowledge graph?\n\nVector search over raw code chunks is a blunt instrument. It finds lexically similar snippets, not *architecturally relevant* ones. Questions like *\"which services does this controller transitively depend on?\"*, *\"who injects `AuthService`?\"*, or *\"which React components use this hook?\"* are graph queries, not similarity queries.\n\n`graphrag-code` gives an LLM (or a human) the structured backbone it needs:\n\n- **Retrieval-augmented generation (RAG)** over a TypeScript codebase with typed traversals instead of opaque embeddings.\n- **Architecture audits** — find hubs, cycles, orphans, tangled modules.\n- **Safer refactors** — understand the blast radius of a change before you make it.\n- **Onboarding** — let new engineers query the codebase in plain Cypher instead of reading files top-to-bottom.\n\n## 🤖 Using with Claude Code \u0026 AI agents\n\n`graphrag-code` is designed as a drop-in retrieval backend for agentic coding workflows. The typical pattern for [Claude Code](https://www.anthropic.com/claude-code) (and any other LLM coding agent — Cursor, Aider, Continue, custom MCP clients):\n\n1. **Index your repo once** (see [Quickstart](#-quickstart)) — `codegraph.cli index` walks the AST and loads the graph into Neo4j.\n2. **Expose the graph to your agent** — either via a thin MCP server, a CLI wrapper the agent can shell out to, or direct Bolt queries from tool-call handlers.\n3. **Let the agent ask architectural questions** in Cypher *before* editing code.\n\n### Why this beats embedding-only RAG for coding agents\n\nClaude Code and other coding agents work best with **structured, low-noise context**. Vector search over code chunks pulls back things that *look* similar; a typed graph answers the question the agent is *actually* asking:\n\n| Agent question | Graph query |\n| --- | --- |\n| *\"What would break if I rename `AuthService`?\"* | Reverse `INJECTS` + `IMPORTS*` traversal |\n| *\"What endpoints does `UserController` expose?\"* | `EXPOSES` direct lookup |\n| *\"Which React components call `useAuth`?\"* | `USES_HOOK` lookup |\n| *\"How is this file reached from the auth entrypoint?\"* | `shortestPath` on `IMPORTS` |\n| *\"Which services are DI hubs I should treat as core?\"* | `INJECTS` aggregation |\n\nAll answered in single-digit milliseconds, with zero tokens spent on retrieving irrelevant snippets.\n\n### Exposing the graph to Claude via MCP\n\ncodegraph ships a first-class **[Model Context Protocol](https://modelcontextprotocol.io/)** stdio server. Install the optional extra, add one block to Claude Code's config, and five typed tools appear in the agent's tool menu — no more shelling out to `codegraph query`.\n\n```bash\npip install \"codegraph[mcp]\"\n```\n\nIn `~/.claude.json` (or your Claude Desktop config):\n\n```json\n{\n  \"mcpServers\": {\n    \"codegraph\": {\n      \"command\": \"codegraph-mcp\",\n      \"type\": \"stdio\",\n      \"env\": {\n        \"CODEGRAPH_NEO4J_URI\":  \"bolt://localhost:7688\",\n        \"CODEGRAPH_NEO4J_USER\": \"neo4j\",\n        \"CODEGRAPH_NEO4J_PASS\": \"codegraph123\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Code. Five tools become available:\n\n| Tool | Purpose |\n| --- | --- |\n| `query_graph(cypher, limit)` | Read-only Cypher escape hatch. Writes are rejected at the session level, so an LLM-generated `DROP`/`DELETE` can't mutate the graph. |\n| `describe_schema()` | Labels, relationship types, and per-label node counts — cheap way for an agent to learn what's in the graph at session start. |\n| `list_packages()` | Every indexed monorepo package with its detected framework, version, TypeScript flag, package manager, and detection confidence. |\n| `callers_of_class(class_name, max_depth)` | Blast-radius traversal over `INJECTS` / `EXTENDS` / `IMPLEMENTS`. The canonical \"what breaks if I rename X\" query. |\n| `endpoints_for_controller(controller_name)` | HTTP routes exposed by a NestJS controller class (method + path + handler). |\n| `files_in_package(name, limit)` | List files belonging to a `:Package` by name. |\n| `hook_usage(hook_name, limit)` | Which components / functions use a given React hook. |\n| `gql_operation_callers(op_name, op_type, limit)` | Who calls a GraphQL query / mutation / subscription, optionally narrowed by type. |\n| `most_injected_services(limit)` | Rank `@Injectable` classes by number of unique callers — the classic \"DI hub detection\" query. |\n| `find_class(name_pattern, limit)` | Case-sensitive substring search over class names, backed by the `class_name` index. |\n\nAll ten tools share a single long-lived Neo4j driver and open sessions in `READ_ACCESS` mode. Configuration is env-var only (the same `CODEGRAPH_NEO4J_*` vars the CLI uses). The server is stdio-only — no network exposure.\n\n## 🏗️ Architecture\n\n```\n  TypeScript repo                Parser                Graph loader          Neo4j\n ┌────────────────┐      ┌──────────────────┐      ┌──────────────┐     ┌──────────┐\n │ *.ts / *.tsx   │ ───► │ AST walk          │ ───► │ Typed nodes  │───► │ Property │\n │ packages/*/src │      │ + framework       │      │ + edges      │     │ graph    │\n └────────────────┘      │ detection         │      └──────────────┘     └────┬─────┘\n                         │ (NestJS / React)  │                                │\n                         └──────────────────┘                                 ▼\n                                                                         Cypher / RAG\n```\n\nAll indexing is local: your code never leaves the machine, and Neo4j runs in a Docker container alongside the CLI.\n\n## 🚀 Quickstart\n\n```bash\ncd codegraph\n\n# 1. Python environment\npython3 -m venv .venv\n.venv/bin/pip install -r requirements.txt\n\n# 2. Neo4j (Docker)\ndocker compose up -d\n# Browser UI:  http://localhost:7475   (neo4j / codegraph123)\n# Bolt:        bolt://localhost:7688\n\n# 3. Tell codegraph which packages in your monorepo to index.\n#    Either drop a codegraph.toml at the repo root (see Configuration below)\n#    or pass --package flags:\n.venv/bin/python -m codegraph.cli index /path/to/your-monorepo \\\n  --package packages/server --package packages/web\n\n# 4. Sanity-check the load\n.venv/bin/python -m codegraph.cli validate /path/to/your-monorepo\n\n# 5. Ask a question\n.venv/bin/python -m codegraph.cli query \\\n  \"MATCH (e:Endpoint) RETURN e.method, e.path LIMIT 10\"\n```\n\n## 🧩 Graph schema\n\n**Nodes**\n\n| Kind | Examples / notes |\n| --- | --- |\n| `Package` | One per configured monorepo package with detected `framework` (React / Next.js / Vue / Angular / Svelte / SvelteKit / **NestJS** / Odoo), `framework_version`, `typescript`, `styling`, `router`, `state_management`, `ui_library`, `build_tool`, `package_manager`, and a detection `confidence`. Framework detection walks up to the monorepo root for lockfiles + workspace-hoisted dependencies. |\n| `File` | TS/TSX files with language, LOC, and framework flags (`is_controller`, `is_component`, …) |\n| `Class` | NestJS controllers, injectables, modules, entities, resolvers |\n| `Function` | Exported functions and React components |\n| `Interface` | TypeScript interfaces |\n| `Endpoint` | HTTP routes exposed by controllers (method + path + handler) |\n| `Hook` | React hooks (custom and built-in usage sites) |\n| `Decorator` | Framework decorators applied to classes/methods |\n| `External` | Symbols imported from `node_modules` |\n\n**Edges**\n\n`IMPORTS`, `IMPORTS_EXTERNAL`, `DEFINES_CLASS`, `DEFINES_FUNC`, `DEFINES_IFACE`, `EXPOSES`, `INJECTS`, `EXTENDS`, `IMPLEMENTS`, `RENDERS`, `USES_HOOK`, `DECORATED_BY`, `BELONGS_TO` (File → Package).\n\n## 🔎 Example queries\n\nA handful of the queries in [`codegraph/queries.md`](codegraph/queries.md):\n\n```cypher\n// 1. Every HTTP endpoint with its controller\nMATCH (c:Class {is_controller:true})-[:EXPOSES]-\u003e(e:Endpoint)\nRETURN c.name, e.method, e.path, e.handler\nORDER BY c.name, e.path;\n\n// 2. Most-injected services (DI hubs)\nMATCH (svc:Class {is_injectable:true})\u003c-[:INJECTS]-(caller:Class)\nRETURN svc.name, count(caller) AS injections\nORDER BY injections DESC LIMIT 20;\n\n// 3. Which React components use a given hook?\nMATCH (:Hook {name:'useAuth'})\u003c-[:USES_HOOK]-(c:Function)\nRETURN c.name, c.file;\n\n// 4. Transitive dependencies of a file\nMATCH (:File {path:$start})-[:IMPORTS*1..3]-\u003e(d:File)\nRETURN DISTINCT d.path;\n```\n\nSee [`codegraph/queries.md`](codegraph/queries.md) for the full catalogue.\n\n## ⚙️ Configuration\n\n### Project config — `codegraph.toml`\n\n`codegraph` has **no hardcoded packages**. You tell it which packages to index via a `codegraph.toml` at the repo root, a `[tool.codegraph]` block in your existing `pyproject.toml`, or `--package` flags on the CLI. Config file values are loaded first; CLI flags override them.\n\n**`codegraph.toml`** (preferred — a standalone file, no interference with Python tooling):\n\n```toml\n# Paths are relative to the repo root. Each entry should be a TypeScript\n# package directory (i.e. contain a package.json / tsconfig.json so path\n# aliases can be resolved).\npackages = [\n  \"packages/server\",\n  \"packages/web\",\n]\n\n# Optional — these extend the built-in defaults, they don't replace them.\nexclude_dirs     = [\"custom-build\", \"fixtures\"]\nexclude_suffixes = [\".gen.ts\"]\n```\n\n**`pyproject.toml`** (if you already have one and want everything in one place):\n\n```toml\n[tool.codegraph]\npackages = [\"packages/server\", \"packages/web\"]\n```\n\n**CLI override** — wins over either file:\n\n```bash\ncodegraph index . --package packages/server --package packages/web\n```\n\nIf no config file exists and no `--package` flags are passed, `index` stops with a clear error. There are no Twenty-specific or other defaults.\n\n### Python support (`.py` indexing)\n\ncodegraph also indexes Python codebases. The detector auto-picks the language based on the package directory: if the directory contains `__init__.py`, it's parsed as Python; otherwise it's parsed as TypeScript (with `tsconfig.json` / `package.json`).\n\nInstall the optional `[python]` extra to enable the Python frontend:\n\n```bash\npip install \"codegraph[python]\"\n```\n\nThen point `--package` at a Python package root (the directory containing `__init__.py`):\n\n```bash\ncodegraph index . --package src/my_package\n```\n\nStage 1 indexes: modules (`.py` files), classes, functions, methods, imports (relative + absolute + `import x as y`), class inheritance, and decorators. Framework detection (FastAPI / Flask / Django / Typer / pytest) and route extraction land in Stage 2.\n\n### Neo4j connection\n\nControlled via environment variables (defaults match the bundled `docker-compose.yml`):\n\n| Variable | Default |\n| --- | --- |\n| `CODEGRAPH_NEO4J_URI` | `bolt://localhost:7688` |\n| `CODEGRAPH_NEO4J_USER` | `neo4j` |\n| `CODEGRAPH_NEO4J_PASS` | `codegraph123` |\n\n### File walk exclusions\n\nIndexing always skips `node_modules`, `dist`, `build`, `.next`, `.turbo`, `.nuxt`, `.svelte-kit`, `.vercel`, `coverage`, `generated`, `__generated__`, `.cache`, `.parcel-cache`, plus `*.d.ts` and `*.stories.{ts,tsx}`. Add to these via `exclude_dirs` / `exclude_suffixes` in your config — those keys **extend** the defaults, they don't replace them.\n\n### `.codegraphignore`\n\nFor **confidential routes, components, or files** that shouldn't reach the graph (and therefore shouldn't reach any LLM agent querying it), drop a `.codegraphignore` file at the repo root. Syntax is gitignore-style, plus two codegraph extensions:\n\n```gitignore\n# Standard gitignore — file paths\n**/admin/**\n**/*.secret.ts\n!**/admin/public/**         # negation — re-include a subtree\n\n# Route patterns — match RouteNode.path\n@route:/admin/*\n@route:/settings/system/*\n\n# Component patterns — match React component / NestJS class names\n@component:*Admin*\n@component:*UserManagement*\n```\n\nOverride the default location with `--ignore-file PATH` on the CLI or `ignore_file = \"custom/.ignore\"` in `codegraph.toml`. `.codegraphignore` is **additive** on top of `BASE_EXCLUDE_DIRS` — it doesn't replace them.\n\n## 🛣️ Roadmap\n\n- Incremental re-indexing on file changes\n- Python and Go language frontends\n- ~~First-class MCP server exposing the graph to LLM agents~~ — **shipped** (see [Exposing the graph to Claude via MCP](#exposing-the-graph-to-claude-via-mcp))\n- Pre-built RAG retrievers for common architecture questions\n\n## 🤝 Contributing\n\nPRs welcome. The repository uses protected branches:\n\n- **`main`** — production-ready code. All changes land here via PR.\n- **`release`** — release-candidate branch. Stabilisation before tagging.\n- **`hotfix`** — urgent fixes that need to skip the normal cycle.\n\nEvery PR into `main`, `release`, or `hotfix` requires a Code Owner review (see [`CODEOWNERS`](CODEOWNERS)). Please open an issue before a large refactor so we can align on direction.\n\n## 👥 Contributors\n\nThanks to everyone who has helped shape `graphrag-code`:\n\n\u003ca href=\"https://github.com/cognitx-leyton/graphrag-code/graphs/contributors\"\u003e\n  \u003cimg alt=\"Avatar grid of graphrag-code contributors\" src=\"https://contrib.rocks/image?repo=cognitx-leyton/graphrag-code\" /\u003e\n\u003c/a\u003e\n\n*Made with [contrib.rocks](https://contrib.rocks).*\n\n## ⭐ Star history\n\nIf `graphrag-code` helps you make sense of a TypeScript monorepo, a star helps others find it too.\n\n\u003ca href=\"https://www.star-history.com/?repos=cognitx-leyton%2Fgraphrag-code\u0026type=date\u0026legend=top-left\"\u003e\n \u003cpicture\u003e\n   \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/chart?repos=cognitx-leyton/graphrag-code\u0026type=date\u0026theme=dark\u0026legend=top-left\" /\u003e\n   \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/chart?repos=cognitx-leyton/graphrag-code\u0026type=date\u0026legend=top-left\" /\u003e\n   \u003cimg alt=\"Star History Chart\" src=\"https://api.star-history.com/chart?repos=cognitx-leyton/graphrag-code\u0026type=date\u0026legend=top-left\" /\u003e\n \u003c/picture\u003e\n\u003c/a\u003e\n\n## 📄 License\n\nLicensed under the [Apache License 2.0](LICENSE). Copyright © [Leyton CognitX](https://cognitx.leyton.com/) and contributors.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcognitx-leyton%2Fgraphrag-code","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcognitx-leyton%2Fgraphrag-code","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcognitx-leyton%2Fgraphrag-code/lists"}