git:20260905.2219623 to git:20260908.bea9f98

- Use codegraph when a repository question depends on structure rather than exact text:

-

- - architecture, hotspots, cycles, unresolved imports, and public API surface

- - definitions, references, dependencies, reverse dependencies, and paths

- - PR or worktree impact, candidate tests, affected test lists, and risk signals

- - duplicate cleanup and refactor-risk triage

- - local Markdown link validation with exact ranges and no network access

- - bounded context for agents through explore, orientation, search, packets, explain, and MCP

-

- Use plain text search for exact strings, logs, config keys, secrets, and prose. Do not treat codegraph as runtime proof; verify behavior with focused tests or execution.

-

- ## Choose the First Command

-

- Bare `codegraph` prints five task-first routes without scanning the project. Use `codegraph --help` for Core commands, `codegraph help advanced` for the complete catalog, and `codegraph help <command>` for command help; unknown commands suggest but never execute alternatives.

-

- Exit `0` means completion without a failure condition. Exit `1` can mean findings, no matching target, or a runtime failure. Inspect its output before continuing; findings and no matching targets are actionable, while runtime or analysis failures need error handling.

-

- Exit `2` means invalid usage or input, including malformed options and unsupported explicit `chunk --language` values. `links` uses `1` for broken local links; do not treat it as an invocation error.

-

- | Task | Start here |

- | --------------------------------------------------------- | -------------------------------------------------------- |

- | Review staged and unstaged work | `codegraph review` |

- | Review a branch against main | `codegraph review --base origin/main --head HEAD` |

- | Map the wider blast radius of a change | `codegraph impact --base HEAD --head WORKTREE` |

- | Select deterministic test paths for changed files | `codegraph affected --base HEAD --head WORKTREE --quiet` |

- | Find a concrete term | `codegraph search "auth user" --json` |

- | Map a repo before selecting a target | `codegraph orient --root . --budget small` |

- | Build context from one narrow query | `codegraph explore "how does auth reach db?" --root .` |

- | Diagnose installation, native runtime, or artifact health | `codegraph doctor` |

-

- Prefer `review` before `impact`: review is the compact reviewer handoff; impact is the broader "what could this break?" map. Start with `orient`, then use `search` or `grep` for concrete terms and `refs` or `callers` for known symbols. Use `explore` only for one narrow query that needs context from top results.

-

- ## Keep the Project Boundary Explicit

-

- Use `--root` to define the boundary for config lookup, path confinement, and output normalization. Cache contents use project-relative paths and may live at the resolved repository anchor; override location with `--cache-dir` or `CODEGRAPH_CACHE_DIR`. An overridden anchor pointing at the home directory or a filesystem root is rejected with an error.

-

- - Positional paths are include roots inside the project boundary for `orient`, `drift`, and positional graph commands.

- - `codegraph.config.json` discovery globs are project-root-relative.

- - `languages.extensions` maps literal suffixes such as `.tpl` to supported language IDs; longest suffix wins, while `.vue` and `.svelte` cannot be remapped.

- - CLI `--include-glob` and `--ignore-glob` values are one-off filters relative to each active scan root.

- - Use `--no-gitignore` only when ignored files are intentionally in scope.

- - Index-backed commands stay quiet for their first second, then write progress and a heartbeat to stderr. Cold or incompatible rebuilds report source discovery, Git listing or filesystem scan, ignore-file listing, and metadata discovery before build progress; path checks include completed and total counts when known. Use `--progress` for immediate logs or `--no-progress` to suppress feedback; JSON stdout remains unchanged.

-

- ## Choose the Smallest Follow-up

-

- ### Understand

-

- - map a repo: `codegraph orient --root . --budget small`

- - find a target: `codegraph symbols "CodeReviewSession"` / `codegraph search "auth user"` / `codegraph grep "spawn|timeout"`

- - navigate a symbol: `codegraph refs <handle>` -> `codegraph callers <handle>` -> `codegraph rdeps <file|handle>`

- - explain or retrieve a target: `codegraph explain <handle>` or `codegraph packet get <handle>`

- - use `codegraph explore` only for one hybrid search plus context from top results

-

