codebase-index 2.1.0__tar.gz → 2.1.2__tar.gz

codebase_index-2.1.2/.claude/skills/codebase-index/.skill_version

@@ -0,0 +1 @@
+2.1.2

{codebase_index-2.1.0 → codebase_index-2.1.2}/.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.2",
   "author": {
     "name": "codebase-index contributors"
   },

codebase_index-2.1.2/.codex/skills/codebase-index/.skill_version

@@ -0,0 +1 @@
+2.1.2

codebase_index-2.1.2/.opencode/skills/codebase-index/.skill_version

@@ -0,0 +1 @@
+2.1.2

{codebase_index-2.1.0 → codebase_index-2.1.2}/CHANGELOG.md

@@ -6,6 +6,40 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [2.1.2] - 2026-09-25
+
+### Fixed
+
+- The `PreToolUse` guard no longer blocks work it should let through:
+  - the first `codebase-index` command of a session turns the guard off even when it
+    is the command that builds the index; before, a repository without an index kept
+    the guard on for the whole session. Session state now lives in the system temp
+    directory (`CBX_HOOK_STATE` overrides it) instead of inside the index;
+  - heredoc bodies (`cat > script.ps1 <<'EOF'`, `python - <<EOF`) are file content, not
+    commands, and are no longer scanned for `grep`/`Select-String`;
+  - a retry is matched by its search term, not by the whole tool call, so a rewritten
+    command or a new description for the same search goes through;
+  - a quoted alternation such as `grep "a\|b"` is read whole, and a search on its own
+    line of a multi-line command is recognised.
+
+## [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 +902,9 @@ 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.2...HEAD
+[2.1.2]: https://github.com/denfry/codebase-index/compare/v2.1.1...v2.1.2
+[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

{codebase_index-2.1.0 → codebase_index-2.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codebase-index
-Version: 2.1.0
+Version: 2.1.2
 Summary: A precise local codebase map for AI coding agents: find, trace, and predict with file-line evidence.
 Project-URL: Homepage, https://github.com/denfry/codebase-index
 Project-URL: Documentation, https://github.com/denfry/codebase-index/tree/main/docs
@@ -195,7 +195,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

{codebase_index-2.1.0 → codebase_index-2.1.2}/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

{codebase_index-2.1.0 → codebase_index-2.1.2}/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.2
 ```
 
 ---

codebase_index-2.1.2/hooks/hooks.json

@@ -0,0 +1,31 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "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
+          }
+        ]
+      }
+    ]
+  }
+}

{codebase_index-2.1.0 → codebase_index-2.1.2}/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"

{codebase_index-2.1.0 → codebase_index-2.1.2}/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.2.tar.gz
 tree-sitter==0.25.2
 tree-sitter-language-pack==1.8.1

{codebase_index-2.1.0 → codebase_index-2.1.2}/src/codebase_index/__init__.py

@@ -4,4 +4,4 @@ Public surface is intentionally small; the CLI (`codebase_index.cli:app`) is the
 See docs/ARCHITECTURE.md for the module map.
 """
 
-__version__ = "2.1.0"
+__version__ = "2.1.2"

{codebase_index-2.1.0 → codebase_index-2.1.2}/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,

codebase_index-2.1.2/src/codebase_index/hooks.py

@@ -0,0 +1,272 @@
+"""Claude Code hooks that make the index the default way to search code.
+
+Two events, both no-ops outside a repository that has an index:
+
+- ``session-start`` adds one short note to the session context: this repository
+  is indexed, and which commands answer code questions.
+- ``guard`` (PreToolUse on Grep and Bash) intercepts a code search the first time
+  in a session, before any ``codebase-index`` command has run, and names the
+  index command to use instead. It is a nudge, not a wall: searching for the
+  same term again lets it through, the first ``codebase-index`` command in the
+  session turns the guard off (even one that has yet to build the index), and
+  searches over docs, logs or config, or inside heredoc bodies, are never
+  intercepted.
+
+Measured on a 5.9k-file monorepo, an agent spent 19% fewer tokens with the index
+than with grep (tests/eval/results/2026-09-24-agent-pilot.md), but agents reach
+for Grep out of habit. The guard runs on every Bash call, so this module imports
+only the standard library and does no index work beyond one small SQLite read.
+
+Entry point: ``codebase-index-hook <event>`` reads the hook JSON on stdin and
+prints the hook JSON reply (or nothing). ``CBX_GUARD=0`` disables the guard.
+Per-session state lives in the system temp directory (``CBX_HOOK_STATE``
+overrides it), so it exists before the repository has an index.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import sqlite3
+import sys
+import tempfile
+import time
+from pathlib import Path
+from typing import Any, Optional
+
+INDEX_REL = Path(".claude") / "cache" / "codebase-index" / "index.sqlite"
+_STATE_DIR = "codebase-index-hooks"
+_STATE_TTL_S = 2 * 24 * 3600
+
+# A shell segment that searches file contents: the first command of the segment
+# (after `&&`, `||`, `;`, a newline or the start), so `ps aux | grep x` is not a
+# repo search. Quoted arguments may hold `|`, as in grep "a\|b".
+_SEARCH_CMD = re.compile(
+    r"(?:^|&&|\|\||;|\n)[ \t]*(?:cd\s+\S+\s*&&\s*)?"
+    r"(?P<cmd>git\s+grep|grep|egrep|fgrep|rg|ag|ack|findstr|Select-String)\b"
+    r"""(?P<args>(?:"[^"\n]*"|'[^'\n]*'|[^|;&\n"'])*)""",
+    re.IGNORECASE,
+)
+# A heredoc body is file content (a script being written, stdin for python), not
+# commands; an unterminated one runs to the end of the command.
+_HEREDOC = re.compile(
+    r"""(?<!<)<<-?(?!<)[ \t]*(['"]?)([A-Za-z_][\w-]*)\1(?P<rest>[^\n]*)\n"""
+    r".*?(?:^[ \t]*\2[ \t]*$|\Z)",
+    re.DOTALL | re.MULTILINE,
+)
+_INDEX_CMD = re.compile(r"(?:^|[\s;&|/\\\"'])(?:codebase-index|cbx)(?:\.exe|\.ps1)?\s+\w")
+# Searches over prose, logs and config are what grep is for; leave them alone.
+_NON_CODE = re.compile(
+    r"\.(?:md|mdx|rst|txt|log|ya?ml|json|toml|ini|cfg|conf|csv|xml|properties|lock|env|html?)\b"
+    r"|--include=\*?\.(?:md|txt|log|ya?ml|json|toml)",
+    re.IGNORECASE,
+)
+_NON_CODE_TYPES = {"md", "markdown", "txt", "log", "yaml", "yml", "json", "toml", "xml",
+                   "csv", "ini", "config"}
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    args = sys.argv[1:] if argv is None else argv
+    event = args[0] if args else ""
+    try:
+        payload = json.loads(sys.stdin.read() or "{}")
+    except (ValueError, OSError):
+        return 0
+    try:
+        reply = {"guard": guard, "session-start": session_start}.get(event, _none)(payload)
+    except Exception:  # a hook must never break the session it runs in
+        return 0
+    if reply:
+        sys.stdout.write(json.dumps(reply))
+    return 0
+
+
+def _none(_payload: dict) -> Optional[dict]:
+    return None
+
+
+def find_index_root(start: Path) -> Optional[Path]:
+    """The nearest directory at or above `start` that holds an index."""
+    for path in (start, *start.parents):
+        if (path / INDEX_REL).is_file():
+            return path
+    return None
+
+
+def _cwd(payload: dict) -> Path:
+    raw = str(payload.get("cwd") or os.getcwd())
+    # Git Bash hands out MSYS paths (/c/Projects/x); Python on Windows needs C:/.
+    msys = re.match(r"^/([a-zA-Z])(/.*)?$", raw)
+    if os.name == "nt" and msys:
+        raw = f"{msys.group(1)}:{msys.group(2) or '/'}"
+    return Path(raw)
+
+
+# --- session-start ------------------------------------------------------------------
+
+
+def session_start(payload: dict) -> Optional[dict]:
+    root = find_index_root(_cwd(payload))
+    if root is None:
+        return None
+    files = _indexed_files(root)
+    size = f" ({files} files)" if files else ""
+    note = (
+        f"This repository has a codebase-index index{size}. For questions about the "
+        "code (where something is, how it works, who calls it, what a change breaks) "
+        "use the codebase-index skill before Grep or Read: "
+        '`codebase-index search "<question>" --compact`, '
+        '`codebase-index refs "Owner.member" --compact`, '
+        '`codebase-index impact "Owner.member" --compact`. '
+        "Output lines are numbered; cite them as file:line."
+    )
+    return {"hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": note}}
+
+
+def _indexed_files(root: Path) -> Optional[int]:
+    try:
+        conn = sqlite3.connect(f"file:{root / INDEX_REL}?mode=ro", uri=True, timeout=0.5)
+        try:
+            return int(conn.execute("SELECT COUNT(*) FROM files").fetchone()[0])
+        finally:
+            conn.close()
+    except sqlite3.Error:
+        return None
+
+
+# --- guard ------------------------------------------------------------------------------
+
+
+def guard(payload: dict) -> Optional[dict]:
+    if os.environ.get("CBX_GUARD", "").strip() == "0":
+        return None
+    tool = payload.get("tool_name") or ""
+    tool_input = payload.get("tool_input") or {}
+    if tool not in ("Grep", "Bash"):
+        return None
+    state = _State(str(payload.get("session_id") or "default"))
+
+    if tool == "Bash":
+        command = _HEREDOC.sub(lambda m: "<<" + m.group("rest"), str(tool_input.get("command") or ""))
+        if _INDEX_CMD.search(command):
+            # Checked before the index exists: the first search is what builds it.
+            state.mark_used()
+            return None
+        pattern = _shell_search_pattern(command)
+        if pattern is None:
+            return None
+    else:
+        if _grep_targets_non_code(tool_input):
+            return None
+        pattern = str(tool_input.get("pattern") or "")
+
+    if state.used or find_index_root(_cwd(payload)) is None:
+        return None
+    # Keyed by the search term, not the whole call: a retry rarely repeats the
+    # command byte for byte (a new description, another pipe, a regenerated script).
+    fingerprint = hashlib.sha1(_term(pattern).lower().encode("utf-8")).hexdigest()
+    if state.was_denied(fingerprint):
+        return None  # the retry after a nudge: the agent decided grep is right
+    state.deny(fingerprint)
+    return {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": _reason(pattern),
+        }
+    }
+
+
+def _shell_search_pattern(command: str) -> Optional[str]:
+    """The search term of a content search in `command`, or None if there is none."""
+    for match in _SEARCH_CMD.finditer(command):
+        args = match.group("args")
+        if _NON_CODE.search(args):
+            continue
+        quoted = re.search(r"""(['"])(.+?)\1""", args)
+        if quoted:
+            return quoted.group(2)
+        words = [w for w in args.split() if not w.startswith("-")]
+        return words[0] if words else ""
+    return None
+
+
+def _grep_targets_non_code(tool_input: dict) -> bool:
+    kind = str(tool_input.get("type") or "").lower()
+    if kind in _NON_CODE_TYPES:
+        return True
+    target = f"{tool_input.get('glob') or ''} {tool_input.get('path') or ''}"
+    return bool(_NON_CODE.search(target))
+
+
+def _term(pattern: str) -> str:
+    """A regex search pattern as plain query words."""
+    return " ".join(re.sub(r"""[\\^$()\[\]{}|*+?"']""", " ", pattern).split())[:80]
+
+
+def _reason(pattern: str) -> str:
+    term = _term(pattern) or "<what you are looking for>"
+    return (
+        "codebase-index: this repository is indexed, and the index answers code "
+        "searches with ranked, numbered lines in fewer tokens than grep. Run it first:\n"
+        f'  codebase-index search "{term}" --compact     # where / how\n'
+        '  codebase-index refs "Owner.member" --compact  # every call site, with callers\n'
+        '  codebase-index symbol "Name"                 # a definition\n'
+        "If the index does not answer, search for the same term again and it will run. "
+        "Once any codebase-index command has run in this session, searches are not "
+        "intercepted."
+    )
+
+
+class _State:
+    """Per-session guard state: whether the index was used, which calls were nudged."""
+
+    def __init__(self, session: str) -> None:
+        safe = re.sub(r"[^A-Za-z0-9_.-]", "_", session)[:80] or "default"
+        self.dir = Path(os.environ.get("CBX_HOOK_STATE") or Path(tempfile.gettempdir()) / _STATE_DIR)
+        self.path = self.dir / f"{safe}.json"
+        self.data: dict[str, Any] = {"used": False, "denied": []}
+        try:
+            self.data.update(json.loads(self.path.read_text(encoding="utf-8")))
+        except (OSError, ValueError):
+            pass
+
+    @property
+    def used(self) -> bool:
+        return bool(self.data.get("used"))
+
+    def was_denied(self, fingerprint: str) -> bool:
+        return fingerprint in self.data.get("denied", [])
+
+    def mark_used(self) -> None:
+        if not self.used:
+            self.data["used"] = True
+            self._save()
+
+    def deny(self, fingerprint: str) -> None:
+        self.data.setdefault("denied", []).append(fingerprint)
+        self._save()
+
+    def _save(self) -> None:
+        try:
+            self.dir.mkdir(parents=True, exist_ok=True)
+            self.path.write_text(json.dumps(self.data), encoding="utf-8")
+            _prune(self.dir)
+        except OSError:
+            pass
+
+
+def _prune(directory: Path) -> None:
+    cutoff = time.time() - _STATE_TTL_S
+    for item in directory.glob("*.json"):
+        try:
+            if item.stat().st_mtime < cutoff:
+                item.unlink()
+        except OSError:
+            pass
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{codebase_index-2.1.0 → codebase_index-2.1.2}/src/codebase_index/scaffold.py

@@ -283,6 +283,67 @@ def merge_hook_settings(root: Path) -> bool:
     return True
 
 
+# Index-first hooks (hooks.py): a SessionStart note and a PreToolUse guard that
+# steers the first code search of a session to the index.
+_GUARD_MARKER = "codebase-index-hook"
+GUARD_HOOKS: dict[str, dict] = {
+    "SessionStart": {
+        "hooks": [{"type": "command", "command": "codebase-index-hook session-start",
+                   "timeout": 5}],
+    },
+    "PreToolUse": {
+        "matcher": "Grep|Bash",
+        "hooks": [{"type": "command", "command": "codebase-index-hook guard", "timeout": 5}],
+    },
+}
+
+
+def _is_guard_entry(entry: dict) -> bool:
+    return any(_GUARD_MARKER in str(h.get("command", "")) for h in entry.get("hooks", []))
+
+
+def install_guard_hooks(settings_path: Path) -> list[str]:
+    """Merge the index-first hooks into a Claude Code settings file.
+
+    Idempotent, and leaves every other hook in place. Returns the events added.
+    """
+    settings: dict = {}
+    if settings_path.exists():
+        settings = json.loads(settings_path.read_text(encoding="utf-8") or "{}")
+    hooks = settings.setdefault("hooks", {})
+    added = []
+    for event, entry in GUARD_HOOKS.items():
+        entries = hooks.setdefault(event, [])
+        if not any(_is_guard_entry(e) for e in entries):
+            entries.append(json.loads(json.dumps(entry)))
+            added.append(event)
+    if added:
+        settings_path.parent.mkdir(parents=True, exist_ok=True)
+        settings_path.write_text(json.dumps(settings, indent=2) + "\n", encoding="utf-8")
+    return added
+
+
+def uninstall_guard_hooks(settings_path: Path) -> list[str]:
+    """Remove the index-first hooks; other hooks are kept. Returns the events changed."""
+    if not settings_path.exists():
+        return []
+    settings = json.loads(settings_path.read_text(encoding="utf-8") or "{}")
+    hooks = settings.get("hooks", {})
+    removed = []
+    for event in GUARD_HOOKS:
+        entries = hooks.get(event, [])
+        kept = [e for e in entries if not _is_guard_entry(e)]
+        if len(kept) != len(entries):
+            removed.append(event)
+            if kept:
+                hooks[event] = kept
+            else:
+                hooks.pop(event, None)
+    if removed:
+        settings_path.write_text(json.dumps(settings, indent=2) + "\n", encoding="utf-8")
+    return removed
+
+
 # ── MCP client config helpers ──────────────────────────────────────────────────────────────────
 
 _MCP_SERVER_NAME = "codebase-index"