codebase-index 2.1.0__py3-none-any.whl → 2.1.2__py3-none-any.whl

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/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/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/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"

{codebase_index-2.1.0.dist-info → codebase_index-2.1.2.dist-info}/METADATA

@@ -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.dist-info → codebase_index-2.1.2.dist-info}/RECORD

@@ -1,10 +1,11 @@
-codebase_index/__init__.py,sha256=YXBNCFRX7GgcDfiGMhw8iEeH0kjn1qMQGF2xbKx1MtI,240
+codebase_index/__init__.py,sha256=pnBspkpuL4MUFufQ9vEX2aLCoarg52kQNO3dUB0zP6E,240
 codebase_index/__main__.py,sha256=wcCrL4PjG51r5wVKqJhcoJPTLfHW0wNbD31DrUN0MWI,28
-codebase_index/cli.py,sha256=cT1xLZZf2lwV5yPHRRzYWhLP_O8pZBTQd6FLeVHbo6s,43693
+codebase_index/cli.py,sha256=3HisRXo0yEyWp4X3PNE1mLoJcGdLr42o8mcnhUqKVxo,45052
 codebase_index/config.py,sha256=piyZ6zr2guEgMOPTJOabMLfk97be7sisTyXRVTdHvEk,4322
 codebase_index/doctor.py,sha256=ely35q-NNfGYtRbnyyDjM0Y2UZgJ5tl8iw1KCP2wzKM,6517
+codebase_index/hooks.py,sha256=MR3rNfuBWL60wK1jFo5lK0ZYlUlOSSEpwyWuPkv0kC0,10294
 codebase_index/models.py,sha256=v9dkcNYz2IsgSmuWqopp8JQ38seqWic9mNpO-nRpqCQ,5734
-codebase_index/scaffold.py,sha256=oMoT_uI6DhdM5dN9SLbnHnmbcB11YDqbOxTyaydt3_Y,14598
+codebase_index/scaffold.py,sha256=s-mwX_O1gsdXGByLA-AlFWcitnkZhQAIFNqW2xJTV4M,16867
 codebase_index/service.py,sha256=k9zm2IqF0qs0DVZau0P8s3FrgvosyiMsSrixpgrXIFs,18024
 codebase_index/skill_update.py,sha256=h8h_sDBXFklw5BSYbj4tuLp4O297nZWSXvEXsf7hiD8,4763
 codebase_index/discovery/__init__.py,sha256=ktlylA5XvkPsDtPDjaw8E4PVByedhfNY186B7T0bUmk,518
@@ -74,8 +75,8 @@ codebase_index/storage/repo.py,sha256=F6MQDo23zwXECb0lI40oZ6Mz-uH9EKwUvIsBEGK4C9
 codebase_index/storage/schema.sql,sha256=JSltVJebOmPxqA6rtP3-6TgTgGT0vQkQKLCt948njCc,5544
 codebase_index/watch/__init__.py,sha256=Mc--hdTGZlf7s7UrtZ8zAf35EGvxBY9paXcuVVzA-j4,242
 codebase_index/watch/watcher.py,sha256=f895qNBZkC6fCbEUWnxdpTH0Gy4RfFdg_hxLWJ9HZlc,3135
-codebase_index-2.1.0.dist-info/METADATA,sha256=PzEcmVAvNQ1z0rCSoSIOX9Nb0XZrnW14ntqgJgaBSSI,17187
-codebase_index-2.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
-codebase_index-2.1.0.dist-info/entry_points.txt,sha256=0UAH5H-m1dvx9a7aKnIA4G2r6Nf4U93i-5p_Fm3XUXo,138
-codebase_index-2.1.0.dist-info/licenses/LICENSE,sha256=UkoUuqQfpFu4eib8UkTVAraPFC44A7pAIS7Jb23fNu8,1084
-codebase_index-2.1.0.dist-info/RECORD,,
+codebase_index-2.1.2.dist-info/METADATA,sha256=ZrMCH9qRhCyC8VgCyAaZU2c5NXNFFmvCkES3Nj9TnuE,17442
+codebase_index-2.1.2.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+codebase_index-2.1.2.dist-info/entry_points.txt,sha256=TOy1PPDDP2vv0sd6skbkZFBxEDmEiSx0YspY0mF4fbI,186
+codebase_index-2.1.2.dist-info/licenses/LICENSE,sha256=UkoUuqQfpFu4eib8UkTVAraPFC44A7pAIS7Jb23fNu8,1084
+codebase_index-2.1.2.dist-info/RECORD,,

{codebase_index-2.1.0.dist-info → codebase_index-2.1.2.dist-info}/entry_points.txt

@@ -1,4 +1,5 @@
 [console_scripts]
 cbx = codebase_index.cli:app
 codebase-index = codebase_index.cli:app
+codebase-index-hook = codebase_index.hooks:main
 codebase-index-mcp = codebase_index.mcp.server:run