P0: add agent installer workflow

README.md

@@ -318,7 +318,18 @@ codegraph graph --root . ./src --dot --output graph.dot
 
 ## Agent setup
 
-Using a skill-aware agent? Install the bundled skill so repo navigation, semantic references, dependency tracing, and PR impact questions route to Codegraph automatically. The installer uses safe per-agent defaults and creates the target skills directory as needed:
+Using a local agent client? The top-level installer configures Codegraph-owned MCP entries and marker files for supported clients, while preserving existing user config:
+
+```bash
+codegraph install --target codex,claude --dry-run
+codegraph install --target codex,claude --yes
+codegraph install --print-config codex
+codegraph uninstall --target codex --yes
+```
+
+Supported installer targets are `codex`, `claude`, `cursor`, `gemini`, `opencode`, and `agents`. Writes require `--yes`; `--dry-run` previews files, and `uninstall` removes only Codegraph-owned marker blocks, marker files, or MCP entries whose command is `codegraph`.
+
+Using a skill-aware agent only? Install the bundled skill directly so repo navigation, semantic references, dependency tracing, and PR impact questions route to Codegraph automatically:
 
 ```bash
 # Codex CLI: ${CODEX_HOME:-~/.codex}/skills/codegraph
@@ -340,7 +351,7 @@ codegraph skill install --agent gemini
 codegraph skill install --agent opencode
 ```
 
-For a custom location, use `codegraph skill install --target <path>/skills/codegraph`; the target must end with `skills/codegraph`, and the installer creates the directory as needed. Cursor CLI now supports native skills directories too, so `.cursor/skills/codegraph` works alongside the universal `~/.agents/skills/codegraph` location. To inspect the packaged skill paths and target health, run `codegraph skill doctor`.
+For a custom skill location, use `codegraph skill install --target <path>/skills/codegraph`; the target must end with `skills/codegraph`, and the installer creates the directory as needed. Cursor CLI supports native skills directories too, so `.cursor/skills/codegraph` works alongside the universal `~/.agents/skills/codegraph` location. To inspect the packaged skill paths and target health, run `codegraph skill doctor`.
 
 ## Using as a library
 

codegraph-skill/codegraph/SKILL.md

@@ -42,9 +42,11 @@ Then choose the smallest useful follow-up:
 - impact: `codegraph impact --base HEAD --head WORKTREE --pretty`
 - review: `codegraph review --base HEAD --head WORKTREE --summary`
 - drift: `codegraph drift ./src --base origin/main --head HEAD --pretty --graph-edges summary --public-api removals`
+- installer: `codegraph install --target codex,claude --dry-run`
 
 Use `--root` to define the project boundary for config lookup, cache scope, path confinement, and output normalization.
 For `orient`, `drift`, and positional graph commands, positional paths are include roots inside that project.
+Use `codegraph install --target <ids> --yes` to configure supported local agent clients. Use `--dry-run` or `--print-config <target>` first; uninstall removes only Codegraph-owned marker blocks, marker files, or MCP entries whose command is `codegraph`.
 
 ## Output Choice
 

docs/agent-workflows.md

@@ -99,6 +99,18 @@ codegraph drift ./src --base origin/main --head HEAD --compact-json
 
 Drift compares structural signals over time: dependency cycles, hotspots, unresolved imports, API surface changes, duplicate group counts, and graph edges. It is review and CI evidence, not runtime validation or compiler diagnostics. Use compact JSON for CI or agent handoff, and use graph-edge/API filters to keep human review output bounded.
 
+## Agent client installer
+
+Use `install` when setting up Codegraph for supported local agent clients:
+
+```bash
+codegraph install --target codex,claude --dry-run
+codegraph install --target codex,claude --yes
+codegraph uninstall --target codex --yes
+```
+
+Writes require `--yes`, and `--print-config <target>` prints the MCP snippet without touching disk. `uninstall` removes only Codegraph-owned marker blocks, marker files, or MCP entries whose command is `codegraph`.
+
 ## MCP server
 
 Use `codegraph mcp serve --root . --stdio` when an agent can spawn and own a stdio MCP subprocess.