- Use `search --no-snippets` when handles and paths are sufficient and source text will be fetched separately with `file`. Use `explain --changed-context` for bounded source context around changed ranges in changed-file or review workflows.

-

- Use `symbols` instead of hybrid `search` when only declarations should compete. It supports `--kind <kind,...>`, `--exported`, `--include-imports`, project-relative `--file-glob`, and `--limit <0-500>`; imports default off, and only named/default aliases that resolve to concrete declarations are returned.

- Use the portable callable handle from `symbols` with `codegraph callers <handle>` or `codegraph callees <handle>`. Depth defaults to 1 and caps at 5, the symbol limit defaults to 100 and caps at 500, pretty grouped callsites are the default, and `--json` returns the structured envelope.

-

- Call hierarchy contains resolved semantic `calls` edges only. `--include-heuristic` is accepted but currently adds no guessed dynamic calls; use `refs` for all references and `deps` or `rdeps` for file relationships.

-

- Receiver method calls (`this.m()`, `$this->m()`, `const l = new Lib(); l.target()`) are resolved `calls` edges, including inherited members. `super`/`base`/`parent` follow class `extends` ancestors only. Unproven receivers and Go methods declared outside the type emit no edge.

-

- Use a portable handle, unique exact symbol name, single-definition file, or source location with `codegraph supertypes <target>`, `codegraph subtypes <target>`, or `codegraph implementations <target>`. Hierarchy depth defaults to 1 and caps at 10; all result limits default to 100 and cap at 500, and the default output is the concise human-readable form.

-

- Hierarchy results contain only proven indexed `extends` and `implements` relationships. Implementation targets are interfaces, traits, abstract types, and members with proven implementation or override relationships; exact declarations are returned, while overloads, dynamic or structural conformance, unrelated same-name methods, and unresolved external bases are not guessed.

-

- Use `codegraph rename-preview <target> <new-name> --json` to plan a semantic rename without changing files. Add `--include-comments`, `--include-strings`, or `--include-filenames` only when needed, and use `--max-edits <1-10000>` to bound the plan.

-

- Treat `safe: false`, conflicts, unsafe sites, and omissions as blockers. Eligible exported class, interface, and type filename results are suggestions only; codegraph has no apply command or tool.

-

- Use `codegraph refactor-plan <target>` to compose references, direct callers and callees, hierarchy, implementations, section issues, candidate tests, omissions, and copyable follow-ups from one snapshot. It accepts portable search or workspace-symbol handles and exact internal review or impact symbol handles; add `--rename <new-name>` only when the packet should include the authoritative nested rename preview.

-

- The independent `--max-references`, `--max-callers`, and `--max-hierarchy` bounds accept 0 to 500, and `--include-source` opts reference context into output. Treat `sectionIssues`, omissions, and nested `rename.safe` as authoritative; the packet is read-only and has no apply action.

-

- ### Navigate

-

- - dependencies: `codegraph deps <file|file::symbol|symbol:...>`

- - reverse dependencies: `codegraph rdeps <file|file::symbol|symbol:...>`

- - shortest path: `codegraph path <from> <to>`

- - definition at a source location: `codegraph goto <file>:<line>:<column>`

- - references at a source location: `codegraph refs <file>:<line>:<column>`

- - coordinate-free definition or references: `codegraph goto <file>::<symbol>` returns one definition; `codegraph refs <file>::<symbol>` resolves one definition then reports its references (both accept `symbol:...`)

- - references for every definition in a file: `codegraph refs <file>`

-

- Use line and column coordinates when known; this is the primary navigation form. Use an exact project-relative `file::symbol` path or portable `symbol:` handle when coordinates are unavailable; neither can be combined with line or column input.

-

- - `deps` and `rdeps` accept either form or a portable `symbol:` handle, resolved to its defining file.

- - `deps` and `rdeps` show depth 1 by default; use `--depth <n>` for another finite output depth or `--all` for every depth.

- - `deps` and `rdeps` return `{ items, truncated }` with `--json`.

- - `callers` and `callees` expose symbol-level calls, returning symbols and callsites separately, both bounded and with truncation metadata.

-

