# CLI, Installer & Agent Targets

> The command surface a new reader should try first: interactive install, project init, indexing, sync, status, query, context, serve, affected tests, and portable agent config writers for Claude Code, Cursor, Codex CLI, and opencode.

- Repository: colbymchenry/codegraph
- GitHub: https://github.com/colbymchenry/codegraph
- Human wiki: https://grok-wiki.com/public/wiki/colbymchenry-codegraph-89e8b2c4d43a
- Complete Markdown: https://grok-wiki.com/public/wiki/colbymchenry-codegraph-89e8b2c4d43a/llms-full.txt

## Source Files

- `src/bin/codegraph.ts`
- `src/bin/node-version-check.ts`
- `src/installer/index.ts`
- `src/installer/targets/registry.ts`
- `src/installer/targets/types.ts`
- `src/installer/targets/claude.ts`
- `src/installer/targets/codex.ts`
- `__tests__/installer-targets.test.ts`

---

<details>
<summary>Relevant source files</summary>
The following files were used as context for generating this wiki page:
- [src/bin/codegraph.ts](src/bin/codegraph.ts)
- [src/bin/node-version-check.ts](src/bin/node-version-check.ts)
- [src/installer/index.ts](src/installer/index.ts)
- [src/installer/targets/registry.ts](src/installer/targets/registry.ts)
- [src/installer/targets/types.ts](src/installer/targets/types.ts)
- [src/installer/targets/claude.ts](src/installer/targets/claude.ts)
- [src/installer/targets/cursor.ts](src/installer/targets/cursor.ts)
- [src/installer/targets/codex.ts](src/installer/targets/codex.ts)
- [src/installer/targets/opencode.ts](src/installer/targets/opencode.ts)
- [src/installer/targets/shared.ts](src/installer/targets/shared.ts)
- [src/installer/targets/toml.ts](src/installer/targets/toml.ts)
- [src/installer/instructions-template.ts](src/installer/instructions-template.ts)
- [src/sync/watch-policy.ts](src/sync/watch-policy.ts)
- [src/sync/git-hooks.ts](src/sync/git-hooks.ts)
- [src/mcp/index.ts](src/mcp/index.ts)
- [__tests__/installer-targets.test.ts](__tests__/installer-targets.test.ts)
- [README.md](README.md)
- [package.json](package.json)
</details>

# CLI, Installer & Agent Targets

This page orients a new contributor around CodeGraph's command surface: the `codegraph` binary, its first-use installer path, project initialization, indexing and sync commands, query/context commands, MCP serving, affected-test lookup, and the portable agent config writers for Claude Code, Cursor, Codex CLI, and opencode.

The implementation is intentionally local and provider-neutral. The installer writes ordinary config and instruction files for several agents, while the runtime server is launched as `codegraph serve --mcp`; no page claim here depends on a hosted model provider or proprietary connector. The selected wiki profile was used as bundled page-shaping guidance only; no local `STRATEGY.md` or `docs/solutions/**` sources were present in this checkout during inspection.

## First Commands To Try

For a fresh reader, the shortest useful path is:

```bash
npx @colbymchenry/codegraph
cd your-project
codegraph init -i
codegraph status
codegraph query "SomeSymbol"
codegraph context "understand this feature"
codegraph serve --mcp
```

The published package exposes the `codegraph` binary from `dist/bin/codegraph.js`, and the source CLI explicitly runs the interactive installer when invoked with no arguments. The README mirrors that flow: run `npx @colbymchenry/codegraph`, then initialize a project with `codegraph init -i`.

Sources: [package.json:7-9](), [src/bin/codegraph.ts:67-78](), [README.md:24-37]()

## Command Surface Map

