CodeGraph session-bootstrap for omo (opencode + codex) + ~/.omo config SOT + license notices

TL;DR

Summary: On coding-agent session start, omo auto-bootstraps CodeGraph (init/keep-fresh the index, register its MCP server) for both the opencode and codex harnesses — detecting/provisioning the codegraph binary and skipping registration if that fails — with index data stored in a global ~/.omo/codegraph/ store linked into each project. Ships alongside a new ~/.omo JSONC config SOT (per-[harness] overrides, codex as first consumer) and comprehensive third-party license notices. Deliverables: shared SOT schema/loader (packages/utils); shared codegraph helpers (binary-resolve, storage-prepare, env+provision); opencode codegraph MCP + session.created bootstrap hook + config section; codex ~/.omo SOT loader + codegraph MCP gating + SessionStart component + install/seed; root + omo-codex THIRD-PARTY-NOTICES.md with ship verification. Effort: XL Risk: Medium - symlinked global index store, MCP-registered-before-index ordering, cross-harness isolation, and a new config SOT are each load-bearing.

Context

Original request

사용자: "그 ~/sionicai/pi-sionic 인가 pionic 인가 여기꺼 최신버전 한번 살펴볼래? 그리고 저기에 세션 켜질때에 codegraph init 하게하고 업데이트도 필요할때마다 하게하고 이거 정보를 로컬에 적당한 위치에 넣고서 쓰게 하고 업데이트도 잘 반영되게 하는게 들어갔는데, 이거 우리 적용해볼 수 있을까? ../opencode ../codex ../codegraph 싹 다 최신으로 git pull 받고 최신 api 최신 버전 기준으로 해서 살펴보고서 말해주라 ulw plan". 후속: codex도 애매하면 비활성, codegraph 텔레메트리 기본 off, 라이선스 전수 고지 보강, codex 설정은 settings.toml/env가 아니라 ~/.omo 기반 새 SOT(마이그레이션 고려)로 — 하네스(codex/opencode/omo-native)별 오버라이드 + 하네스 한정 설정 힌팅 스키마까지 함께 설계. high accuracy, Momus는 codex CLI의 momus 리뷰어를 xhigh로.

Interview summary

Integration via MCP route (codegraph serve --mcp), NOT pi's native-tool-wrapper route. Reference = sionic-ai/pionic-mono sionic-codegraph builtin (mengmotaHost ~/sionicai/pi-sionic, already pushed — nothing to push).
Binary policy (user): detect → auto-provision → if it fails, do NOT register the MCP — both harnesses (codex too). Mirrors omo lsp/ast_grep enabled: exists + git-bash detect-skip.
Storage (mirror pi): global ~/.omo/codegraph/projects/<base>-<sha256(path)[:16]>/, project .codegraph symlinked (junction on win32). CODEGRAPH_INSTALL_DIR scoped there. Telemetry OFF by default (forced).
Session start: opencode session.created event hook + codex new SessionStart component → prepare(symlink)→provision→status→init|sync background non-blocking; failures never abort the session. Accepted behavior: fresh repo's first session has no codegraph tools (bg init running) → tools active from session 2.
Config SOT (workstream C): ~/.omo/config.jsonc (+ project .omo/config.jsonc), JSONC. Override via [harness] blocks ([codex]/[opencode]/future [omo]), base deep-merged with the active harness block (VSCode [language] analogy). Schema declares which harness(es) each setting supports + warns when set under an unsupported harness. THIS plan: foundation + codex consumption only; opencode keeps oh-my-openagent.json (no migration now; types stay harness-agnostic so opencode can read SOT later). env-var override kept for back-compat during transition.
License (workstream B): comprehensive — root THIRD-PARTY-NOTICES.md + packages/omo-codex/THIRD-PARTY-NOTICES.md; audit all vendoring + fix gaps; verify NOTICE files ship in tarballs.
Tests: TDD + tests-after + manual QA (all). High accuracy → Momus loop via codex CLI at reasoning effort xhigh.

Research findings

