From 229fbb29689a9ae3c015d2a5b6e49103b2305e7f Mon Sep 17 00:00:00 2001 From: "roy.lei" Date: Thu, 9 Jul 2026 14:37:42 +0800 Subject: [PATCH 1/3] feat: add octo installer target Co-authored-by: octo-agent --- CHANGELOG.md | 5 +- README.md | 7 +- .../docs/getting-started/installation.md | 6 +- .../docs/getting-started/introduction.md | 2 +- .../docs/getting-started/quickstart.md | 2 +- site/src/content/docs/guides/indexing.md | 2 +- .../content/docs/reference/integrations.md | 1 + src/installer/index.ts | 6 +- src/installer/targets/octo.ts | 122 ++++++++++++++++++ src/installer/targets/registry.ts | 2 + src/installer/targets/types.ts | 2 +- 11 files changed, 142 insertions(+), 15 deletions(-) create mode 100644 src/installer/targets/octo.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index 6dca15d21..ce75bda8b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,9 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [Unreleased] +### New Features + +- CodeGraph's installer now supports **octo** (octo-agent). Running `codegraph install` can auto-detect and wire the CodeGraph MCP server into octo's MCP config at `~/.octo/mcp.json` (global) or `./.octo/mcp.json` (project-local), using the same `mcpServers.codegraph` shape as Claude Code / Cursor / Gemini. `codegraph uninstall` removes the entry cleanly. ## [1.3.1] - 2026-07-09 @@ -19,8 +22,6 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - Fixed a race that could leave a freshly-attached MCP session permanently silent: when a client's first messages arrived glued together during the daemon's connection handshake (roughly one attach in five on a busy machine), the daemon could drop them and stop reading that connection entirely — every tool call from that session then hung with no reply. The handshake now hands the connection over losslessly, and the fix is validated by hammering the previously-flaky attach test 25× under load. - The first tool call after the shared daemon starts no longer waits behind the query workers' cold start (which can take many seconds on a busy machine) — it's served directly until the first worker is warm, so a fresh session answers immediately. -## [1.3.0] - 2026-07-07 - ### New Features - CodeGraph now indexes **Nix** (`.nix`) — flakes, NixOS and home-manager modules, overlays, and package sets join the graph: `let` and attrset bindings, functions (simple, destructured `{ pkgs, ... }`, and curried), and `inherit` bindings all become searchable symbols, with call edges between bindings. File-level wiring follows the ways Nix actually connects files: `import ./relative/path.nix` (with `import ./dir` reaching the directory's `default.nix`), NixOS module `imports = [ ./hardware.nix ../common ]` lists, flake-style `modules = [ ./configuration.nix ]` lists, and the nixpkgs `callPackage ./pkgs/foo { }` idiom — so "what does this configuration actually pull in" and "what uses this module" are answerable on real setups. Dynamic references (`import `, variable paths, flake-input module references) are deliberately left unlinked rather than guessed. Thanks @TyceHerrman. (#324, #332, #648) diff --git a/README.md b/README.md index 0b23cc48f..55e5dcc40 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ Already installed? Run `codegraph upgrade` Follow [@getcodegraph](https://x.com/getcodegraph) on X for updates. -### Supercharge Claude Code, Cursor, Codex, OpenCode, Hermes Agent, Gemini, Antigravity, and Kiro with Semantic Code Intelligence +### Supercharge Claude Code, Cursor, Codex, OpenCode, Hermes Agent, Gemini, Antigravity, Kiro, and octo with Semantic Code Intelligence **Surgical context · fewer tool calls · faster answers · 100% local** @@ -99,7 +99,7 @@ In a **new terminal**, run the installer to connect CodeGraph to the agents you codegraph install ``` -Detects and auto-configures Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, and Kiro — wiring the CodeGraph MCP server into each. **This is the step that connects CodeGraph to your agent;** installing the CLI in step 1 does not do it on its own. It only wires up your agent — it does **not** index any code; building each project's graph is the separate `codegraph init` in step 3. (Shortcut: `npx @colbymchenry/codegraph` downloads and runs this in one go.) +Detects and auto-configures Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, Kiro, and octo — wiring the CodeGraph MCP server into each. **This is the step that connects CodeGraph to your agent;** installing the CLI in step 1 does not do it on its own. It only wires up your agent — it does **not** index any code; building each project's graph is the separate `codegraph init` in step 3. (Shortcut: `npx @colbymchenry/codegraph` downloads and runs this in one go.) ### 3. Initialize each project @@ -768,6 +768,7 @@ is written): - **Gemini CLI** - **Antigravity IDE** - **Kiro** +- **octo** ## Supported Languages @@ -876,7 +877,7 @@ MIT
-**Made for AI coding agents — Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, and Kiro** +**Made for AI coding agents — Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, Kiro, and octo** [Report Bug](https://github.com/colbymchenry/codegraph/issues) · [Request Feature](https://github.com/colbymchenry/codegraph/issues) diff --git a/site/src/content/docs/getting-started/installation.md b/site/src/content/docs/getting-started/installation.md index 4f9b90986..1426881df 100644 --- a/site/src/content/docs/getting-started/installation.md +++ b/site/src/content/docs/getting-started/installation.md @@ -11,10 +11,10 @@ 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**. +- Ask which agent(s) to configure — auto-detecting installed ones from **Claude Code**, **Cursor**, **Codex CLI**, **opencode**, **Hermes Agent**, **Gemini CLI**, **Antigravity IDE**, **Kiro**, and **octo**. - 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`. +- 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, Kiro, and octo 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). @@ -38,7 +38,7 @@ codegraph install --print-config codex # print snippet, no file wr ## 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. +Restart your agent (Claude Code / Cursor / Codex CLI / opencode / Hermes Agent / Gemini CLI / Antigravity IDE / Kiro / octo) for the MCP server to load. ## 3. Initialize projects diff --git a/site/src/content/docs/getting-started/introduction.md b/site/src/content/docs/getting-started/introduction.md index 44d6546c1..a23c59cef 100644 --- a/site/src/content/docs/getting-started/introduction.md +++ b/site/src/content/docs/getting-started/introduction.md @@ -5,7 +5,7 @@ description: What CodeGraph is, and why it makes AI coding agents faster and mor 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. +It exists to make AI coding agents — Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, Kiro, and octo — **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 diff --git a/site/src/content/docs/getting-started/quickstart.md b/site/src/content/docs/getting-started/quickstart.md index e1ea543f0..4b3c340a7 100644 --- a/site/src/content/docs/getting-started/quickstart.md +++ b/site/src/content/docs/getting-started/quickstart.md @@ -25,7 +25,7 @@ Already have Node? `npm i -g @colbymchenry/codegraph` works on any version. Code 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.) +Auto-detects and configures Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, Kiro, and octo — 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 diff --git a/site/src/content/docs/guides/indexing.md b/site/src/content/docs/guides/indexing.md index 1518c3d0a..cb9054c11 100644 --- a/site/src/content/docs/guides/indexing.md +++ b/site/src/content/docs/guides/indexing.md @@ -24,7 +24,7 @@ codegraph sync # incremental — only changed files ## Stay fresh automatically -**You don't need to run `codegraph sync` by hand during an agent session.** When your agent (Claude Code, Cursor, Codex, opencode, Hermes, Gemini, Antigravity, Kiro) launches `codegraph serve --mcp`, three layers cooperate to keep the index in step with your code — and to never give the agent a quiet wrong answer in the small window between an edit and the next sync. +**You don't need to run `codegraph sync` by hand during an agent session.** When your agent (Claude Code, Cursor, Codex, opencode, Hermes, Gemini, Antigravity, Kiro, octo) launches `codegraph serve --mcp`, three layers cooperate to keep the index in step with your code — and to never give the agent a quiet wrong answer in the small window between an edit and the next sync. ### 1. File watcher with debounced auto-sync (always on) diff --git a/site/src/content/docs/reference/integrations.md b/site/src/content/docs/reference/integrations.md index 1b4b87c89..62941e4ee 100644 --- a/site/src/content/docs/reference/integrations.md +++ b/site/src/content/docs/reference/integrations.md @@ -15,6 +15,7 @@ The interactive installer auto-detects and configures each supported agent — w - **Gemini CLI** - **Antigravity IDE** - **Kiro** +- **octo** Run `npx @colbymchenry/codegraph` and pick your agent(s); see [Installation](/codegraph/getting-started/installation/) for the non-interactive flags. diff --git a/src/installer/index.ts b/src/installer/index.ts index 5f703a385..8116bbfc5 100644 --- a/src/installer/index.ts +++ b/src/installer/index.ts @@ -3,7 +3,7 @@ * * Multi-target: writes MCP server config + instructions for the * agents the user picks (Claude Code, Cursor, Codex CLI, opencode, - * Hermes Agent, Gemini CLI, Antigravity IDE). + * Hermes Agent, Gemini CLI, Antigravity IDE, Kiro, octo). * Defaults to the Claude-only behavior for backwards compatibility * when no targets are explicitly chosen and nothing else is detected. * @@ -388,8 +388,8 @@ export async function runUninstaller(opts: RunUninstallerOptions): Promise const sel = await clack.select({ message: 'Remove CodeGraph from all your projects, or just this one?', options: [ - { value: 'global' as const, label: 'All projects (global)', hint: '~/.claude, ~/.cursor, ~/.codex, ~/.config/opencode, ~/.hermes, ~/.gemini, ~/.kiro' }, - { value: 'local' as const, label: 'Just this project (local)', hint: './.claude, ./.cursor, ./opencode.jsonc, ./.gemini, ./.kiro' }, + { value: 'global' as const, label: 'All projects (global)', hint: '~/.claude, ~/.cursor, ~/.codex, ~/.config/opencode, ~/.hermes, ~/.gemini, ~/.kiro, ~/.octo' }, + { value: 'local' as const, label: 'Just this project (local)', hint: './.claude, ./.cursor, ./opencode.jsonc, ./.gemini, ./.kiro, ./.octo' }, ], initialValue: 'global' as const, }); diff --git a/src/installer/targets/octo.ts b/src/installer/targets/octo.ts new file mode 100644 index 000000000..521dd005a --- /dev/null +++ b/src/installer/targets/octo.ts @@ -0,0 +1,122 @@ +/** + * octo (octo-agent) target. + * + * - MCP server entry to `~/.octo/mcp.json` (global) or + * `./.octo/mcp.json` (local) under the standard `mcpServers.codegraph` + * key. The shape is the same one Claude Code / Cursor / Gemini use, + * so users can copy-paste configs between octo and other agents. + * + * - No instructions file — octo reads skill / tool guidance from the + * MCP server's `initialize` response, so there is no separate + * markdown file to maintain. + * + * - No permissions concept — octo gates tool invocations through its + * own permission-mode system, not an external allowlist. `autoAllow` + * is silently ignored. + * + * Docs: https://octo-agent.dev/docs/guides/connect-mcp-servers + */ + +import * as fs from 'fs'; +import * as path from 'path'; +import * as os from 'os'; +import { + AgentTarget, + DetectionResult, + InstallOptions, + Location, + WriteResult, +} from './types'; +import { + getMcpServerConfig, + jsonDeepEqual, + readJsonFile, + writeJsonFile, +} from './shared'; + +function configDir(loc: Location): string { + return loc === 'global' + ? path.join(os.homedir(), '.octo') + : path.join(process.cwd(), '.octo'); +} + +function mcpJsonPath(loc: Location): string { + return path.join(configDir(loc), 'mcp.json'); +} + +class OctoTarget implements AgentTarget { + readonly id = 'octo' as const; + readonly displayName = 'octo'; + readonly docsUrl = 'https://octo-agent.dev/docs/guides/connect-mcp-servers'; + + supportsLocation(_loc: Location): boolean { + return true; + } + + detect(loc: Location): DetectionResult { + const file = mcpJsonPath(loc); + const config = readJsonFile(file); + const alreadyConfigured = !!config.mcpServers?.codegraph; + const installed = loc === 'global' + ? fs.existsSync(configDir('global')) || fs.existsSync(file) + : fs.existsSync(file) || fs.existsSync(configDir('local')); + return { installed, alreadyConfigured, configPath: file }; + } + + install(loc: Location, _opts: InstallOptions): WriteResult { + const files: WriteResult['files'] = []; + files.push(writeMcpEntry(loc)); + return { files }; + } + + uninstall(loc: Location): WriteResult { + const files: WriteResult['files'] = []; + + const file = mcpJsonPath(loc); + const config = readJsonFile(file); + if (config.mcpServers?.codegraph) { + delete config.mcpServers.codegraph; + if (Object.keys(config.mcpServers).length === 0) { + delete config.mcpServers; + } + writeJsonFile(file, config); + files.push({ path: file, action: 'removed' }); + } else { + files.push({ path: file, action: 'not-found' }); + } + + return { files }; + } + + printConfig(loc: Location): string { + const target = mcpJsonPath(loc); + const snippet = JSON.stringify({ mcpServers: { codegraph: getMcpServerConfig() } }, null, 2); + return `# Add to ${target}\n\n${snippet}\n`; + } + + describePaths(loc: Location): string[] { + return [mcpJsonPath(loc)]; + } +} + +function writeMcpEntry(loc: Location): WriteResult['files'][number] { + const file = mcpJsonPath(loc); + const dir = path.dirname(file); + if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true }); + + const existing = readJsonFile(file); + const before = existing.mcpServers?.codegraph; + const after = getMcpServerConfig(); + + if (jsonDeepEqual(before, after)) { + return { path: file, action: 'unchanged' }; + } + const action: 'created' | 'updated' = + before ? 'updated' : (fs.existsSync(file) ? 'updated' : 'created'); + if (!existing.mcpServers) existing.mcpServers = {}; + existing.mcpServers.codegraph = after; + writeJsonFile(file, existing); + return { path: file, action }; +} + +export const octoTarget: AgentTarget = new OctoTarget(); diff --git a/src/installer/targets/registry.ts b/src/installer/targets/registry.ts index 5e929d468..89bce4c4c 100644 --- a/src/installer/targets/registry.ts +++ b/src/installer/targets/registry.ts @@ -16,6 +16,7 @@ import { hermesTarget } from './hermes'; import { geminiTarget } from './gemini'; import { antigravityTarget } from './antigravity'; import { kiroTarget } from './kiro'; +import { octoTarget } from './octo'; export const ALL_TARGETS: readonly AgentTarget[] = Object.freeze([ claudeTarget, @@ -26,6 +27,7 @@ export const ALL_TARGETS: readonly AgentTarget[] = Object.freeze([ geminiTarget, antigravityTarget, kiroTarget, + octoTarget, ]); export function getTarget(id: string): AgentTarget | undefined { diff --git a/src/installer/targets/types.ts b/src/installer/targets/types.ts index 833a801ae..ef2e15496 100644 --- a/src/installer/targets/types.ts +++ b/src/installer/targets/types.ts @@ -19,7 +19,7 @@ export type Location = 'global' | 'local'; * lookup. New targets add a value here when they're added to the * registry. Keep these short and lowercase. */ -export type TargetId = 'claude' | 'cursor' | 'codex' | 'opencode' | 'hermes' | 'gemini' | 'antigravity' | 'kiro'; +export type TargetId = 'claude' | 'cursor' | 'codex' | 'opencode' | 'hermes' | 'gemini' | 'antigravity' | 'kiro' | 'octo'; /** * Result of `target.detect(location)`. From 40c80de835e9f3fd840ba78f021ceffae23890ae Mon Sep 17 00:00:00 2001 From: "roy.lei" Date: Thu, 9 Jul 2026 14:56:50 +0800 Subject: [PATCH 2/3] docs: include octo in CLI help and context docs Co-authored-by: octo-agent --- CLAUDE.md | 4 ++-- site/src/pages/index.astro | 2 +- src/bin/codegraph.ts | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index a06395619..84468b314 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## Project Overview -CodeGraph is a local-first code intelligence library + CLI + MCP server. It parses any supported codebase with tree-sitter, stores symbols/edges/files in SQLite (FTS5), and exposes a knowledge graph to AI agents (Claude Code, Cursor, Codex CLI, opencode) over MCP. Per-project data lives in `.codegraph/`. Extraction is deterministic — derived from AST, not LLM-summarized. +CodeGraph is a local-first code intelligence library + CLI + MCP server. It parses any supported codebase with tree-sitter, stores symbols/edges/files in SQLite (FTS5), and exposes a knowledge graph to AI agents (Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, Kiro, octo) over MCP. Per-project data lives in `.codegraph/`. Extraction is deterministic — derived from AST, not LLM-summarized. Distributed as `@colbymchenry/codegraph` on npm; same binary serves as installer, indexer, and MCP server. @@ -75,7 +75,7 @@ Defined in `src/types.ts`. Both extractors and resolvers must use these exact st - `targets/registry.ts` lists every supported agent. - `targets/types.ts` defines the `AgentTarget` interface — adding a 5th agent (Continue, Zed, Windsurf…) is **one new file in `targets/` + one entry in `registry.ts`**. Each target owns its config-file location and MCP-server JSON/TOML/JSONC writing. (Targets no longer write an instructions file — see below.) -- Current targets: `claude.ts`, `cursor.ts`, `codex.ts`, `opencode.ts`. +- Current targets: `claude.ts`, `cursor.ts`, `codex.ts`, `opencode.ts`, `hermes.ts`, `gemini.ts`, `antigravity.ts`, `kiro.ts`, `octo.ts`. - `targets/toml.ts` is a hand-rolled TOML serializer scoped to `[mcp_servers.codegraph]` (used by Codex). Sibling tables and `[[array_of_tables]]` are preserved verbatim. No new dependency. - opencode reads `opencode.jsonc` by default; the installer prefers existing `.jsonc`, falls back to `.json`, and creates `.jsonc` for greenfield installs. Edits are surgical via `jsonc-parser` so user comments and formatting survive install/re-install/uninstall round-trips. - `instructions-template.ts` no longer holds an instructions body — it exports only the ``/`` markers. The installer **stopped writing** a `## CodeGraph` block into each agent's instructions file (`CLAUDE.md` / `~/.codex/AGENTS.md` / `~/.config/opencode/AGENTS.md` / `~/.gemini/GEMINI.md` / `.cursor/rules/codegraph.mdc` / Kiro steering doc) because it duplicated the MCP `initialize` instructions verbatim (issue #529). Each target's `install` (self-heal on upgrade) and `uninstall` use the markers to **strip** a block a previous install left behind. `server-instructions.ts` is the single source of truth for agent-facing guidance. diff --git a/site/src/pages/index.astro b/site/src/pages/index.astro index a469c00b4..caf08d714 100644 --- a/site/src/pages/index.astro +++ b/site/src/pages/index.astro @@ -94,7 +94,7 @@ const install = 'npx @colbymchenry/codegraph';

MCP server

Expose the graph to Claude Code, Cursor, Codex, opencode, Hermes, - Gemini, Antigravity, and Kiro over MCP — agents answer in a handful of calls. + Gemini, Antigravity, Kiro, and octo over MCP — agents answer in a handful of calls.

diff --git a/src/bin/codegraph.ts b/src/bin/codegraph.ts index 97448f38d..fe26dc7d5 100644 --- a/src/bin/codegraph.ts +++ b/src/bin/codegraph.ts @@ -2181,7 +2181,7 @@ program */ program .command('install') - .description('Install codegraph MCP server into one or more agents (Claude Code, Cursor, Codex CLI, opencode, Hermes Agent)') + .description('Install codegraph MCP server into one or more agents (Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, Kiro, octo)') .option('-t, --target ', 'Target agent(s): comma-separated ids, or "auto"|"all"|"none". Default: prompt') .option('-l, --location ', 'Install location: "global" or "local". Default: prompt') .option('-y, --yes', 'Non-interactive: defaults to --location=global --target=auto, auto-allow on') @@ -2248,7 +2248,7 @@ program */ program .command('uninstall') - .description('Remove codegraph from your agents (Claude Code, Cursor, Codex CLI, opencode, Hermes Agent)') + .description('Remove codegraph from your agents (Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, Kiro, octo)') .option('-t, --target ', 'Target agent(s): comma-separated ids, or "all". Default: all') .option('-l, --location ', 'Uninstall location: "global" or "local". Default: prompt') .option('-y, --yes', 'Non-interactive: defaults to --location=global --target=all') From c2ae52f1c9b227c5ad3a112aa401e3e77adc1fcf Mon Sep 17 00:00:00 2001 From: "roy.lei" Date: Thu, 9 Jul 2026 15:39:06 +0800 Subject: [PATCH 3/3] feat: write CodeGraph instructions to octorules.md for octo Co-authored-by: octo-agent --- .../docs/getting-started/installation.md | 2 +- src/installer/targets/octo.ts | 31 ++++++++++++++++--- 2 files changed, 27 insertions(+), 6 deletions(-) diff --git a/site/src/content/docs/getting-started/installation.md b/site/src/content/docs/getting-started/installation.md index 1426881df..0deb155e6 100644 --- a/site/src/content/docs/getting-started/installation.md +++ b/site/src/content/docs/getting-started/installation.md @@ -14,7 +14,7 @@ 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**, **Kiro**, and **octo**. - 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, Kiro, and octo get the MCP config only. Removed cleanly by `codegraph uninstall`. +- 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` / `octorules.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). diff --git a/src/installer/targets/octo.ts b/src/installer/targets/octo.ts index 521dd005a..391059280 100644 --- a/src/installer/targets/octo.ts +++ b/src/installer/targets/octo.ts @@ -6,9 +6,10 @@ * key. The shape is the same one Claude Code / Cursor / Gemini use, * so users can copy-paste configs between octo and other agents. * - * - No instructions file — octo reads skill / tool guidance from the - * MCP server's `initialize` response, so there is no separate - * markdown file to maintain. + * - Project instructions are upserted into `~/.octo/octorules.md` + * (global) or `./.octo/octorules.md` (local) using the same + * marker-fenced CodeGraph section that Claude / Codex / Gemini use, + * because octo loads these rules into every session's system prompt. * * - No permissions concept — octo gates tool invocations through its * own permission-mode system, not an external allowlist. `autoAllow` @@ -20,6 +21,11 @@ import * as fs from 'fs'; import * as path from 'path'; import * as os from 'os'; +import { + CODEGRAPH_INSTRUCTIONS_BLOCK, + CODEGRAPH_SECTION_END, + CODEGRAPH_SECTION_START, +} from '../instructions-template'; import { AgentTarget, DetectionResult, @@ -31,6 +37,8 @@ import { getMcpServerConfig, jsonDeepEqual, readJsonFile, + removeMarkedSection, + upsertInstructionsEntry, writeJsonFile, } from './shared'; @@ -44,6 +52,10 @@ function mcpJsonPath(loc: Location): string { return path.join(configDir(loc), 'mcp.json'); } +function octorulesPath(loc: Location): string { + return path.join(configDir(loc), 'octorules.md'); +} + class OctoTarget implements AgentTarget { readonly id = 'octo' as const; readonly displayName = 'octo'; @@ -66,6 +78,7 @@ class OctoTarget implements AgentTarget { install(loc: Location, _opts: InstallOptions): WriteResult { const files: WriteResult['files'] = []; files.push(writeMcpEntry(loc)); + files.push(upsertInstructionsEntry(octorulesPath(loc))); return { files }; } @@ -85,17 +98,25 @@ class OctoTarget implements AgentTarget { files.push({ path: file, action: 'not-found' }); } + const rulesFile = octorulesPath(loc); + const instructionsAction = removeMarkedSection( + rulesFile, + CODEGRAPH_SECTION_START, + CODEGRAPH_SECTION_END, + ); + files.push({ path: rulesFile, action: instructionsAction }); + return { files }; } printConfig(loc: Location): string { const target = mcpJsonPath(loc); const snippet = JSON.stringify({ mcpServers: { codegraph: getMcpServerConfig() } }, null, 2); - return `# Add to ${target}\n\n${snippet}\n`; + return `# Add to ${target}\n\n${snippet}\n\n# Add to ${octorulesPath(loc)}\n\n${CODEGRAPH_INSTRUCTIONS_BLOCK}\n`; } describePaths(loc: Location): string[] { - return [mcpJsonPath(loc)]; + return [mcpJsonPath(loc), octorulesPath(loc)]; } }