| Command | First-use purpose | Important options |
|---|---|---|
| `codegraph` | Runs interactive installer when no args are supplied. | None. |
| `codegraph install` | Configures one or more agent targets. | `--target`, `--location`, `--yes`, `--no-permissions`, `--print-config`. |
| `codegraph init [path]` | Creates `.codegraph/`; optionally indexes immediately. | `--index`, `--verbose`. |
| `codegraph index [path]` | Full indexing pass. | `--force`, `--quiet`, `--verbose`. |
| `codegraph sync [path]` | Incremental update since last index. | `--quiet`. |
| `codegraph status [path]` | Shows index stats, backend, and pending changes. | `--json`. |
| `codegraph query <search>` | Searches symbols. | `--path`, `--limit`, `--kind`, `--json`. |
| `codegraph files` | Shows indexed file structure. | `--filter`, `--pattern`, `--format`, `--max-depth`, `--no-metadata`, `--json`. |
| `codegraph context <task>` | Builds markdown or JSON task context. | `--path`, `--max-nodes`, `--max-code`, `--no-code`, `--format`. |
| `codegraph serve --mcp` | Starts the MCP stdio server for agents. | `--path`, `--mcp`, `--no-watch`. |
| `codegraph affected [files...]` | Finds tests affected by changed files. | `--stdin`, `--depth`, `--filter`, `--json`, `--quiet`. |

The README has the high-level command reference, while the Commander definitions in `src/bin/codegraph.ts` are the source of truth for options and behavior.

Sources: [README.md:314-329](), [src/bin/codegraph.ts:394-399](), [src/bin/codegraph.ts:536-542](), [src/bin/codegraph.ts:605-609](), [src/bin/codegraph.ts:667-671](), [src/bin/codegraph.ts:786-793](), [src/bin/codegraph.ts:849-858](), [src/bin/codegraph.ts:1055-1063](), [src/bin/codegraph.ts:1101-1107](), [src/bin/codegraph.ts:1195-1204](), [src/bin/codegraph.ts:1326-1334]()

## CLI Bootstrap And Node Guardrails

`src/bin/codegraph.ts` keeps startup light by lazy-loading heavy CodeGraph modules and the installer. Before any tree-sitter or WASM-heavy work, it blocks Node.js major versions 25 and newer unless `CODEGRAPH_ALLOW_UNSAFE_NODE=1` is set. The banner text lives in a side-effect-free helper so tests can import it without bootstrapping the CLI.

```ts
// src/bin/codegraph.ts
const nodeVersion = process.versions.node;
const nodeMajor = parseInt(nodeVersion.split('.')[0] ?? '0', 10);
if (nodeMajor >= 25) {
  process.stderr.write(buildNode25BlockBanner(nodeVersion) + '\n');
  if (!process.env.CODEGRAPH_ALLOW_UNSAFE_NODE) {
    process.exit(1);
  }
}
```

The package also declares supported Node engines as `>=20.0.0 <25.0.0`.

Sources: [src/bin/codegraph.ts:30-65](), [src/bin/node-version-check.ts:1-20](), [src/bin/node-version-check.ts:20-39](), [package.json:56-58]()

## Project Lifecycle Commands

### `init`, `index`, and `sync`

`codegraph init [path]` resolves the target path, creates a CodeGraph project with `CodeGraph.init(projectPath, { index: false })`, and then optionally calls `indexAll()` when `--index` is set. If the project is already initialized, rerunning `init` is still useful: it attempts to wire project-local agent surfaces for globally configured agents and offers the watch fallback.

`codegraph index [path]` opens an initialized project and performs a full `indexAll()` pass. `--force` clears the existing index first, `--quiet` suppresses UI, and `--verbose` uses timestamped progress instead of the shimmer progress renderer. `codegraph sync [path]` opens the same project and calls `cg.sync()`, reporting added, modified, removed, and node update counts.

Sources: [src/bin/codegraph.ts:394-464](), [src/bin/codegraph.ts:536-588](), [src/bin/codegraph.ts:605-651]()

### `status`, `query`, `files`, and `context`

`status` is the health check. In JSON mode it returns initialization state, project path, file/node/edge counts, database size, backend, languages, and pending change counts. In human mode it also prints node and language breakdowns and tells the user to run `codegraph sync` when pending changes exist.

`query` searches indexed symbols via `cg.searchNodes(search, { limit, kinds })`. `files` reads `cg.getFiles()` and can render a tree, flat list, grouped-by-language output, or JSON. `context` calls `cg.buildContext(task, ...)` and prints the returned markdown or JSON.

Sources: [src/bin/codegraph.ts:667-710](), [src/bin/codegraph.ts:715-773](), [src/bin/codegraph.ts:786-812](), [src/bin/codegraph.ts:849-958](), [src/bin/codegraph.ts:1055-1089]()

## MCP Serve And Freshness

