Skip to content

Local code intelligence for developers and AI agents. Connect code, docs and infrastructure in a persistent graph, with CBM Lens, MCP tools, agent integrations and change-aware test selection.

Merge origin/main into carry/1862-install-hook-optout

Martin Vogel1adabd8c5799
diff --cc README.md
index 5a0e4d12c,73e7e7f64..3a05de6d2
--- a/README.md
+++ b/README.md
@@@ -104,16 -128,26 +128,28 @@@ Restart your coding agent. Say **"Inde
3. **Restart** your coding agent.
- The `install` command automatically strips macOS quarantine attributes and ad-hoc signs the binary — no manual `xattr`/`codesign` needed.
+ The `install` command automatically strips macOS quarantine attributes and ad-hoc signs the binary; no manual `xattr`/`codesign` needed.
</details>
- The `install` command auto-detects installed coding agents and configures their documented MCP entries plus durable instructions, skills, and lifecycle hooks where supported.
+ ### Agent setup: skills, profiles, and hooks
+
+ Installation also equips supported coding agents to use the graph in daily work. The native `install` command detects clients and installs the integration pieces their documented formats support:
+
+ | Component | What it adds |
+ |-----------|--------------|
+ | **MCP configuration** | Connects the client to the local server and its tools. |
+ | **Instructions and skills** | Explains graph-first exploration, index freshness, coverage checks, and when to read source. |
+ | **Scout, Verify, and Auditor profiles** | Offers fast provisional lookup, task-directed verification, or bounded full verification, where custom agents are supported. |
+ | **Session and compaction hooks** | Restores graph context at supported lifecycle events. |
+ | **Search and read hooks** | Adds relevant graph context to supported searches and flags recorded coverage gaps after supported file reads. |
+
+ Hook augmentation is context-only and fail-open: it does not replace or block the requested tool call. Features vary by client and platform; some clients use durable instructions or a parent-agent handoff instead of hooks or direct subagent MCP access. Codex users review and trust installed hooks through `/hooks`. See [Multi-Agent Support](#multi-agent-support) and [Sessions, compaction, and subagents](#sessions-compaction-and-subagents) for exact support and activation requirements.
+Hooks are enabled by default. Run `codebase-memory-mcp install --no-hooks` to remove CBM-managed hooks while keeping MCP registration and other integration files; the choice persists for later installs and updates. Run `codebase-memory-mcp install --hooks` to re-enable them, or inspect the current preference with `codebase-memory-mcp config get install_hooks`.
+
### Session Coordination Daemon
- CBM automatically shares one per-account coordination daemon across Claude Code, Codex, OpenCode, and every other configured client. There is no opt-in setting for MCP servers or hook clients: the first daemon-backed CBM session starts it, each session registers its own work, and the final session shuts it down. The daemon owns long-lived background services such as watchers, shared indexing jobs, and the optional UI. Closing one session cancels work owned only by that session, while work still needed by another session continues.
+ CBM automatically shares one per-account coordination daemon across Claude Code, Codex, OpenCode, and every other configured client. There is no opt-in setting for MCP servers or hook clients: the first daemon-backed CBM session starts it, each session registers its own work, and a session-managed daemon stops after the final session. A daemon started with `daemon start` remains running until stopped. The daemon owns long-lived background services such as watchers, shared indexing jobs, and the optional UI. Closing one session cancels work owned only by that session, while work still needed by another session continues.
The detached daemon does not depend on an MCP frontend's stderr. It keeps owner-only durable records under the canonical `${CBM_CACHE_DIR}/logs` directory (default `~/.cache/codebase-memory-mcp/logs`):
diff --cc docs/CONFIGURATION.md
index 4cf82faf4,aa4a72d81..a37584c55
--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@@@ -88,18 -87,31 +88,34 @@@ Current keys
|---|---|---|
| `auto_index` | `false` | Automatically index new projects when an MCP session starts. |
| `auto_index_limit` | `50000` | Maximum file count allowed for automatic indexing of a new project. |
- | `auto_watch` | `true` | Register the session's project with the background git watcher on connect. Set `false` to keep a session from registering its project (the watcher still runs for other projects). |
- | `watcher_enabled` | `true` | Master switch for the background watcher subsystem. Set `false` to stop the watcher from starting at all — no poll thread and no project registration. Reindex manually with `index_repository` when disabled. |
+ | `auto_watch` | `true` | Global switch for MCP session watch registration. On the next refresh or registration request, `true` allows session roots and successful `index_repository` targets to be watched; `false` removes all watches. The background watcher can still run with no registered projects. |
+ | `doc_candidates` | `auto` | Score documentation sections against code to store doc↔code candidates (the possible targets of a section, and the sections that may describe a function or file, each with a judged probability). Unset (`auto`), the index mode decides: on for `full` indexes (the default mode), off for `moderate` and `fast`. Set `true` or `false` to choose for every mode; `config reset doc_candidates` returns to `auto`. The scoring grows with sections × functions: under a second up to ~100k functions, ~15 s at ~400k, ~3 minutes on the Linux kernel. Off stores no candidates and leaves the rest of the graph unchanged; on in `fast` mode stores candidates without adding `fast`'s skipped `SIMILAR_TO` / `SEMANTICALLY_RELATED` edges. `index_repository` also takes `doc_candidates` for a single index, which wins over this setting. Applies from the next index. |
+ | `watcher_enabled` | `true` | Master switch for the background watcher subsystem. Set `false` to stop the watcher from starting at all — no poll thread and no project registration. Reindex manually with `index_repository` when disabled. Active MCP sessions can register their root project and successful explicit index targets; under `daemon start` those watches outlive the session until the daemon stops, the project is deleted, its directory disappears, or `auto_watch` is set to `false`. `index_status` reports the current state in its `watch` object. |
+ | `watch_non_git` | `false` | Also poll project roots that are **not git repositories**. By default the watcher only follows git projects, so a project indexed from a plain directory is never refreshed after its first index — reindex it manually with `index_repository`. Set `true` to poll such roots on the same adaptive cadence with a file-tree scan: the indexer's own discovery walk (same skip lists, `.gitignore` and `.cbmignore` rules) hashed over each file's path, size and mtime. Any change reindexes once; paths the indexer skips (including cbm's own `.codebase-memory/` output) never trigger. The first poll after the daemon starts reindexes each such project once, since nothing records which tree state the index holds. The scan walks the whole tree every poll, so it costs more than git polling on very large trees. Read once when the daemon starts, like `watcher_enabled`. |
| `index_max_files` | `off` | Optional maximum number of accepted source files in one discovery run. |
| `index_max_source_mb` | `off` | Optional maximum accepted source size in MiB in one discovery run. |
+| `install_hooks` | `true` | Install CBM-managed client hooks. `install --no-hooks` persists `false`; `install --hooks` restores `true`. |
+
+Bare installs and updates respect the stored hook preference. MCP registration, skills, instructions, and profiles remain installed when hooks are disabled.
+ For a watched project, `index_status` names the polling method in `watch.strategy`:
+ `git` (HEAD and dirty-state polling), `tree` (a non-git root polled by the
+ `watch_non_git` file-tree scan), `none` (a non-git root that is registered but never
+ polled, the default for a plain directory) or `pending` (registered; the first poll
+ has not run yet).
+
> **`watcher_enabled` vs `auto_watch`.** `watcher_enabled` controls whether the
> watcher *subsystem* starts at all (the background poll thread). `auto_watch` is
- > narrower: it only controls whether a connecting session registers *its own*
- > project with an already-running watcher. When `watcher_enabled=false`,
+ > narrower: it globally controls MCP session watch registration. On the next
+ > refresh or registration request, `false` removes all watches; `true` allows
+ > session roots and successful explicit `index_repository` targets to register.
+ > Watcher refreshes retain `mode`, `persistence`, and the resolved
+ > `doc_candidates` boolean from the latest successful explicit index registered
+ > for that target. This boolean can come from the request or its global setting.
+ > When neither supplied a boolean, refresh uses the current setting or mode default.
+ > A watcher callback also observes `auto_watch=false`: it removes all watches
+ > before admitting any new refresh work.
+ > When `watcher_enabled=false`,
> `auto_watch` has no effect — there is no watcher to register with.
>
> They also differ in **when they are read**, which matters because the watcher
diff --cc src/cli/cli.c
index 5707c6e0c,587e25918..df29e41ea
--- a/src/cli/cli.c
+++ b/src/cli/cli.c
@@@ -7442,9 -8088,13 +8088,14 @@@ static const config_key_def_t CONFIG_KE
{CBM_CONFIG_AUTO_INDEX, "false", "Enable auto-indexing on MCP session start"},
{CBM_CONFIG_AUTO_INDEX_LIMIT, "50000", "Max files for auto-indexing new projects"},
{CBM_CONFIG_AUTO_WATCH, "true", "Register background git watcher on session connect"},
+ /* Unset: the index mode decides (cbm_pipeline_doc_candidates_enabled). */
+ {CBM_CONFIG_DOC_CANDIDATES, "auto",
+ "Doc-code candidates: auto = on for full, off for moderate/fast; true/false forces"},
{CBM_CONFIG_WATCHER_ENABLED, "true",
"Run the background watcher thread (auto-reindex); false to disable"},
+ {CBM_CONFIG_WATCH_NON_GIT, "false",
+ "Also poll non-git project roots for changes (file-tree scan); off by default"},
+ {CBM_CONFIG_INSTALL_HOOKS, "true", "Install managed client hooks"},
{CBM_CONFIG_UI_LANG, "auto", "Pin graph UI language: en, zh, or auto"},
{CBM_CONFIG_UI_ENABLED, "false", "Serve the graph UI on a loopback HTTP port"},
{CBM_CONFIG_UI_PORT, "9749", "Port for the graph UI listener when enabled"},
@@@ -9791,14 -10577,8 +10748,15 @@@ static void install_cli_agent_configs(c
plan_record("Codex CLI", "hook", hook_target);
} else {
bool hook_ok = true;
+ int pretool_written = 1;
- if (!dry_run && use_hooks_json) {
+ if (!g_install_hooks && !dry_run) {
+ int toml_result = cbm_reconcile_codex_hooks_command(
+ cp, command, command_windows, CBM_TOML_CODEX_HOOK_REMOVE, false);
+ int json_result = !cbm_file_exists(hooks_json)
+ ? CLI_OK
+ : cbm_remove_paired_lifecycle_hooks_json(hooks_json, command);
+ hook_ok = toml_result == CLI_OK && json_result == CLI_OK;
+ } else if (!dry_run && use_hooks_json) {
hook_ok =
cbm_upsert_paired_lifecycle_hooks_json(hooks_json, command, command_windows,
NULL, CMM_HOOK_TIMEOUT_SEC) == CLI_OK &&
@@@ -9805,16 -10587,19 +10765,23 @@@
cbm_reconcile_codex_hooks_command(cp, command, command_windows,
CBM_TOML_CODEX_HOOK_REMOVE, false) == CLI_OK;
} else if (!dry_run) {
- hook_ok = cbm_upsert_codex_hooks_command(cp, command, command_windows) == CLI_OK;
+ hook_ok = cbm_reconcile_codex_hooks_command_detailed(
+ cp, command, command_windows, CBM_TOML_CODEX_HOOK_UPSERT, false, NULL,
+ &pretool_written) == CLI_OK;
}
if (!hook_ok) {
- record_agent_config_error(false, "Codex CLI", "hook_install", hook_target);
+ record_agent_config_error(false, "Codex CLI",
+ g_install_hooks ? "hook_install" : "hook_disable",
+ hook_target);
+ } else if (!g_install_hooks) {
+ print_hooks_skipped();
} else {
- printf(" hooks: SessionStart + SubagentStart (dynamic graph context)\n");
+ printf(pretool_written
+ ? " hooks: SessionStart + SubagentStart + PreToolUse Bash (dynamic "
+ "graph context)\n"
+ : " hooks: SessionStart + SubagentStart (dynamic graph context); "
+ "PreToolUse skipped: config.toml already has an inline "
+ "hooks.PreToolUse\n");
printf(" note: non-managed hooks require /hooks trust; definition changes "
"require re-trust\n");
}
diff --cc src/cli/cli.h
index 98548d2dd,52ace9003..276124ee8
--- a/src/cli/cli.h
+++ b/src/cli/cli.h
@@@ -443,9 -526,10 +526,11 @@@ bool cbm_config_load_index_policy(cbm_c
#define CBM_CONFIG_AUTO_INDEX "auto_index"
#define CBM_CONFIG_AUTO_INDEX_LIMIT "auto_index_limit"
#define CBM_CONFIG_AUTO_WATCH "auto_watch"
+ #define CBM_CONFIG_DOC_CANDIDATES "doc_candidates"
+#define CBM_CONFIG_INSTALL_HOOKS "install_hooks"
#define CBM_CONFIG_UI_LANG "ui-lang"
#define CBM_CONFIG_WATCHER_ENABLED "watcher_enabled"
+ #define CBM_CONFIG_WATCH_NON_GIT "watch_non_git"
/* #1558: the graph UI's loopback listener. Stored in the UI config file rather
* than the key-value store, but surfaced through `config` so it is findable. */
#define CBM_CONFIG_UI_ENABLED "ui_enabled"
diff --cc src/main.c
index e9fb33c64,8824a805f..807cd66bc
--- a/src/main.c
+++ b/src/main.c
@@@ -1100,12 -1133,16 +1133,16 @@@ static void print_help(void)
"[args]\n");
printf(" Run one tool locally, then exit\n");
printf(" codebase-memory-mcp install [-y|-n] [--force] [--dry-run] "
- "[--dir=<path>] [--skip-config]\n");
+ "[--dir=<path>] [--skip-config] [--hooks|--no-hooks]\n");
printf(" [--clients=<tokens>] Run "
"'install --clients' to list tokens\n");
- printf(" codebase-memory-mcp uninstall [-y|-n] [--dry-run]\n");
+ printf(" codebase-memory-mcp uninstall [-y|-n] [--dry-run] [--delete-indexes]\n");
printf(" codebase-memory-mcp update [-y|-n]\n");
printf(" codebase-memory-mcp config <list|get|set|reset>\n");
+ printf(" codebase-memory-mcp daemon <start|stop|status>\n");
+ printf(" start keeps a daemon warm: CLI calls skip\n");
+ printf(" the per-command start-up, and hooks add\n");
+ printf(" graph context only while a daemon runs\n");
printf(" codebase-memory-mcp --version Print version\n");
printf(" codebase-memory-mcp --help Print this help\n");
printf("\nCLI output options:\n");
diff --cc tests/test_cli.c
index fcc8b9c76,f716418ad..484b30dfa
--- a/tests/test_cli.c
+++ b/tests/test_cli.c
@@@ -16459,10 -20156,9 +20428,11 @@@ SUITE(cli)
RUN_TEST(cli_install_force_quiesces_active_cohort_before_replacing_binary);
RUN_TEST(cli_install_dir_and_skip_config_stage_first_install_safely);
RUN_TEST(cli_activation_commands_reject_malformed_and_unknown_flags);
+ RUN_TEST(cli_install_hooks_preference_persists_and_migrates_owned_state);
+ RUN_TEST(cli_no_hooks_plan_covers_every_hook_installer_family);
RUN_TEST(cli_install_reset_deletion_waits_for_final_activation_guard);
RUN_TEST(cli_remove_indexes_deletes_orphan_sqlite_sidecars_issue2054);
+ RUN_TEST(cli_index_enumeration_skips_internal_cache_dbs);
RUN_TEST(cli_install_config_only_waits_for_cohort_drain);
RUN_TEST(cli_install_config_and_path_finish_before_guard_release);
RUN_TEST(cli_install_config_failure_keeps_published_binary);