CodeGraph v1.0.1 MCP server does NOT lazy-index — no .codegraph/codegraph.db ⇒ inactive, 0 tools (src/mcp behavior). codegraph init is idempotent; the daemon's native FS watcher (2s debounce) + connect-time catch-up keep the index fresh; codegraph serve --mcp must not be run by humans. Index dir name overridable by CODEGRAPH_DIR (plain name only, not absolute) → pi relocates via symlink instead. → implication: omo must run init itself; freshness is otherwise free.
Reference sionic-codegraph/index.ts (537 lines): getCodeGraphDataRoot=~/.pionic/codegraph; prepareCodeGraphWorkspace makes ~/.pionic/codegraph/projects/<base>-<sha256(resolved)[:16]> and symlinks project .codegraph → it (junction on win32; throws "storage blocked" if .codegraph is a real dir or wrong link); env CODEGRAPH_INSTALL_DIR + CODEGRAPH_NO_DOWNLOAD=1; resolveCodeGraphCommand 4-tier env→bundled(require.resolve)→provisioned(~/.pionic/lsp/node-servers/node_modules)→PATH; runStartupSync on session_start: prepare→(ensureProvisionedServers if PATH-tier & not on PATH)→status --json→(127⇒unavailable+return)→init --index|sync --quiet→ready, every failure = widget + return (never aborts). → implication: copy storage+provision+startup design onto MCP registration.
opencode (5d0f86606): createBuiltinMcps(disabledMcps,...) (packages/omo-opencode/src/mcp/index.ts:26) gates each MCP if(!disabledMcps.includes(name)); LocalMcpConfig {type:"local",command,enabled,environment} with enabled: resolvedCommand.exists (src/mcp/lsp.ts:161, src/mcp/ast-grep.ts:118); runtime detect resolveRuntimeExecutable (src/mcp/runtime-executable.ts:32, Bun.which); final gate applyMcpConfig (src/plugin-handlers/mcp-config-handler.ts:28-69) deletes disabled. Session-once event session.created (src/plugin/event.ts:141); hooks built src/plugin/hooks/create-session-hooks.ts:66, dispatched src/plugin/event-hook-dispatcher.ts:37, copy src/hooks/auto-update-checker/. Config Zod schema src/config/schema/oh-my-opencode-config.ts:31 (add section like team-mode.ts), loader src/plugin-config/layered-config-loader.ts:121, basename oh-my-openagent. → implication: opencode codegraph = src/mcp/codegraph.ts + a session.created hook + a Zod config section.
codex (dfd03ea01b): static plugin/.mcp.json (ast_grep/grep_app/context7/git_bash/lsp); SessionStart hooks in plugin/hooks/hooks.json (rules/telemetry/auto-update[^startup$]/bootstrap), components built to dist/cli.js. Components read config via env ONLY today; no shared config module. SOT loader home → new packages/omo-codex/plugin/shared/src/config-loader.ts (imported by each component cli). JSONC parser reuse packages/utils/src/jsonc-parser.ts. ~/.omo/rules already read (components/rules/src/rules/constants.ts). Seed/migrate via plugin/scripts/auto-update.mjs + migrate-codex-config.mjs. Platform-stamp precedent scripts/install/git-bash-mcp-env.mjs. git-bash detect-skip+hint packages/git-bash-mcp/src/git-bash-resolver.ts:31. codex MCP config (its own ~/.codex/config.toml [mcp_servers.x]) NOT used here — we register via plugin .mcp.json. → implication: codex codegraph = SOT loader + .mcp.json entry with detection-gating + a SessionStart component + install seed.
License (state): per-component NOTICE/LICENSE under packages/omo-codex/plugin/components/{lsp,rules,comment-checker,ulw-loop,ultrawork,start-work-continuation} + packages/lsp-tools-mcp; root LICENSE.md = SUL-1.0 w/ third-party clause; no root aggregate. Need notices for 13 npm deps (MCP SDK, @ast-grep/cli+napi, clack, commander, diff, js-yaml, jsonc-parser, picocolors, picomatch, posthog-node, vscode-jsonrpc, @code-yeongyu/comment-checker) + codegraph (@colbymchenry, MIT) + ported pi-lsp-client/pi-rules/pi-comment-checker (MIT). Distribution via root package.json files[]. JSONC parser packages/utils/src/jsonc-parser.ts.
Isolation: omo-opencode and omo-codex are isolated bundles (no cross-import); both depend on packages/utils → shared SOT + codegraph helpers belong in packages/utils.

Metis review