`codegraph serve` without `--mcp` prints a sample MCP config and the available tools to stderr. `codegraph serve --mcp` starts `MCPServer`, optionally bound to `--path`; without a path, the MCP server can initialize from client roots. `--no-watch` sets `CODEGRAPH_NO_WATCH=1` before server startup.

Freshness has two paths. The MCP server normally starts file watching and reports auto-sync activity to stderr. If watching is disabled by policy, it explains why and tells the user to run `codegraph sync` or install git sync hooks. The watch policy disables watching when `CODEGRAPH_NO_WATCH=1`, allows `CODEGRAPH_FORCE_WATCH=1` to override auto-detection, and disables WSL2 `/mnt/*` projects because recursive watching is too slow there.

Sources: [src/bin/codegraph.ts:1101-1148](), [src/mcp/index.ts:240-270](), [src/sync/watch-policy.ts:71-98]()

## Affected Test Discovery

`codegraph affected [files...]` accepts file arguments or newline-delimited stdin. It includes changed files that already match test patterns, then performs a breadth-first traversal through `cg.getFileDependents()` up to `--depth` and keeps dependents that look like tests. The default test patterns include `.spec.`, `.test.`, `__tests__`, `tests`, `e2e`, and `spec`; `--filter` replaces that with a custom glob-derived regex.

This command is designed for local hooks or CI glue:

```bash
git diff --name-only | codegraph affected --stdin --quiet
codegraph affected src/auth.ts --filter "e2e/*" --json
```

Sources: [src/bin/codegraph.ts:1185-1204](), [src/bin/codegraph.ts:1213-1256](), [src/bin/codegraph.ts:1258-1303](), [README.md:331-357]()

## Installer Flow

The installer has two entry points: `runInstaller()` for the interactive path and `runInstallerWithOptions()` for CLI flags such as `--target`, `--location`, and `--yes`. Its flow is:

1. Resolve target agents first.
2. Optionally install the npm package globally so agents can run `codegraph`.
3. Choose global vs local config location.
4. Ask about Claude auto-allow permissions only when Claude is selected.
5. Run each target's `install(location, { autoAllow })`.
6. For local installs, initialize and index the current project.
7. For global installs, print `cd your-project` and `codegraph init -i` as the quick start.

Sources: [src/installer/index.ts:64-87](), [src/installer/index.ts:87-130](), [src/installer/index.ts:132-217]()

### Target Selection

The target registry is deliberately small and explicit. Adding a new agent means implementing `AgentTarget` in `targets/<id>.ts` and adding it to `ALL_TARGETS`. The current target order is Claude Code, Cursor, Codex CLI, then opencode; that order controls the multiselect prompt, `--target=all`, and print-config help.

`--target` accepts `auto`, `all`, `none`, or a comma-separated list. `auto` returns detected installed targets, falling back to Claude if none are detected.

Sources: [src/installer/targets/registry.ts:1-21](), [src/installer/targets/registry.ts:23-45](), [src/installer/targets/registry.ts:47-83](), [src/installer/index.ts:261-309]()

## Agent Target Contract

Every target implements the same portable contract: support checks, detection, install, uninstall, manual config printing, path description, and optional project-surface wiring. That keeps the installer BYOC/BYOK friendly: CodeGraph does not assume one model vendor or agent; each agent adapter owns only its local file format and filesystem paths.

```ts
// src/installer/targets/types.ts
export interface AgentTarget {
  readonly id: TargetId;
  readonly displayName: string;
  supportsLocation(loc: Location): boolean;
  detect(loc: Location): DetectionResult;
  install(loc: Location, opts: InstallOptions): WriteResult;
  uninstall(loc: Location): WriteResult;
  printConfig(loc: Location): string;
  describePaths(loc: Location): string[];
  wireProjectSurfaces?(): WriteResult;
}
```

Sources: [src/installer/targets/types.ts:1-13](), [src/installer/targets/types.ts:15-23](), [src/installer/targets/types.ts:73-120]()

## Target Matrix