- Safe shorthand: `impact` and git-backed `drift` default to `HEAD..WORKTREE`; `artifact`, `packet`, and `mcp` infer `build`, `get`, and `serve`. `artifact --sqlite` is equivalent to `artifact build --sqlite`; `grep <regex>` and `sql <db> "SELECT ..."` accept positional forms. Explicit options remain valid. `grep --json` returns an envelope `{ items, limit, totalSeen, truncated, omitted }`, not a bare hit array: `limit` is the effective `--max-hits` cap for text greps (default 5000, capped at 200000) and `null` for uncapped `--query` AST greps. Check `truncated` before treating text results as complete, and raise `--max-hits` when it is true - `truncated` stays exact through that ceiling. `graph` output selectors are mutually exclusive.

-

- - compact review handoff: `codegraph review`

- - broader change impact: `codegraph impact --base HEAD --head WORKTREE`

- - impact with candidate tests: `codegraph impact --base HEAD --head WORKTREE --include-tests`

- - affected test paths: `codegraph affected --base HEAD --head WORKTREE --quiet`

- - architecture drift: `codegraph drift ./src --base origin/main --head HEAD --graph-edges summary --public-api removals`

- - architecture summary: `codegraph inspect ./src --limit 20`

- - prioritized cycles: `codegraph cycles --sort priority`

- - duplicate cleanup: `codegraph duplicates --root . ./src --profile cleanup`

- - full duplicate groups: `codegraph duplicates --root . ./src --json`

- - local Markdown link check: `codegraph links --json`

- - exported API summary: `codegraph apisurface --root . --json`

- - embedding-ready file chunks: `codegraph chunk src/auth.ts --json` (explicit `--language` must be supported; unknown extensions use text)

- - one indexed module: `codegraph dumpmod src/auth.ts --json`

- - prewarm or repair disk state: `codegraph index --root .`

- - include static-string Python `importlib.import_module(...)` and `__import__(...)` edges: `codegraph graph --root . --dynamic-import-heuristics`

- - inspect complex files: `codegraph hotspots --root . --limit 20`

- - list unresolved source imports: `codegraph unresolved --root . --json`

- - search text with a regex: `codegraph grep "TODO|FIXME" --glob "src/**/*.ts"`

- - query an exported SQLite graph: `codegraph sql codegraph.sqlite "SELECT * FROM files LIMIT 20"`

- - compare graph changes across revisions: `codegraph graph-delta --git-base origin/main --git-head HEAD --json`

- - create a durable artifact: `codegraph artifact --root . --out codegraph-out --sqlite --graph-json`

- - start a warm local tool server: `codegraph mcp --root . --stdio`

-

- Dynamic import heuristics use shared language adapters, including JS and TypeScript embedded script blocks. The Python adapter recognizes direct `importlib.import_module(...)`, direct `__import__(...)`, and direct import aliases when the module argument is a static string. It does not evaluate computed names, assignment-based aliases, name reassignment, the `package=` argument, or `__import__` relative `level=` semantics; leading-dot `importlib.import_module(...)` strings use the importing file's package-relative resolution.

-

- `links` checks root-confined local Markdown links and GitHub-style heading fragments, including raw HTML `a[href]` in `.md` files. It skips external URLs and unsupported formats; exit 1 reports broken links. Discovery honors `codegraph.config.json` discovery globs plus CLI `--include-glob` / `--ignore-glob` / `--no-gitignore`. `review` and non-empty `impact` include the same `markdownLinks` findings; `unresolved` excludes document edges.

-

- `inspect --duplicates` adds the slower bounded duplicate summary. Treat duplicate matches, candidate tests, and call-compatibility hints as review leads, not proof.

-

- Current-state commands validate the on-disk index automatically and default to the disk cache, so `index` and `sync` only prewarm or repair state and are never prerequisites for a query. `--cache off|memory|disk` stays explicit, `--cache-verify` and `--cache-strict` request stronger checks when reusable cache or manifest state exists, and `--cache-strict` has no effect with `--cache off`. `drift`/`graph-delta` keep revision-range semantics instead. `review` and `impact` diff ranges select what to analyze independently from the complete current-project index, so repeated unchanged ranges reuse a warm manifest without narrowing graph, symbol, candidate-test, or duplicate context.

-

- ## Choose Output by Consumer

-