Metis (9 CRITICAL / 7 MINOR / 6 AMBIGUOUS). Resolutions:

C1/C2 (codex has NO per-session MCP gate — enablement is install-time in ~/.codex/config.toml via scripts/install/config.mjs ensurePluginMcpEnabled; git_bash is platform+install-time+soft-prompt, NOT a detect-skip precedent) → USER DECISION (conditional): IF codex tolerates a failing required=false MCP gracefully → unify on git_bash style: always-declare codegraph in .mcp.json with required=false + a soft prompt, binary absence ⇒ codex skips the failed spawn, no broken session. IF NOT → SessionStart rewrites config.toml enabled. VERIFIED & RESOLVED: codex tolerates a required=false MCP failure gracefully — non-required servers are spawned, failures logged as McpStartupUpdateEvent, and only required_servers block validate_required_servers() (codex-rs/codex-mcp/src/connection_manager.rs:140-144,287-327; config/src/mcp_types.rs:141-143; test exec/tests/suite/mcp_required_exit.rs). → git_bash style chosen: declare codegraph in .mcp.json with required=false + a serve-wrapper that exits non-zero when the binary is unresolvable (codex logs+skips, session unaffected) + a soft prompt. NO config.toml rewrite; git_bash unchanged. My false "git-bash detect-skip" reference is removed.
C3 (codegraph self-installer writes ~/.codex/config.toml + ~/.codex/AGENTS.md) → GUARDRAIL: hook invokes ONLY status/init/sync, NEVER install/serve; add QA asserting those files are byte-unchanged after the hook.
C4 (env var was WRONG: CODEGRAPH_INSTALL_DIR = binary cache, NOT index store; index store hardcoded to project .codegraph/; CODEGRAPH_DIR = rename-only, single segment, no absolute → cannot relocate) → FOLDED FIX: relocate index via symlink ONLY; set CODEGRAPH_INSTALL_DIR=~/.omo/codegraph for the binary cache; do not rely on any env var to move the index.
C5/C6 (real .codegraph/codegraph.db here is ~5 GB + live daemon.sock; global store accretes multi-GB/project with no GC; cross-volume junction fails; socket ~104-char limit → tmpdir fallback; worktrees hash to DIFFERENT stores) → AWAITING USER (Q: storage model). If global kept: add size/GC guard + same-filesystem check + cross-volume in-place fallback.
C7 (MCP registered-but-unindexed) → USER DECISION: binary-exists gate (NOT index-exists). The plugin ALWAYS runs init/sync itself, so only the binary must exist. Safe because codegraph's MCP server, when the index is absent, advertises inactive / "not initialized" guidance — NOT empty results (verified: codegraph CLI lane), so the model is not misled; it just uses Read until init completes (the accepted session-2 window).
STORAGE (C4/C5/C6) → USER DECISION (adoption rule): if the project ALREADY has a real .codegraph/ → use it in-place (no symlink, no move); if absent → create the global ~/.omo/codegraph/projects/<slug>/ store + symlink the project .codegraph to it (junction on win32). Fallbacks: junction/symlink failure or cross-volume ⇒ create a real in-place .codegraph/ instead (never abort). This auto-handles this repo's existing ~5 GB .codegraph/ (stays in-place). Global store gets a size/GC guard + same-filesystem check before symlinking. Index relocation is via symlink ONLY (env vars can't); CODEGRAPH_INSTALL_DIR=~/.omo/codegraph scopes the binary cache.
C8 (provision concurrency: bootstrap lock is per-plugin-version, not per-resource) → FOLDED: codegraph gets its OWN per-host provisioning lock + idempotent completion marker.
C9 (license scope bigger: codegraph pulls 6 platform pkgs + vendored Node 24 + tree-sitter WASM grammars; ast-grep binary 0.42.3 also un-noticed; SUL-1.0 makes NOTICES a compliance requirement) → FOLDED: enumerate the REAL set (codegraph + platform pkgs + vendored Node + grammars + ast-grep + npm deps) before writing NOTICES.
MINOR folded: M1 ~/.omo namespace + project .omo/* is gitignored (project .omo/config.jsonc would be ignored — use .git/info/exclude or document); M2 add .codegraph to project gitignore/exclude; M3 adoption of pre-existing real .codegraph (this repo!) — detect real dir → skip-symlink/use-in-place, never destroy; M4 harness identity is PASSED explicitly by each bundle (not auto-sniffed); M5 precedence order written (see below); M6 telemetry off knob = CODEGRAPH_TELEMETRY exact off-value, forced in spawned env; M7 daemon idle-timeout/NO_DAEMON/NO_WATCH lifecycle pinned.
AMBIGUOUS defaults applied: A1 pin @colbymchenry/[email protected] (scoped name — goal's "colbymchenry/codegraph" was the repo); A2 provision via ast-grep-style checksummed GitHub-release download (manifest+sha256), NOT runtime npm i (avoids self-installer + optionalDeps mirror bug); A3 only status/init/sync at startup; A4 sanitize <base> to [A-Za-z0-9._-] (mirror git-bash safePathSegment); A5 junction on win32 + cross-volume fallback; A6 shared types model ONLY codex's current needs + extensible (no opencode mapping pre-built).
Precedence (M5, decided): built-in defaults < ~/.omo base < ~/.omo [harness] < project .omo base < project .omo [harness] < env override (back-compat; env wins during transition, documented as temporary).
Scope-creep watch (Metis): NO opencode migration; license list ENUMERATED not open-ended; codegraph's claude/cursor/gemini installer targets OUT.

Scope

Must have

On opencode session start, when codegraph is resolvable/provisionable: the project index is prepared per the adoption rule (in-project .codegraph if it already exists, else the global ~/.omo/codegraph/projects/<slug>/ store + symlink) and init/sync runs in the background non-blocking; the codegraph MCP is registered with enabled: <binary resolvable> and serves tools once the index exists.
On codex session start: the same prepare/provision/init behavior via a new SessionStart component; the codegraph MCP is declared in .mcp.json with required=false and launched through a serve-wrapper that exits non-zero when the binary is unresolvable — so when detection/provision fails codex logs the failure and skips the server (no broken/active MCP), per the verified required=false graceful-skip behavior.
Both harnesses degrade safely when codegraph cannot be detected AND auto-provision fails: opencode omits the MCP (enabled:false); codex's required=false wrapper exits non-zero so codex skips it. Either way there is no broken/inactive server and the session proceeds normally.
CodeGraph telemetry OFF by default (env forced).
A ~/.omo/config.jsonc SOT with [harness] override blocks (JSONC), a loader+resolver in packages/utils, harness-applicability metadata + warnings, consumed by the codex side for codegraph config; env-var back-compat preserved.
Root THIRD-PARTY-NOTICES.md + packages/omo-codex/THIRD-PARTY-NOTICES.md covering all vendored deps + codegraph + ported code; verified to ship in the published tarballs.
TDD (RED→GREEN) for every shared helper + a tests-after layer + agent-executed manual QA on the real opencode and codex harnesses for every success criterion.

Must NOT have (guardrails)

No forking/patching CodeGraph itself; no running codegraph serve --mcp by hand in tests.
No opencode config migration to ~/.omo in this plan (opencode keeps oh-my-openagent.json); SOT consumption on the opencode side is OUT (types stay harness-agnostic only).
No pi/pionic harness work; no Claude Code (omocc) distribution changes.
No writing tracked project files other than the .codegraph symlink; the only allowed untracked project-local metadata write is adding .codegraph to .git/info/exclude as specified in Todo 3. Never throw out of a session-start path (failures are logged/widgeted, never fatal).
No cross-import between omo-opencode and omo-codex bundles (shared code goes in packages/utils).
Do not touch the untracked build artifacts under packages/oh-my-openagent-*/bin/ (dirty_worktree) — out of every task's scope.
No as any, empty catches, debug prints, or dead code; respect the 250-LOC module ceiling.