| Target | Global files | Local files | Config shape | Permissions |
|---|---|---|---|---|
| Claude Code | `~/.claude.json`, `~/.claude/settings.json`, `~/.claude/CLAUDE.md` | `./.mcp.json`, `./.claude/settings.json`, `./.claude/CLAUDE.md` | JSON `mcpServers.codegraph` | Claude auto-allow list when enabled |
| Cursor | `~/.cursor/mcp.json` | `./.cursor/mcp.json`, `./.cursor/rules/codegraph.mdc` | JSON `mcpServers.codegraph`, with extra `--path` | None |
| Codex CLI | `~/.codex/config.toml`, `~/.codex/AGENTS.md` | Not supported | TOML `[mcp_servers.codegraph]` | None |
| opencode | XDG or Windows config dir `opencode.jsonc`/`.json`, plus `AGENTS.md` | `./opencode.jsonc`/`.json`, `./AGENTS.md` | JSONC `mcp.codegraph` with `enabled: true` | None |

All JSON-shaped targets share the base server command shape where applicable: `type: 'stdio'`, `command: 'codegraph'`, and `args: ['serve', '--mcp']`. Codex serializes the same command into a narrow TOML block. opencode uses a different wrapper where `command` is an array and `enabled` is explicit.

Sources: [src/installer/targets/claude.ts:1-18](), [src/installer/targets/cursor.ts:1-31](), [src/installer/targets/codex.ts:1-15](), [src/installer/targets/opencode.ts:1-27](), [src/installer/targets/shared.ts:14-25](), [src/installer/targets/toml.ts:1-20]()

### Claude Code Details

Claude supports both global and local locations. Global MCP config is written to `~/.claude.json`; local MCP config is written to `./.mcp.json`, because the source notes that Claude Code does not read project-level `./.claude.json`. The target also migrates stale local `./.claude.json` CodeGraph entries during install and uninstall.

When auto-allow is enabled, Claude receives permissions for CodeGraph MCP tools in `settings.json`. Instructions are inserted into `CLAUDE.md` through marker-delimited replacement.

Sources: [src/installer/targets/claude.ts:46-74](), [src/installer/targets/claude.ts:85-120](), [src/installer/targets/claude.ts:197-241](), [src/installer/targets/claude.ts:244-308](), [src/installer/targets/shared.ts:27-42]()

### Cursor Details

Cursor supports both global and local MCP configs, but its instruction/rules surface is project-local only. A global Cursor install writes `~/.cursor/mcp.json`; a local install writes `./.cursor/mcp.json` and `./.cursor/rules/codegraph.mdc`.

Cursor also gets special `--path` handling. Local installs use the current absolute path; global installs use `${workspaceFolder}` so a single global config can still resolve each opened workspace correctly.

Sources: [src/installer/targets/cursor.ts:59-71](), [src/installer/targets/cursor.ts:87-123](), [src/installer/targets/cursor.ts:151-185](), [src/installer/targets/cursor.ts:187-238]()

### Codex CLI Details

Codex CLI is global-only in this implementation. It writes `[mcp_servers.codegraph]` into `~/.codex/config.toml` and writes shared CodeGraph instructions into `~/.codex/AGENTS.md`. The TOML helper is intentionally not a general TOML parser; it splices one dotted-key table while preserving the rest of the file.

Sources: [src/installer/targets/codex.ts:40-59](), [src/installer/targets/codex.ts:61-90](), [src/installer/targets/codex.ts:121-180](), [src/installer/targets/toml.ts:56-121]()

### opencode Details

opencode supports global and local locations. On global installs, it uses `%APPDATA%/opencode` on Windows or `$XDG_CONFIG_HOME/opencode` / `~/.config/opencode` elsewhere. It prefers an existing `opencode.jsonc`, falls back to an existing `opencode.json`, and defaults new installs to `.jsonc`.

The target uses `jsonc-parser` edits so comments survive reinstall and uninstall. It writes the MCP entry under `mcp.codegraph` and uses `AGENTS.md` for shared instructions.

Sources: [src/installer/targets/opencode.ts:52-82](), [src/installer/targets/opencode.ts:99-132](), [src/installer/targets/opencode.ts:173-224](), [src/installer/targets/opencode.ts:226-242]()

## Shared Instructions And Idempotency

All agent instruction files receive the same marker-delimited block from `instructions-template.ts`. The block tells agents when to prefer CodeGraph tools over native search and includes a tool-choice table for `codegraph_search`, `codegraph_context`, callers/callees, impact, node, explore, files, and status.