- - Human or model reading one result: use the human-readable default with no output flag; `review` is already compact.

- - Tool chaining, filtering, stable handles, exact ranges, or schema fields: use `--json`. If `--json` and `--pretty` are both present, `--json` wins. `viewer` and `mcp` reject `--json`/`--pretty` because they do not emit structured command output.

- - Repeated agent queries over one repo snapshot: prefer MCP so the index stays warm. MCP inputs are flat JSON objects and the server root is fixed at startup; send only fields in the mounted tool schema, never CLI flags such as `--root` or `--json`. Unknown tool fields are rejected as invalid parameters. If the first MCP call fails at startup or loses its transport, do not retry the same server; run `codegraph doctor`, use the equivalent CLI command for this session, and restart the agent client after package upgrades.

- - Durable graph handoff: use `codegraph graph --root . ./src --json --output codegraph.json` rather than parsing display text. `graph --json` and `index --json` payloads include an `analysis` object (`mode`, `backend`, `label`, fallback counts); when `mode` is `mixed` or `reduced` the run used regex/graph-only extraction for some or all files, so treat symbol accuracy accordingly. Degraded runs also print a `Backend:` warning on stderr even without `--progress`.

- - Search and inspect performance diagnosis: add `--report` for JSON on stderr or `--report-file <path>` for a file while keeping normal command output unchanged.

- - Index discovery diagnosis: `--report` timing JSON can include `sourceDiscoveryMs`, `metadataDiscoveryMs`, `gitListMs`, `filesystemScanMs`, and `cacheProbeMs` when those steps run. Named `steps` cover discovery (`git-list`, `git-ignore`, `filesystem-scan`, `cache-probe`, `metadata-discovery`), an incremental build's manifest-reuse preamble (`file-identity`, `clear-resolution-caches`, `load-manifest`, `diff-build-options`, `config-hash`), and post-parse persistence (`persist-cache`, `workspace-manifests`, `index-manifest`, `finalize`, `snapshot-write`). `index-manifest` totals its sub-steps `git-head`, `config-hash`, `manifest-transform`, `manifest-write`, and `cache-prune`. Incremental updates include `snapshot-write` when the project snapshot is rewritten.

- - `config-hash` includes config discovery and reads, not just hashing. Its Git sub-steps remain visible as `git-list` and `git-ignore`; do not add them to the parent total.

-

- ### Human Graph Viewer

-

- `viewer` is for a human inspecting a graph, not an agent interface; use graph JSON, SQLite, MCP, or `--json` for structured agent work. Its contract is `codegraph viewer [--root <root>] [--graph <root-confined-json>] [--host <host>] [--port <0-65535>] [--open] [--print-url]`, with the current directory, `127.0.0.1`, and `4173` as the default root, host, and port. Do not pass `--json` to `viewer`.

-

- ```bash

- codegraph viewer --root . --open

- codegraph viewer --root . --graph codegraph-out/graph.json --open

- codegraph viewer --root . --port 4173 --print-url

- ```

-

- `--print-url` is preview-only: it prints the deterministic URL and exits without starting a server, rejects `--open`, and rejects port `0`. Without `--graph`, each load or reload builds the current project graph through the automatically validated disk cache; `init`, `index`, and exported JSON are not prerequisites. An explicit `--graph` is served through the same `/graph.json` route; manual upload remains available, and the viewer loads Sigma, Graphology, and ForceAtlas2 from bundled local vendor assets (no CDN).

-

- Do not parse pretty output to recover fields already available in structured output.

-

- ## Live Reads and Sensitive Files

-

- Use `codegraph file <path>` for current disk content. Readable numbered lines are the default; add `--json` for structured pagination fields.

-

- ```bash

- codegraph file src/auth.ts --offset 201 --limit 200 --max-bytes 80000

- codegraph file src/auth.ts --include-graph-context

- ```

-

- Pagination and byte contracts:

-

- - `--offset` is 1-based.

- - `--limit` defaults to 2000 lines and is capped at 10000.

- - `--max-bytes` defaults to 80000 unnumbered text bytes and is capped at 500000.

- - A separate 16 MiB input limit rejects larger raw reads and structural text-config summaries before unbounded I/O.