Verification strategy

Zero human intervention - all verification is agent-executed.

Test decision: TDD for packages/utils shared helpers + per-component logic (framework: bun test / vitest as the package uses) plus tests-after for wiring; manual QA always.
QA policy: every todo has agent-executed scenarios through a real surface — opencode via opencode run --format json / server+SSE / tmux, ALWAYS in an isolated XDG sandbox with a before/after opencode.db session-count proof (AGENTS.md §OPENCODE rules 1-2 / opencode-qa skill — never pollute the real ~/.local/share/opencode/opencode.db); codex via the plugin hook CLI (node .../dist/cli.js hook session-start) and a real codex run under an isolated CODEX_HOME; config/DB/symlink shaped work via CLI stdout + filesystem/state diff + parsed config dump.
Evidence for this branch is consolidated under .omo/evidence/20260615-codegraph-omo-integration/. Root .omo/evidence/task-* files are local ignored scratch artifacts only and must not appear in the PR diff.
QA shell + invocation conventions (apply to every scenario below):
- All tmux QA panes are created running fish (tmux new-session -d -s <name> -x 200 -y 50 fish) so the fish syntax in the steps (set x (cmd), for i in (seq ..); ..; end, $status, math) runs as written. (Momus accepts an explicit shell; the host shell is fish.)
- packages/utils is ESM with NO build (package.json exports → ./src/index.ts, "type":"module", deps only js-yaml+jsonc-parser). Therefore: NEVER require('./packages/utils/src/index.ts'); run inline checks with bun importing source — bun -e 'const m = await import("./packages/utils/src/index.ts"); ...' — and put utils tests co-located at packages/utils/src/<name>.test.ts, run via cd packages/utils && bun test src/<name>.test.ts (matches its bun test src/*.test.ts script). Do NOT add a runtime validator dep (no zod/typebox) to packages/utils.

Execution strategy

Parallel execution waves

Target 5-8 todos per wave. Fewer than 3 in a non-final wave = under-splitting. Wave 1 (no deps): 1 SOT schema/types · 2 codegraph binary-resolve · 3 codegraph storage-prepare · 4 codegraph env+provision · 5 root NOTICES · 6 codex NOTICES+audit Wave 2 (after W1): 7 SOT loader/[harness] resolver (after 1) · 10 opencode codegraph config schema (after 1) · 11 license ship-verify (after 5,6) Wave 3 (after W2): 8 opencode codegraph MCP (after 2,3,4,10) · 9 opencode session.created bootstrap hook (after 2,3,4,10) · 12 codex shared SOT loader + shared-pkg scaffold (after 7) Wave 4 (after W3): 13 codex codegraph component scaffold + .mcp.json entry + serve-wrapper + workspaces[] registration (after 2,4,12) Wave 5 (after W4): 14 codex codegraph SessionStart cli/hook + hooks.json (after 3,4,12,13) Wave 6 (after W5): 15 codex install/seed SOT+migration (after 12,14) Critical path: 1 → 7 → 12 → 13 → 14 → 15 → F-wave (the codex component chain 13→14→15 shares one component dir + build registration, so it is inherently sequential — not a splitting defect)

Dependency matrix

Todo	Depends on	Blocks	Can parallelize with
1	none	7,10	2,3,4,5,6
2	none	8,9,13	1,3,4,5,6
3	none	8,9,14	1,2,4,5,6
4	none	8,9,13,14	1,2,3,5,6
5	none	11	1,2,3,4,6
6	none	11	1,2,3,4,5
7	1	12	10,11
8	2,3,4,10	F	9,12
9	2,3,4,10	F	8,12
10	1	8,9,F	7,11
11	5,6	F	7,10
12	7	13,14,15	8,9
13	2,4,12	14,F	—
14	3,4,12,13	15	—
15	12,14	F	—

TODOs

Implementation + its test = ONE todo. Never separate them.

Final Verification Wave

Runs in parallel after ALL todos. Each reviewer returns APPROVE or REJECT. Any REJECT -> fix -> re-run only the rejecting reviewer.

Evidence hygiene note for final reviewers (2026-06-15):

The todo evidence references above intentionally point at the dated .omo/evidence/20260615-codegraph-omo-integration/ tree. Do not resurrect root .omo/evidence/task-* paths.
.omo/evidence/final-qa/ remains the tracked F3 cross-harness QA bundle from commit 712972a59 and is intentionally not duplicated under the dated folder; duplicating it would reintroduce the duplicate-evidence problem this cleanup is avoiding.
.omo/evidence/final-review/ remains the tracked final-review and blocker-repair evidence bundle for post-review fixes: unavailable no-mutation, Windows install-dir shim, dist regeneration, final QA evidence consistency, and focused post-fix tests.
.omo/evidence/20260615-todo9-codegraph-bootstrap-disabled-hooks/ remains a targeted Todo 9 / F4 gate-repair bundle for the disabled-hooks blocker. It is outside the main dated folder so reviewers can distinguish blocker repair evidence from the original todo evidence.
.omo/evidence/20260615-codegraph-resolution-platforms/ remains a targeted CodeGraph resolver/platform repair bundle for npm platform metadata, Windows shim, invalid env override, focused tests, and OpenCode QA evidence. It is outside the main dated folder so reviewers can distinguish cross-platform resolver repair evidence from the original todo evidence.
.omo/evidence/20260615-codegraph-omo-integration/final-loc-refactor/ remains the F2 LOC gate-repair evidence for splitting packages/omo-codex/plugin/components/codegraph/src/hook.ts into focused hook.ts, hook-types.ts, and session-start-worker.ts files, including component tests, typecheck, build, test:codex, and isolated Codex QA.
.agents/skills/work-with-pr/SKILL.md and .opencode/skills/work-with-pr/SKILL.md are included as an F2 gate repair only: the project-skill reference test expected task delegation to use a real category. Evidence: .omo/evidence/20260615-codegraph-omo-integration/final-f2-work-with-pr-skill-test.txt.
Do not mark F1-F4 complete from this hygiene pass alone; final reviewers must still rerun/approve those boxes.
F1. Plan compliance audit - read the plan end-to-end; verify every Must Have exists (read file / run command), every Must NOT Have is absent (search, reject with file:line), every .omo/evidence/ file exists.
F2. Code quality review - typecheck + lint + full test suite (both bundles + packages/utils); review changed files for as any / empty catches / debug prints / dead code / slop / 250-LOC ceiling.
F3. Real manual QA - from clean state, execute EVERY QA scenario from EVERY todo plus cross-harness integration (fresh-repo first-session→second-session tool activation; binary-missing skip; symlink conflict) and save evidence to .omo/evidence/final-qa/. Opencode-spawning QA runs in an isolated XDG sandbox with the before/after opencode.db session-count isolation proof; codex-spawning QA runs under an isolated CODEX_HOME (AGENTS.md §OPENCODE/§CODEX).
F4. Scope fidelity check - per todo, diff spec vs actual changes: nothing missing, nothing beyond spec (esp. no opencode SOT migration, no cross-bundle import), no unaccounted files.

Commit strategy

See each todo's Commit line. One atomic commit per todo on a feature branch off dev; pre-commit runs the todo's acceptance commands. Do not commit the dirty_worktree bin/ artifacts.

Success criteria

Verification commands

bash

# opencode: codegraph MCP present & enabled when binary resolvable
# (run inside an isolated XDG sandbox per AGENTS.md opencode-qa — see todo 9; never touch the real opencode.db)
for v in XDG_DATA_HOME XDG_CONFIG_HOME XDG_STATE_HOME XDG_CACHE_HOME; set -x $v (mktemp -d); end; mkdir -p $XDG_CONFIG_HOME/opencode; printf '{"plugin":["%s/packages/omo-opencode/dist/index.js"]}' $PWD > $XDG_CONFIG_HOME/opencode/opencode.jsonc
opencode run --format json "list mcp tools" 2>/dev/null | grep -i codegraph   # Expected: codegraph_* tools listed (after index exists)
# codex: SessionStart component runs and reports a JSON outcome
node packages/omo-codex/plugin/components/codegraph/dist/cli.js hook session-start   # Expected: JSON with codegraph bootstrap status, exit 0
# storage model (adoption rule: a pre-existing real dir stays in-place; only a FRESH repo gets a symlink)
ls -ld "$PWD/.codegraph"   # Expected: a real directory if it pre-existed (e.g. THIS repo), OR a symlink → ~/.omo/codegraph/projects/<slug> for a fresh repo
# SOT resolution
bun -e "const m=await import('./packages/utils/src/index.ts'); console.log(JSON.stringify(m.loadOmoConfig({harness:'codex',cwd:process.cwd(),env:{}}).config.codegraph||{}))"   # Expected: base deep-merged with [codex]
# license ship
tar -tf "$(npm pack --silent)" | grep THIRD-PARTY-NOTICES   # Expected: file present in tarball

Final checklist

All Must Have present
All Must NOT Have absent
All QA evidence captured under .omo/evidence/