docs/cli.md

@@ -157,6 +157,12 @@ codegraph mcp serve --root . --stdio --allow-build
 codegraph mcp serve --root . --port 7331
 codegraph mcp serve --root . --stdio --warmup
 codegraph mcp serve --root . --port 7331 --warmup-symbols
+
+# Install or preview agent client integration
+codegraph install --target codex,claude --dry-run
+codegraph install --target codex,claude --yes
+codegraph install --print-config codex
+codegraph uninstall --target codex --yes
 codegraph mcp --help
 
 # Chunk a file for LLM processing
@@ -264,6 +270,13 @@ For SQL, prefer handles or schema-qualified names when basenames may be ambiguou
 - Use `--force` to replace recognizable stale Codegraph artifacts while preserving unrelated files.
 - Artifact contents exclude their own output directory and linked outside-root files.
 
+#### Agent client installer
+
+- `install` configures Codegraph-owned MCP entries and marker files for supported local agent clients: `codex`, `claude`, `cursor`, `gemini`, `opencode`, and `agents`.
+- Writes require `--yes`; use `--dry-run` to preview exact file changes or `--print-config <target>` to print a copyable MCP snippet without writing.
+- `uninstall` removes only Codegraph-owned marker blocks, marker files, or MCP entries whose command is `codegraph`.
+- `skill install` remains the lower-level primitive for copying the bundled skill directly.
+
 #### MCP server
 
 - `mcp serve` exposes explore, navigation, search, impact, review, SQLite query, session refresh, and artifact-build tools.

docs/installation.md