- - `content` is exact `number<TAB>line` text; `text` omits line-number prefixes.

- - Follow `page.nextOffset`. Beyond EOF, JSON fields are empty and pretty output reports that no lines remain.

-

- Live bytes and indexed context have different freshness rules:

-

- - Plain file bytes come from disk and do not depend on index freshness.

- - `--include-graph-context` opts into indexed `usedBy` paths, imports, and symbols.

- - An exact project-relative query such as `codegraph explore src/auth.ts --json` adds `fileView` with the same live-read contract as `codegraph file`; `--no-source` suppresses it.

-

- Sensitive-file rules:

-

- - Recognized environment, authentication, and credential text configs return structural summaries by default.

- - Key material defaults to metadata and may report file size without reading raw secret bytes.

- - Use `--allow-sensitive` only for deliberate raw access.

- - `--allow-sensitive` never bypasses input-size, binary, NUL, or UTF-8 guards; `.p12` and `.pfx` remain metadata-only in practice.

-

- ## MCP and Freshness

-

- If MCP tools are available, prefer them over repeated CLI invocations. Use `explore`, `orient`, `workspace_symbols`, `search`, `get_file`, `get_symbol`, `packet_get`, `goto`, `refs`, `rename_preview`, `refactor_plan`, `calls`, `type_hierarchy`, `implementations`, `file_deps`, `path`, `impact`, `review`, `query_sqlite`, `refresh_index`, and `artifact_build`; fall back to the CLI when MCP is unavailable. Legacy `callers`/`callees`, `supertypes`/`subtypes`, and `deps`/`rdeps` names remain valid `tools/call` aliases.

-

- MCP `explore` defaults `includeSource` to `false` because source-bearing packets dominate an agent response; anchors and follow-ups identify the focused source request to make next. This intentionally differs from CLI `explore`, which includes source by default for human-readable output; pass `includeSource: true` to MCP when source is needed.

-

- codegraph uses the official MCP SDK v2 to serve current 2026-07-28 clients while retaining compatibility with 2025-era clients. MCP protocol connections and HTTP protocol sessions keep separate transport state, but all share the server's one warm codegraph analysis session for the configured root.

-

- - `mcp serve` warms the base session cache during startup by default, so a cold discovery-and-build cost lands on server startup rather than the first `tools/call`.

- - Pass `--no-warmup` to start lazily instead, or `--warmup-symbols` to also build the detailed symbol graph before serving.

- - Tool schemas reject unknown fields; each protocol session caps tool concurrency at 4 with a retryable busy error.

- - HTTP request bodies time out after 30 seconds; idle HTTP protocol sessions are evicted with a bounded session count.

- - Cancellation responds to the caller promptly but retains the occupied slot until shared work settles, so abandoned calls cannot bypass that resource bound.

- - Concurrent `refresh_index` calls serialize and honor each request's requested warmup mode.

-

- On the first `tools/call`, codegraph can emit `notifications/message` and, when the request includes `_meta.progressToken`, `notifications/progress` before the final result. Stdio carries them inline, and modern Streamable HTTP clients that accept `text/event-stream` receive them as a stream until the terminal result frame.

- HTTP enforces Host and Origin policies. A missing `Origin` is accepted for non-browser clients; unapproved, malformed, and opaque origins are rejected. This is not authentication: binding `--host` to a non-loopback address exposes an unauthenticated endpoint intended only for trusted networks or containers.

- For a reusable local HTTP server, run `codegraph server start --root .`, inspect it with `codegraph server status --root . --json`, and shut it down with `codegraph server stop --root .`. The lifecycle wrapper serializes project changes and writes `.codegraph/server.json` only after a challenged `/health` response proves the root, process, and startup time; its secret remains in the per-user Codegraph state directory, outside the project and separate from package files and compiler cache data. It defaults to `127.0.0.1:7331`, accepts `--startup-timeout-ms <1-86400000>` for warmups longer than 15 seconds, and writes startup diagnostics to `.codegraph/server.log`; add `--json` for `status: "started"`, registry fields, and update state.

- For stdio lifecycle control, pass `--idle-timeout-ms <milliseconds>`; `0` disables the timer and the option is rejected with HTTP `--port` transport.

-

