release: v2.1.1 — index-first hooks

.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "codebase-index",
   "displayName": "Codebase Index",
   "description": "Give Claude a precise local map of your codebase: find implementations, trace behavior, and predict change impact with file-line evidence.",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "author": {
     "name": "codebase-index contributors"
   },

.claude/skills/codebase-index/.skill_version

@@ -1 +1 @@
-2.1.0
+2.1.1

.codex/skills/codebase-index/.skill_version

@@ -1 +1 @@
-2.1.0
+2.1.1

.opencode/skills/codebase-index/.skill_version

@@ -1 +1 @@
-2.1.0
+2.1.1

CHANGELOG.md

@@ -6,6 +6,24 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [2.1.1] - 2026-09-25
+
+### Added
+
+- `codebase-index install-hooks [--global]` makes Claude Code search through the index
+  by default. It merges two hooks into `.claude/settings.json` (or
+  `~/.claude/settings.json`), keeping every other hook:
+  - `SessionStart`: in an indexed repository, one line of context naming the commands
+    that answer code questions;
+  - `PreToolUse` on `Grep|Bash`: the first code search of a session, before any
+    `codebase-index` command has run, is sent back with the index command to use
+    instead. Repeating the same call lets it through, the first index command turns the
+    guard off for the session, and searches over docs, logs or config, pipelines such
+    as `ps | grep`, and directories without an index are never intercepted.
+    `CBX_GUARD=0` disables it; `install-hooks --uninstall` removes both hooks.
+  The hooks run as `codebase-index-hook`, a standard-library-only entry point (about
+  0.1 s per call). The Claude Code plugin registers the same hooks.
+
 ## [2.1.0] - 2026-09-24
 
 Agent-efficiency release. An agent answering five code questions on a 5.9k-file
@@ -868,7 +886,8 @@ Pooled over 305 queries (Python, Java, TypeScript), v1.8.0 → 1.9.0:
 - Hooks example + `watch` mode for keeping the index fresh without blocking the edit loop (M8).
 - `doctor`, `stats`, `clean` diagnostics/maintenance commands.
 
-[Unreleased]: https://github.com/denfry/codebase-index/compare/v2.1.0...HEAD
+[Unreleased]: https://github.com/denfry/codebase-index/compare/v2.1.1...HEAD
+[2.1.1]: https://github.com/denfry/codebase-index/compare/v2.1.0...v2.1.1
 [2.1.0]: https://github.com/denfry/codebase-index/compare/v2.0.0...v2.1.0
 [2.0.0]: https://github.com/denfry/codebase-index/compare/v1.9.0...v2.0.0
 [1.10.0]: https://github.com/denfry/codebase-index/compare/v1.9.0...abb67df

README.md

@@ -145,7 +145,10 @@ agent format: `path:start-end symbol` with the matching lines numbered underneat
 | **Any MCP client** (Claude Desktop, Cursor, VS Code, Zed, Windsurf, ...) | `pip install "codebase-index[mcp]"` then `codebase-index mcp --root /path/to/repo` | 11 tools (`search_code`, `find_refs`, `impact_of`, `impact_of_diff`, `path_between`, ...) with a versioned JSON envelope |
 | **Anything with a shell** | `codebase-index --json ...` | The same payloads as plain JSON, plus a local SQLite database you can query yourself |
 
-`init --target auto` detects which of these are present. See
+`init --target auto` detects which of these are present. To make Claude Code reach for
+the index before Grep in every indexed repository, run
+`codebase-index install-hooks --global`: a session-start note plus a guard that sends the
+first code search of a session to the index (repeat the call to run it anyway). See
 [INSTALLATION.md](docs/INSTALLATION.md) and [MCP.md](docs/MCP.md).
 
 ## Evidence

docs/installer.md

@@ -110,7 +110,7 @@ pwsh ./install.ps1 -Target claude -InstallDir "D:\skills\codebase-index"
 **Pin to a branch or tag** (reproducibility and safety):
 
 ```sh
-sh install.sh --branch v2.1.0
+sh install.sh --branch v2.1.1
 ```
 
 ---

hooks/hooks.json

@@ -6,6 +6,23 @@
           {
             "type": "command",
             "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/bootstrap.sh\""
+          },
+          {
+            "type": "command",
+            "command": "codebase-index-hook session-start 2>/dev/null || true",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Grep|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "codebase-index-hook guard 2>/dev/null || true",
+            "timeout": 5
           }
         ]
       }

pyproject.toml

@@ -57,6 +57,7 @@ build = ["build>=1.2", "twine>=5.0"]
 codebase-index = "codebase_index.cli:app"
 cbx = "codebase_index.cli:app"           # short alias
 codebase-index-mcp = "codebase_index.mcp.server:run"  # standalone MCP entry point
+codebase-index-hook = "codebase_index.hooks:main"  # Claude Code hooks (stdlib only, fast)
 
 [project.urls]
 Homepage = "https://github.com/denfry/codebase-index"

requirements.lock

@@ -1,3 +1,3 @@
-codebase-index @ https://github.com/denfry/codebase-index/archive/refs/tags/v2.1.0.tar.gz
+codebase-index @ https://github.com/denfry/codebase-index/archive/refs/tags/v2.1.1.tar.gz
 tree-sitter==0.25.2
 tree-sitter-language-pack==1.8.1

src/codebase_index/__init__.py

@@ -4,4 +4,4 @@
 See docs/ARCHITECTURE.md for the module map.
 """
 
-__version__ = "2.1.0"
+__version__ = "2.1.1"

src/codebase_index/cli.py

@@ -1064,6 +1064,41 @@ def watch(
         raise typer.Exit(code=1)
 
 
+@app.command("install-hooks")
+def install_hooks(
+    ctx: typer.Context,
+    global_: bool = typer.Option(
+        False, "--global", help="Install into ~/.claude/settings.json (every project)."
+    ),
+    uninstall: bool = typer.Option(False, "--uninstall", help="Remove the hooks instead."),
+) -> None:
+    """Make Claude Code search through the index by default.
+
+    Adds a SessionStart note and a PreToolUse guard on Grep/Bash: the first code
+    search of a session, before any codebase-index command, is sent back with the
+    index command to run instead; repeating it lets it through. Both do nothing in
+    a directory without an index. Other hooks in the settings file are kept.
+    """
+    from .config import find_root
+    from . import scaffold
+
+    if global_:
+        path = Path.home() / ".claude" / "settings.json"
+    else:
+        root_opt = ctx.obj.get("root") if ctx.obj else None
+        path = (Path(root_opt).resolve() if root_opt else find_root()) / scaffold.SETTINGS_REL
+    if uninstall:
+        changed = scaffold.uninstall_guard_hooks(path)
+        verb = "removed from"
+    else:
+        changed = scaffold.install_guard_hooks(path)
+        verb = "added to"
+    if changed:
+        typer.echo(f"[install-hooks] {', '.join(changed)} {verb} {path}")
+    else:
+        typer.echo(f"[install-hooks] nothing to change in {path}")
+
+
 @app.command("skill-update")
 def skill_update(
     ctx: typer.Context,