@@ -86,6 +86,19 @@ Explicit CLI, library, and tool `native` options take precedence over `CODEGRAPH
 
 Reduced mode preserves graph-only and regex-backed recovery where available; it does not provide a non-native Tree-sitter parser.
 
+## Agent client setup
+
+After installing the CLI, `codegraph install` can configure Codegraph-owned MCP entries and skill marker files for supported agent clients:
+
+```bash
+codegraph install --target codex,claude --dry-run
+codegraph install --target codex,claude --yes
+codegraph install --print-config codex
+```
+
+Supported targets are `codex`, `claude`, `cursor`, `gemini`, `opencode`, and `agents`. Writes require `--yes`; `--dry-run` reports the files that would change, and `uninstall` removes only Codegraph-owned marker blocks, marker files, or MCP entries whose command is `codegraph`.
+The lower-level `codegraph skill install --agent <name>` command remains available when you only want to copy the bundled skill.
+
 ## Next steps
 
 - For CLI commands and examples, see [docs/cli.md](./cli.md).

docs/mcp.md

@@ -63,6 +63,18 @@ Tool schemas are flat JSON objects for broad client compatibility; argument comb
 - `query_sqlite` rejects mutating SQL, recursive queries, synthetic payload functions, and stale artifact queries it cannot refresh safely.
 - SQLite responses are row- and byte-bounded.
 
+## Installer
+
+Use `codegraph install` to configure supported local clients without manually editing MCP config files:
+
+```bash
+codegraph install --target codex,claude --dry-run
+codegraph install --target codex,claude --yes
+codegraph install --print-config codex
+```
+
+The installer writes only Codegraph-owned marker blocks, marker files, or `codegraph` MCP entries. `codegraph uninstall --target <ids> --yes` removes only those owned entries.
+
 ## Client Configuration Examples
 
 Use `command: "codegraph"` when the CLI is on `PATH`. Use the full executable path when the client runs with a narrower environment.

src/cli.ts

@@ -37,6 +37,7 @@ import { handleGraphQueryCommand } from "./cli/graphQueries.js";
 import { handleGrepCommand } from "./cli/grep.js";
 import { CLI_HELP_TEXT, helpTextForCommand, isKnownCliCommand } from "./cli/help.js";
 import { handleImpactCommand } from "./cli/impact.js";
+import { handleInstallerCommand } from "./cli/install.js";
 import { handleIndexCommand } from "./cli/index.js";
 import { handleHotspotsCommand, handleInspectCommand } from "./cli/inspect.js";
 import { handleOrientCommand } from "./cli/orient.js";
@@ -285,6 +286,20 @@ async function runCliWithActiveRuntime(rawArgs: string[]) {
     return;
   }
 
+  if (cmd === "install" || cmd === "uninstall") {
+    await handleInstallerCommand({
+      command: cmd,
+      positionals: parsed.positionals,
+      getOpt,
+      hasFlag,
+      writeJSONLine,
+      writeStdoutLine,
+      writeStderrLine,
+      exit: exitCli,
+    });
+    return;
+  }
+
   if (cmd === "sql") {
     const { handleSqlCommand } = await import("./cli/sql.js");
     await handleSqlCommand({

src/cli/help.ts

@@ -31,6 +31,8 @@ Commands:
   sql           Query a SQLite graph export read-only
   chunk         Chunk file for embeddings
   doctor        Inspect backend/runtime state and local graph artifacts
+  install       Configure Codegraph MCP and skill integration for agent clients
+  uninstall     Remove Codegraph-owned installer configuration
   skill         Install or inspect the bundled agent skill
   version       Print the installed codegraph version
 
@@ -85,6 +87,9 @@ Examples:
   codegraph packet get file:src%2Fcli.ts --json
   codegraph artifact build --root . --out codegraph-out --json
   codegraph mcp serve --root . --stdio
+  codegraph install --target codex,claude --yes
+  codegraph install --print-config codex
+  codegraph uninstall --target codex --yes
   codegraph inspect ./src --limit 20
   codegraph duplicates ./src --min-confidence medium
   codegraph graph ./src
@@ -124,6 +129,7 @@ const knownCliCommands = new Set([
   "hotspots",
   "impact",
   "index",
+  "install",
   "inspect",
   "mcp",
   "orient",
@@ -137,12 +143,32 @@ const knownCliCommands = new Set([
   "sql",
   "unresolved",
   "version",
+  "uninstall",
 ]);
 
 export function isKnownCliCommand(command: string): boolean {
   return knownCliCommands.has(command);
 }
 
+export const INSTALL_HELP_TEXT = `codegraph install - Configure Codegraph for supported agent clients
+
+Usage: codegraph install [target] [--target <codex,claude,cursor,gemini,opencode,agents>] [--yes | --dry-run] [--print-config <target>] [--detect] [--json]
+
+Targets:
+  codex, claude, cursor, gemini, opencode, agents
+
+Safety:
+  Writes require --yes. Use --dry-run to preview changed files or --print-config <target> to print the MCP snippet.
+`;
+
+export const UNINSTALL_HELP_TEXT = `codegraph uninstall - Remove Codegraph-owned installer configuration
+
+Usage: codegraph uninstall [target] [--target <codex,claude,cursor,gemini,opencode,agents>] [--yes | --dry-run] [--detect] [--json]
+
+Safety:
+  Removes only Codegraph-owned marker blocks, marker files, or MCP entries whose command is codegraph.
+`;
+
 export const EXPLORE_HELP_TEXT = `codegraph explore - Answer a broad repo question with bounded repo context
 
 Usage: codegraph explore "<query>" [--root <path>] [--limit <n>] [--max-packets <n>] [--max-paths <n>] [--no-source] [--json | --pretty]