- Use `refactor_plan` with flat `handle`, optional `renameTo`, independent optional `maxReferences`, `maxCallers`, and `maxHierarchy` bounds from 0 to 500, and optional `includeSource`. It reuses the configured server root and one session snapshot, returns portable targets and structured tool-call follow-ups even for exact internal review handles, exposes unsupported implementation sections in `sectionIssues`, preserves nested `rename.safe`, and never writes.

- Use `workspace_symbols` for deterministic symbol identities and exact ranges; use `search` when paths, prose, SQL, snippets, or graph evidence should participate.

- Use `type_hierarchy` with `direction: "supertypes" | "subtypes"` and `implementations` with portable symbol handles for repeated hierarchy queries; schemas are flat and use the same 10-depth and 500-result caps as the CLI.

- `refs` and `file_deps` collection limits default to 25 and cap at 500. `query_sqlite` row limits default to 100 and cap at 500 (`src/sqlite/rowBounds.ts`); its 10-second deadline can reject a long-running query, and concurrent calls can temporarily fail while an expired native step completes its bounded cleanup.

-

- Use `calls` with `direction: "callers" | "callees"` and portable callable handles for repeated call hierarchy queries. The flat schema accepts `handle`, `direction`, `depth`, `limit`, and `includeHeuristic`, reuses the MCP freshness gate, and caps depth at 5 and symbols at 500; current results remain semantic-only.

- Use `file_deps` with `direction: "deps" | "rdeps"` for file-level dependency queries. Its `file` field accepts an exact `file::symbol` path or portable `symbol:` handle and resolves either to the declaring file; use `calls` for symbol-level relationships. `refs` and `file_deps` pair their collections with `limit`, `totalSeen`, `truncated`, and `omitted`; when `truncated` is true the result is a capped prefix, so rerun with a higher `limit` instead of treating it as complete. MCP `review` is bounded for transport: collections are capped at the response's `limits` with exact `omittedCounts`, while `summary` totals always describe the full report.

- Use `rename_preview` with `handle`, `newName`, optional boolean inclusion fields, and optional `maxEdits`. It remains available in read-only mode, reuses the MCP session, never changes files, and has no apply counterpart.

- Keep live and indexed evidence distinct:

- - `get_file` returns bounded live bytes with `offset`, `limit`, and `maxBytes`; continue at `page.nextOffset`.

- - Set `allowSensitive: true` only for intentional sensitive reads.

- - Set `includeGraphContext: true` only when freshness-backed context is needed; importers, imports, and symbols are each capped at 100.

- - Plain `get_file` freshness does not gate live bytes.

- - After indexed calls, check `freshness` before trusting graph or semantic context. `refreshed` means codegraph rebuilt; `stale` includes a reason and bounded changed-file metadata.

- - Run `refresh_index` before `artifact_build` when the index is stale. Artifact writes refuse stale snapshots.

- - After an install or codegraph update, restart or reload the owning MCP client. `codegraph doctor --json` diagnoses package/native version identity; `refresh_index` refreshes repository state only and does not reload MCP code or tools.

- ## Agent Setup and Project Lifecycle

- Run the guided installer interactively to detect clients, preview exact actions, and confirm once. Use `--all` to configure the complete current catalog without detection:

- ```bash

- codegraph install

- codegraph install --target codex,claude --dry-run

- codegraph install --print-config codex

- codegraph install --target codex,claude --yes

- codegraph install --target codex --yes --force

- codegraph install --all --dry-run

- codegraph install --all --yes

- codegraph uninstall --target codex --yes

- ```

- Use `codegraph version` to inspect package identity and `codegraph skill doctor` to inspect bundled skill targets.

- Interactive confirmation accepts only `y` or `yes` and defaults to no. Noninteractive writes require `--yes`. `--all` is install-only, configures `codex`, `claude`, `cursor`, `gemini`, `opencode`, `omp`, `kilo`, and `agents`, and cannot be combined with target selection, `--detect`, or `--print-config`.

- Compatible JSON MCP entries and equivalent unmarked Codex tables are preserved byte-for-byte. Kilo JSONC comments and unrelated settings remain intact. Divergent codegraph entries are collision-reported without exposing configuration values.

