chore: import upstream snapshot with attribution
This commit is contained in:
wehub-resource-sync
@@ -0,0 +1,97 @@
|
||||
---
|
||||
title: Configuration
|
||||
description: CodeGraph is zero-config by default, with one optional codegraph.json for custom extensions, excluding tracked directories, indexing gitignored source, and indexing nested git repositories.
|
||||
---
|
||||
|
||||
Next to none — CodeGraph is **zero-config by default**, with nothing to write or keep in sync to get started. Language support is automatic from the file extension; there's nothing to wire up per language. The one optional file, `codegraph.json`, covers [custom file extensions](#custom-file-extensions), [excluding tracked directories](#excluding-a-tracked-directory), [indexing gitignored source](#indexing-gitignored-source-a-second-vcs), and [indexing nested git repositories](#indexing-nested-git-repositories).
|
||||
|
||||
## What it skips out of the box
|
||||
|
||||
- **Dependency, build, and cache directories** — `node_modules`, `vendor`, `dist`, `build`, `target`, `.venv`, `Pods`, `.next`, and the like across every [supported stack](/codegraph/reference/languages/) — so the graph is your code, not third-party noise. This holds even with no `.gitignore`.
|
||||
- **Anything in your `.gitignore`** — honored in git repos via git, and in non-git projects by reading `.gitignore` directly (root and nested).
|
||||
- **Files larger than 1 MB** — generated bundles, minified JS, vendored blobs.
|
||||
|
||||
## Excluding or including more
|
||||
|
||||
To keep something else out, add it to `.gitignore`. To pull a default-excluded directory back **in** (e.g. you really want a vendored dependency indexed), add a negation — `!vendor/`.
|
||||
|
||||
The defaults apply uniformly, so committing a dependency or build directory doesn't force it into the graph — the `.gitignore` negation is the explicit opt-in.
|
||||
|
||||
## Excluding a tracked directory
|
||||
|
||||
`.gitignore` only affects files git **doesn't already track** — it can't drop a directory you've committed. So a vendored theme, SDK, or asset bundle that's checked into the repo (say a Metronic admin theme under `static/`, with hundreds of `.js` files) can't be excluded that way. For those, list them under `exclude` in `codegraph.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"exclude": ["static/", "**/vendor/**"]
|
||||
}
|
||||
```
|
||||
|
||||
Each entry is a gitignore-style pattern, matched against project-root-relative paths, and honored everywhere CodeGraph looks at files — the full index, incremental `sync`, and file-watching. It applies even to tracked files (that's the whole point) and takes precedence over everything else, so it's the right tool for a large committed dependency that bloats the graph but isn't really your code. (This is the opposite of [`includeIgnored`](#indexing-nested-git-repositories), which pulls gitignored directories back *in*.)
|
||||
|
||||
Re-index (`codegraph index`) after adding or changing `exclude`.
|
||||
|
||||
## Indexing gitignored source (a second VCS)
|
||||
|
||||
`.gitignore` keeps files out of the index — which is usually what you want, but not when the gitignored files are real first-party source. The case this exists for: a project tracked by **SVN, Perforce, or another VCS alongside Git**, where some source is committed to that VCS and deliberately listed in `.gitignore` so it never lands in Git. That source is still yours and you want it in the graph, but git never lists it, so CodeGraph never sees it. (`includeIgnored` doesn't help — it only revives *embedded git repositories* inside a gitignored directory, not plain source.)
|
||||
|
||||
List those paths under `include` in `codegraph.json` to force them in:
|
||||
|
||||
```json
|
||||
{
|
||||
"include": ["Tools/", "Local/typescript/"]
|
||||
}
|
||||
```
|
||||
|
||||
Each entry is a gitignore-style pattern, matched against project-root-relative paths (a directory like `"Tools/"`, a recursive `"Tools/**"` glob, or a single file all work). CodeGraph discovers the matching files directly off disk — overriding `.gitignore` — and indexes them everywhere it looks at files: the full index, incremental `sync`, and file-watching.
|
||||
|
||||
A few things to know:
|
||||
|
||||
- An explicit [`exclude`](#excluding-a-tracked-directory) still wins — listing the same path in both keeps it out.
|
||||
- Built-in skips like `node_modules`, `dist`, and `.git` are never re-included, even when an `include` pattern would match inside them.
|
||||
- This is the opposite of `exclude` (which keeps tracked files *out*); it's for source git itself never tracks.
|
||||
|
||||
Re-index (`codegraph index`) after adding or changing `include`.
|
||||
|
||||
## Custom file extensions
|
||||
|
||||
If your project uses a non-standard extension for a [supported language](/codegraph/reference/languages/) — say `.dota_lua` for Lua, or `.tpl` for PHP — those files are skipped by default, because the extension isn't one CodeGraph recognizes. Map them with an optional `codegraph.json` at your project root:
|
||||
|
||||
```json
|
||||
{
|
||||
"extensions": {
|
||||
".dota_lua": "lua",
|
||||
".tpl": "php"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Each value is a supported language id. The mappings merge on top of the built-in defaults and win on conflict, so you can also re-point a built-in (e.g. `".h": "cpp"`). Commit the file to share the mapping with your team.
|
||||
|
||||
A typo'd language or a malformed file is warned about and skipped — it never breaks indexing — and a project with no `codegraph.json` behaves exactly as before. Re-index (`codegraph index`) after adding or changing mappings.
|
||||
|
||||
## Indexing nested git repositories
|
||||
|
||||
CodeGraph respects your `.gitignore`, so a directory you've gitignored stays out of the graph — **including any git repositories nested inside it.** If you keep cloned reference projects, vendored copies, or a folder of unrelated repos in a gitignored directory (a `resource/`, `.repos/`, or `examples/` dir), CodeGraph leaves it untouched: it won't walk in, discover the embedded repos, or index them.
|
||||
|
||||
If instead you run a **"super-repo" of independent clones** — a workspace whose own `.gitignore` lists its child repos to keep `git status` quiet, where you genuinely want every child indexed into one graph — opt those directories back in with `includeIgnored`:
|
||||
|
||||
```json
|
||||
{
|
||||
"includeIgnored": ["packages/", "services/"]
|
||||
}
|
||||
```
|
||||
|
||||
Each entry is a gitignore-style pattern naming a gitignored directory whose nested git repositories should be indexed anyway. CodeGraph descends into the directories you list and indexes each embedded repo by its own `git ls-files`, so every child repo's own `.gitignore` is still honored. Directories you don't list stay excluded.
|
||||
|
||||
A few things to know:
|
||||
|
||||
- **Untracked** nested repositories (ones you haven't gitignored) are indexed automatically — `includeIgnored` is only for the ones your `.gitignore` excludes.
|
||||
- Built-in skips like `node_modules` are never re-included, even inside an opted-in directory.
|
||||
- A project without this layout needs no `codegraph.json` at all.
|
||||
|
||||
Re-index (`codegraph index`) after adding or changing `includeIgnored`.
|
||||
|
||||
## Where data lives
|
||||
|
||||
Per-project data lives in a `.codegraph/` directory at your project root, containing the SQLite database (`codegraph.db`). Nothing leaves your machine.
|
||||
@@ -0,0 +1,70 @@
|
||||
---
|
||||
title: Installation
|
||||
description: Install CodeGraph and configure your AI coding agents.
|
||||
---
|
||||
|
||||
## 1. Run the installer
|
||||
|
||||
```bash
|
||||
npx @colbymchenry/codegraph
|
||||
```
|
||||
|
||||
The installer will:
|
||||
|
||||
- Ask which agent(s) to configure — auto-detecting installed ones from **Claude Code**, **Cursor**, **Codex CLI**, **opencode**, **Hermes Agent**, **Gemini CLI**, **Antigravity IDE**, and **Kiro**.
|
||||
- Prompt to install `codegraph` on your `PATH` (so agents can launch the MCP server).
|
||||
- Ask whether configs apply to all your projects or just this one.
|
||||
- Write each chosen agent's MCP server config, plus a small marker-fenced CodeGraph section in the agent's instructions file (`CLAUDE.md` / `AGENTS.md` / `GEMINI.md`). Cursor and Kiro get the MCP config only. Removed cleanly by `codegraph uninstall`.
|
||||
- Set up auto-allow permissions when Claude Code is one of the targets.
|
||||
|
||||
The installer **wires up your agents only — it does not index your code.** After it finishes, build each project's graph yourself with `codegraph init` (step 3 below).
|
||||
|
||||
## Non-interactive (scripting / CI)
|
||||
|
||||
```bash
|
||||
codegraph install --yes # auto-detect agents, install global
|
||||
codegraph install --target=cursor,claude --yes # explicit target list
|
||||
codegraph install --target=auto --location=local # detected agents, project-local
|
||||
codegraph install --print-config codex # print snippet, no file writes
|
||||
```
|
||||
|
||||
| Flag | Values | Default |
|
||||
|---|---|---|
|
||||
| `--target` | `auto`, `all`, `none`, or csv (`claude,cursor,…`) | prompt |
|
||||
| `--location` | `global`, `local` | prompt |
|
||||
| `--yes` | (boolean) | prompt every step |
|
||||
| `--no-permissions` | (boolean) skip Claude auto-allow list | permissions on |
|
||||
| `--print-config <id>` | dump snippet for one agent and exit | — |
|
||||
|
||||
## 2. Restart your agent
|
||||
|
||||
Restart your agent (Claude Code / Cursor / Codex CLI / opencode / Hermes Agent / Gemini CLI / Antigravity IDE / Kiro) for the MCP server to load.
|
||||
|
||||
## 3. Initialize projects
|
||||
|
||||
```bash
|
||||
cd your-project
|
||||
codegraph init
|
||||
```
|
||||
|
||||
`codegraph init` creates the local `.codegraph/` directory and builds the full graph in the same step — one command. A single global `codegraph install` covers every project; you run `codegraph init` once per project.
|
||||
|
||||
## Supported platforms
|
||||
|
||||
Every release ships a self-contained build (bundled Node runtime — nothing to compile) for all three desktop OSes, on both x64 and arm64:
|
||||
|
||||
| Platform | Architectures | Install |
|
||||
|---|---|---|
|
||||
| Windows | x64, arm64 | PowerShell installer or npm |
|
||||
| macOS | x64, arm64 | shell installer or npm |
|
||||
| Linux | x64, arm64 | shell installer or npm |
|
||||
|
||||
## Uninstall
|
||||
|
||||
Changed your mind? One command removes CodeGraph from every agent it configured:
|
||||
|
||||
```bash
|
||||
codegraph uninstall
|
||||
```
|
||||
|
||||
This reverses the installer — stripping CodeGraph's MCP server config, instructions, and permissions from each configured agent. Your project indexes (`.codegraph/`) are left untouched; remove those per-project with `codegraph uninit`. Use `--target` to remove from specific agents, or `--yes` to run non-interactively.
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
title: Introduction
|
||||
description: What CodeGraph is, and why it makes AI coding agents faster and more precise.
|
||||
---
|
||||
|
||||
CodeGraph is a **local-first code-intelligence tool**. It parses your codebase with [tree-sitter](https://tree-sitter.github.io/), stores every symbol, edge, and file in a local SQLite database, and exposes the result as a queryable **knowledge graph** — over the [Model Context Protocol (MCP)](/codegraph/reference/mcp-server/), a CLI, and a TypeScript library.
|
||||
|
||||
It exists to make AI coding agents — Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, and Kiro — **answer structural questions without scanning files**. Instead of fanning out across `grep`, `glob`, and `Read` to reconstruct how code fits together, an agent queries a pre-built index and gets the answer in a handful of calls.
|
||||
|
||||
## Why it matters
|
||||
|
||||
When an agent explores a codebase, it spends most of its budget on *discovery* — finding the right files before it can read them. CodeGraph removes that step: it hands the agent the exact code it needs in one call, so symbol relationships, call graphs, and structure don't have to be rebuilt file by file.
|
||||
|
||||
The universal win is **surgical context and speed** — fewer tool calls, faster answers, on every codebase. Tested across 7 real-world open-source codebases (median of 4 runs per arm), giving an agent CodeGraph meant, regardless of repo size:
|
||||
|
||||
- **58% fewer tool calls**
|
||||
- **22% faster**
|
||||
- **file reads cut to ~zero**
|
||||
|
||||
Token and dollar savings are real too, but they're the **scale-dependent bonus** that shows up on large, tangled codebases run at volume — small and noisy on a modest repo, material only once the codebase (and the team) gets big.
|
||||
|
||||
## What's in the graph
|
||||
|
||||
- **Symbols** — functions, classes, methods, types, routes, components, and more.
|
||||
- **Edges** — calls, imports, inheritance, references, and framework-specific relationships.
|
||||
- **Files** — structure plus full-text search (FTS5).
|
||||
|
||||
Extraction is **deterministic** — derived from the AST, never LLM-summarized.
|
||||
|
||||
## 100% local
|
||||
|
||||
No data leaves your machine. No API keys, no external services — just a SQLite database in `.codegraph/`.
|
||||
|
||||
Ready to try it? Head to the [Quickstart](/codegraph/getting-started/quickstart/).
|
||||
@@ -0,0 +1,25 @@
|
||||
---
|
||||
title: Next Steps
|
||||
description: Where to go once CodeGraph is installed and indexing.
|
||||
---
|
||||
|
||||
You've got CodeGraph installed and a graph built. Here's where to go next.
|
||||
|
||||
## Understand the model
|
||||
|
||||
- [How It Works](/codegraph/core-concepts/how-it-works/) — the extraction → storage → resolution → sync pipeline.
|
||||
- [The Knowledge Graph](/codegraph/core-concepts/knowledge-graph/) — the node and edge kinds the graph is built from.
|
||||
- [Resolution & Frameworks](/codegraph/core-concepts/resolution/) — how references and framework routes get connected.
|
||||
|
||||
## Put it to work
|
||||
|
||||
- [Indexing a Project](/codegraph/guides/indexing/) — full index, incremental sync, and the file watcher.
|
||||
- [Framework Routes](/codegraph/guides/framework-routes/) — link URL patterns to their handlers.
|
||||
- [Affected Tests in CI](/codegraph/guides/affected-tests/) — run only the tests a change touches.
|
||||
|
||||
## Reference
|
||||
|
||||
- [MCP Server](/codegraph/reference/mcp-server/) — the tools agents call.
|
||||
- [CLI](/codegraph/reference/cli/) — every command and flag.
|
||||
- [API](/codegraph/reference/api/) — use CodeGraph as a TypeScript library.
|
||||
- [Integrations](/codegraph/reference/integrations/) — supported agents and manual setup.
|
||||
@@ -0,0 +1,39 @@
|
||||
---
|
||||
title: Get Started
|
||||
description: Get up and running with CodeGraph in seconds.
|
||||
---
|
||||
|
||||
Get up and running with CodeGraph in seconds.
|
||||
|
||||
## 1. Install the CLI
|
||||
|
||||
No Node.js required — one command grabs the right build for your OS:
|
||||
|
||||
```bash
|
||||
# macOS / Linux
|
||||
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
|
||||
|
||||
# Windows (PowerShell)
|
||||
irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex
|
||||
```
|
||||
|
||||
Already have Node? `npm i -g @colbymchenry/codegraph` works on any version. CodeGraph bundles its own runtime — nothing to compile, no native build, works the same everywhere. The installer puts `codegraph` on your `PATH` but doesn't change your current shell — open a new terminal before the next step.
|
||||
|
||||
## 2. Wire up your agent(s)
|
||||
|
||||
```bash
|
||||
codegraph install
|
||||
```
|
||||
|
||||
Auto-detects and configures Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, and Kiro — wiring the CodeGraph MCP server into each. This step connects your agents only; it does **not** index any code. (Shortcut: `npx @colbymchenry/codegraph` downloads and runs the installer in one go.)
|
||||
|
||||
## 3. Initialize each project
|
||||
|
||||
```bash
|
||||
cd your-project
|
||||
codegraph init
|
||||
```
|
||||
|
||||
`codegraph init` creates the local `.codegraph/` directory and builds the full graph in the same step — one command, done. Your agent will use CodeGraph tools automatically when a `.codegraph/` directory exists.
|
||||
|
||||
Next: build [Your First Graph](/codegraph/getting-started/your-first-graph/), or see the full [Installation](/codegraph/getting-started/installation/) options.
|
||||
@@ -0,0 +1,51 @@
|
||||
---
|
||||
title: Your First Graph
|
||||
description: Build an index and run your first queries against it.
|
||||
---
|
||||
|
||||
Once CodeGraph is installed, building and exploring a graph takes a few commands.
|
||||
|
||||
## Index a project
|
||||
|
||||
```bash
|
||||
cd your-project
|
||||
codegraph init
|
||||
```
|
||||
|
||||
`codegraph init` creates the `.codegraph/` directory and builds the full graph in the same step — one command, done. From there a native file watcher keeps the index in sync on every change, so you rarely need to rebuild by hand. When you do want to:
|
||||
|
||||
```bash
|
||||
codegraph index # full re-index
|
||||
codegraph sync # incremental update of changed files
|
||||
```
|
||||
|
||||
## Check it worked
|
||||
|
||||
```bash
|
||||
codegraph status
|
||||
```
|
||||
|
||||
This reports the node/edge/file counts, the active SQLite backend, and the journal mode — a quick health check that the index is ready.
|
||||
|
||||
## Run a query
|
||||
|
||||
Reach for `codegraph explore` first — a natural-language question or a bag of symbol names returns the relevant source plus the call paths between those symbols in a single shot (the same output the `codegraph_explore` tool gives your agent):
|
||||
|
||||
```bash
|
||||
codegraph explore "how does login work"
|
||||
```
|
||||
|
||||
For narrower, scriptable lookups there are focused commands:
|
||||
|
||||
```bash
|
||||
codegraph query UserService # find symbols by name
|
||||
codegraph callers handleRequest # what calls a function
|
||||
codegraph callees handleRequest # what a function calls
|
||||
codegraph impact AuthMiddleware # what a change would affect
|
||||
```
|
||||
|
||||
These four each accept `--json` for machine-readable output. See the full [CLI reference](/codegraph/reference/cli/).
|
||||
|
||||
## Hand it to your agent
|
||||
|
||||
With a `.codegraph/` directory present and an agent configured (see [Installation](/codegraph/getting-started/installation/)), your agent uses the [MCP tools](/codegraph/reference/mcp-server/) automatically — no extra step.
|
||||
Reference in New Issue
Block a user