@@ -360,6 +386,8 @@ export function helpTextForCommand(command: string, positionals: readonly string
   if (command === "orient") return ORIENT_HELP_TEXT;
   if (command === "packet") return PACKET_HELP_TEXT;
   if (command === "explain") return EXPLAIN_HELP_TEXT;
+  if (command === "install") return INSTALL_HELP_TEXT;
+  if (command === "uninstall") return UNINSTALL_HELP_TEXT;
   if (command === "drift") return DRIFT_HELP_TEXT;
   if (command === "duplicates") return DUPLICATES_HELP_TEXT;
   if (command === "artifact") return ARTIFACT_HELP_TEXT;

src/cli/install.ts

@@ -0,0 +1,61 @@
+import {
+  detectInstallTargets,
+  installCodegraphTargets,
+  parseInstallTargetId,
+  parseInstallTargetIds,
+  printInstallConfig,
+  uninstallCodegraphTargets,
+  type InstallTargetId,
+} from "../installer/registry.js";
+
+export type InstallerCommandContext = {
+  command: "install" | "uninstall";
+  positionals: string[];
+  getOpt: (name: string) => string | undefined;
+  hasFlag: (name: string) => boolean;
+  writeJSONLine: (value: unknown) => void;
+  writeStdoutLine: (message: string) => void;
+  writeStderrLine: (message: string) => void;
+  exit: (code: number) => never;
+};
+
+export async function handleInstallerCommand(context: InstallerCommandContext): Promise<void> {
+  const printConfigTarget = context.getOpt("--print-config");
+  const targetIds = parseInstallerTargets(context);
+  const options = {
+    ...(targetIds !== undefined ? { targetIds } : {}),
+    yes: context.hasFlag("--yes"),
+    dryRun: context.hasFlag("--dry-run"),
+  };
+
+  if (printConfigTarget !== undefined) {
+    const targetId = parseInstallTargetId(printConfigTarget);
+    context.writeStdoutLine(printInstallConfig({ targetId }).trimEnd());
+    return;
+  }
+
+  if (context.hasFlag("--detect")) {
+    context.writeJSONLine({ targets: await detectInstallTargets(options) });
+    return;
+  }
+
+  if (context.command === "install") {
+    context.writeJSONLine(await installCodegraphTargets(options));
+    return;
+  }
+
+  context.writeJSONLine(await uninstallCodegraphTargets(options));
+}
+
+function parseInstallerTargets(context: InstallerCommandContext): InstallTargetId[] | undefined {
+  const targetOpt = context.getOpt("--target");
+  const positionalTarget = context.positionals[0];
+  if (context.positionals.length > 1) {
+    context.writeStderrLine(`Unexpected positional argument for ${context.command}: ${context.positionals[1]!}`);
+    context.exit(2);
+  }
+  if (targetOpt !== undefined && positionalTarget !== undefined) {
+    throw new Error("Use either --target or a positional target, not both.");
+  }
+  return parseInstallTargetIds(targetOpt ?? positionalTarget);
+}

src/cli/options.ts

@@ -63,6 +63,7 @@ const CLI_VALUE_OPTIONS = new Set<string>([
   "--duplicates",
   "--agent",
   "--target",
+  "--print-config",
   "--limit",
   "--fail-on",
   "--hotspot-jump-threshold",
@@ -360,6 +361,22 @@ const CLI_COMMAND_SCHEMAS = new Map<string, CliCommandSchema>([
     ),
   ],
   ["index", graphCommandSchema({ kind: "any" })],
+  [
+    "install",
+    commandSchema(["--detect", "--dry-run", "--json", "--yes"], ["--print-config", "--target"], {
+      kind: "max",
+      max: 1,
+      usage: "Usage: codegraph install [target] [--target <ids>] [--yes | --dry-run] [--print-config <target>]",
+    }),
+  ],
+  [
+    "uninstall",
+    commandSchema(["--detect", "--dry-run", "--json", "--yes"], ["--target"], {
+      kind: "max",
+      max: 1,
+      usage: "Usage: codegraph uninstall [target] [--target <ids>] [--yes | --dry-run]",
+    }),
+  ],
   [
     "inspect",
     commandSchema([...SHARED_BUILD_FLAGS, ...JSON_OUTPUT_FLAGS], [...SHARED_BUILD_OPTIONS, "--limit"], { kind: "any" }),