- The installer manages codegraph-owned MCP entries, skill payloads, and marker files; uninstall removes only recognized codegraph-owned content. Existing user-owned `SKILL.md` files are preserved unless an ownership marker and known payload match, or `--force` is passed.

- Lifecycle commands manage `.codegraph/manifest.json`; shared server commands separately manage `.codegraph/server.json` and `.codegraph/server.log`, and other commands do not require the manifest:

- codegraph init --root .

- codegraph status --root . --json

- codegraph sync --root .

- codegraph uninit --root .

- # Opt out only when initializing

- codegraph init --root . --no-update-gitignore

- codegraph sync --root . --init --no-update-gitignore

- `init` and `sync --init` use Git's effective ignore semantics before lifecycle hashing. When the untracked manifest is not already ignored, they append exactly `.codegraph/` to the resolved root's `.gitignore`; effective parent/global/info excludes are honored, tracked manifests are left unchanged with a warning, and non-Git roots are not modified.

-

- Use `--no-update-gitignore` to opt out during `init` or `sync --init`; ordinary `sync` never updates ignore policy. `uninit` preserves `.codegraph/server.json`, `.codegraph/server.log`, and `.codegraph/cache/` even with `--force`, so stop a shared server explicitly; it leaves the root rule, while `init` and `sync` may warm or update `.codegraph/cache/index-v1/`. An existing `.codegraph-cache/` directory migrates automatically on the next run.

-

- Lifecycle commands accept either one positional project path or `--root <path>`, never both. Automatic ignore updates are bound to that same resolved project root.

- ## Installation

- For normal CLI and MCP use, install from public npm with Node.js 22.16 or newer. Disk cache uses Node's standard-library `node:sqlite` module; builds below 22.16 may load it without the statement APIs Codegraph needs and then disable disk cache after one warning.

- ```bash

- npm install -g @lzehrung/codegraph

- codegraph doctor

- codegraph install --all --dry-run

- codegraph install --all --yes

- ```

- Public npm installs need no GitHub token or `@lzehrung` registry mapping. Do not suggest the unscoped `codegraph` package. If `.npmrc` still maps `@lzehrung` to `https://npm.pkg.github.com`, remove or replace that legacy mapping; npm otherwise selects GitHub Packages instead of current public releases.

- Published installs resolve the optional native runtime when a compatible artifact exists; otherwise codegraph reports reduced graph-only and regex recovery behavior rather than semantic parity.

- For library or API consumers, use only the scoped packages:

- - slim library install: `@lzehrung/codegraph-core`

- - agent-shaped APIs: `@lzehrung/codegraph/agent` or `@lzehrung/codegraph-core/agent`

- - MCP handlers/server: `@lzehrung/codegraph/mcp`

- - optional native runtime: `@lzehrung/codegraph-native`

- No Node.js or npm? The preview standalone archive is self-contained: it bundles Node.js, production dependencies, the matching native runtime, and the codegraph skill.

- ```powershell

- irm https://github.com/lzehrung/codegraph/releases/latest/download/install.ps1 | iex

- ```

- ```bash

- curl -fsSL https://github.com/lzehrung/codegraph/releases/latest/download/install.sh | sh

- ```

- The standalone Linux archives require glibc. On musl Linux, use the package or source installation path instead. The bootstrap previews its target and paths, then confirms interactively or requires `-Yes`/`--yes` for noninteractive writes. It verifies the selected archive against release `SHA256SUMS`, rejects unsafe entries, installs under a versioned user-owned root, and records the prior version; pin or roll back with `./install.ps1 -Version VERSION` or `sh ./install.sh --version VERSION`. This channel is checksummed preview content, not a signed release claim.

- On Windows, installed releases load native code from `%LOCALAPPDATA%\codegraph\native-cache\v1`. The first upgrade from an older direct-loading release requires closing codegraph MCP clients once, running `npm install -g @lzehrung/codegraph@latest`, and restarting the clients.

- Use `codegraph doctor` to inspect `native.origin`, cache fallback errors, stale `.codegraph-*` npm retirement siblings, and installed-versus-running version drift. Do not delete reported paths or kill Node/IDE processes automatically; restart the owning client explicitly, and only clean obsolete cache entries after every process using them has stopped.