The shared writer utilities are conservative: JSON parse failures are backed up before overwrite, writes are atomic, JSON equality avoids unnecessary rewrites, and markdown sections are replaced only between CodeGraph markers. The installer-target tests enforce the expected contract: install writes files, reinstall is idempotent, sibling MCP servers are preserved, uninstall reverses install, and `printConfig` does not write files.

Sources: [src/installer/instructions-template.ts:1-23](), [src/installer/instructions-template.ts:23-56](), [src/installer/targets/shared.ts:44-95](), [src/installer/targets/shared.ts:97-167](), [__tests__/installer-targets.test.ts:1-15](), [__tests__/installer-targets.test.ts:65-145]()

## Project-Local Surfaces After Global Install

A global MCP config is not always enough. Cursor's rule file is project-scoped, so `codegraph init` calls `wireProjectSurfacesForGlobalAgents()` to let any globally configured target write project-local support files. Today, Cursor is the notable target with a `wireProjectSurfaces()` implementation.

This is the key workflow detail for new maintainers: `codegraph install --location=global` configures the agent globally, and `codegraph init -i` in each project builds the graph and repairs any target-specific local surfaces needed for that project.

Sources: [src/installer/index.ts:219-249](), [src/bin/codegraph.ts:405-421](), [src/bin/codegraph.ts:430-442](), [src/installer/targets/types.ts:106-120](), [src/installer/targets/cursor.ts:163-171]()

## Watch Fallback And Git Hooks

After initialization, CodeGraph may offer a fallback when the live watcher is disabled. If the project is not a git repo, it tells the user to run `codegraph sync` manually after changes. If the repo is git-backed and hooks are not already installed, it can install sync hooks for commit, pull, and checkout workflows. Hook installation strips and re-appends only CodeGraph's marked block, preserving user hook content.

Sources: [src/installer/index.ts:365-433](), [src/sync/git-hooks.ts:121-159](), [src/sync/git-hooks.ts:161-208]()

## Manual Config Printing

`codegraph install --print-config <id>` is the no-write escape hatch. It resolves the target id, chooses global unless `--location=local` is provided, then prints that target's config snippet and returns without invoking the installer. Tests assert that `printConfig` returns non-empty output without creating files.

This supports portable setup docs, locked-down environments, and BYOC/BYOK workflows where users want to review or paste config manually rather than letting the installer write files.

Sources: [src/bin/codegraph.ts:1326-1352](), [src/installer/targets/types.ts:98-105](), [__tests__/installer-targets.test.ts:135-141]()

## Maintainer Checklist

When changing this area, verify the behavior at three layers:

| Change area | Files to inspect | Tests or checks to update |
|---|---|---|
| Add a CLI command or option | `src/bin/codegraph.ts`, README CLI reference | Command behavior and README examples |
| Add an agent target | `src/installer/targets/types.ts`, new `targets/<id>.ts`, `registry.ts` | Contract tests in `__tests__/installer-targets.test.ts` |
| Change shared MCP command shape | `src/installer/targets/shared.ts`, target-specific overrides | Target tests and manual snippets |
| Change Codex TOML handling | `src/installer/targets/codex.ts`, `src/installer/targets/toml.ts` | TOML serializer tests |
| Change install flow | `src/installer/index.ts` | Target resolution, local/global behavior, watch fallback |
| Change freshness behavior | `src/bin/codegraph.ts`, `src/mcp/index.ts`, `src/sync/**` | Watch policy and git hook behavior |

Sources: [src/installer/targets/registry.ts:1-8](), [src/installer/targets/types.ts:73-120](), [__tests__/installer-targets.test.ts:438-457](), [__tests__/installer-targets.test.ts:459-549]()

## Summary

The CLI is the user-facing shell around a local CodeGraph index and MCP server. The installer is the portability layer: one orchestrator, one target registry, and small target adapters that write each agent's native config format while preserving user-owned content. For a first 30 minutes in the repo, read `src/bin/codegraph.ts` for commands, `src/installer/index.ts` for install flow, `src/installer/targets/types.ts` plus `registry.ts` for the adapter contract, and the four target files for agent-specific config behavior.

Sources: [src/bin/codegraph.ts:126-129](), [src/installer/index.ts:1-12](), [src/installer/targets/types.ts:1-13](), [src/installer/targets/registry.ts:16-21]()