graphscout 0.2.0__tar.gz

graphscout-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: pip install -e ".[dev,mcp,watch]"
+      - name: Test
+        run: pytest -v

graphscout-0.2.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.pytest_cache/
+.cache/

graphscout-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Duc Nguyen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

graphscout-0.2.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: graphscout
+Version: 0.2.0
+Summary: Cached, incremental code-graph maps so AI agents query code structure instead of reading whole files. CLI + MCP server, wires into Claude Code, Codex, Gemini CLI, and Cursor. Auto-sync watch mode.
+Project-URL: Homepage, https://github.com/nguyenminhduc9988/graphscout
+Project-URL: Repository, https://github.com/nguyenminhduc9988/graphscout
+Project-URL: Issues, https://github.com/nguyenminhduc9988/graphscout/issues
+Author: Duc Nguyen
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,claude-code,code-graph,codebase-map,mcp,static-analysis,token-efficiency,tree-sitter
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: graphifyy>=0.9
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == 'mcp'
+Provides-Extra: watch
+Requires-Dist: watchdog>=4.0; extra == 'watch'
+Description-Content-Type: text/markdown
+
+# graphscout
+
+**Cached, incremental code-graph maps so AI agents query code structure instead of reading whole files.**
+
+Agents burn most of their tokens reading source files to answer structural questions — "where is this defined?", "who calls this?", "what does this file import?". `graphscout` answers those questions from a cached tree-sitter AST graph in milliseconds, so the agent reads only the exact line ranges it needs.
+
+```
+$ graphscout sym cli_fallback
+CLIFallback  [class]  agent/cli_fallback.py:24-210
+run_cascade  [function]  agent/cli_fallback.py:96-158
+
+$ graphscout callers run_cascade
+handle_turn  [function]  agent/loop.py:311-360
+retry_turn   [function]  agent/loop.py:402-431
+```
+
+One `build` per repo; after that, every query auto-refreshes only the files that changed since the last call (mtime-based). No forced background process, no database, no API keys — a JSON cache under `~/.cache/graphscout`. Want it always fresh with zero per-query overhead instead? Run `graphscout watch` — see [Auto-sync](#auto-sync-optional).
+
+> Formerly published as `codegraph-kit` (repo `codegraph`) — renamed to avoid confusion with the unrelated, much larger [colbymchenry/codegraph](https://github.com/colbymchenry/codegraph) project. Same tool, same cache format (`$CODEGRAPH_CACHE` still works as a fallback env var).
+
+## Install
+
+```bash
+pip install graphscout          # CLI
+pip install "graphscout[mcp]"   # CLI + MCP server
+pip install "graphscout[watch]" # CLI + instant filesystem-event auto-sync
+```
+
+Python ≥ 3.10. Parsing is done by [graphify](https://pypi.org/project/graphifyy/) (tree-sitter), which extracts real defs/calls/imports for Python, JavaScript, TypeScript/TSX, Java, Groovy, C, C++, Ruby, C#, Kotlin, Scala, PHP, Lua, and Swift, and walks 40+ other extensions (Go, Rust, Vue, Svelte, Astro, Dart, Elixir, Terraform, and more) for outline/import-level structure.
+
+## Commands
+
+| Command | What it answers |
+|---|---|
+| `graphscout build [dir]` | full graph build (run once per repo) |
+| `graphscout map [dir]` | repo overview: size, per-directory breakdown, top hub symbols |
+| `graphscout file <path>` | outline of one file: definitions + line ranges |
+| `graphscout sym <name>` | where is this symbol defined? |
+| `graphscout callers <name>` | who calls it? |
+| `graphscout callees <name>` | what does it call? |
+| `graphscout deps <path>` | what does this file import? |
+| `graphscout ensure [dir]` | incremental refresh (queries do this automatically) |
+| `graphscout watch [dir]` | block, keeping the graph in sync as files change |
+| `graphscout touch <path>` | re-extract one file (for editor/agent hooks) |
+| `graphscout agent` | print an instruction snippet for your agent's context file |
+| `graphscout install [agent...]` | wire the MCP server into detected agents |
+| `graphscout uninstall [agent...]` | remove it again |
+| `graphscout mcp` | run as an MCP server (stdio) |
+
+## Integrate with any agent
+
+`graphscout` is plain CLI-over-stdout, so **any agent that can run shell commands can use it** — Claude Code, Codex CLI, Cursor, Aider, OpenHands, Goose, custom agents. Two steps:
+
+**1. Tell the agent the graph exists.** Append the ready-made snippet to your agent's context file:
+
+```bash
+graphscout agent >> AGENTS.md      # or CLAUDE.md, .cursorrules, .github/copilot-instructions.md
+```
+
+**2. (Optional) Keep the graph fresh on every edit.** For Claude Code, install the bundled PostToolUse hook so each `Edit`/`Write` re-extracts just that file:
+
+```bash
+cp integrations/claude-code/graphscout-touch.sh ~/.claude/hooks/
+chmod +x ~/.claude/hooks/graphscout-touch.sh
+# then merge integrations/claude-code/settings-snippet.json into ~/.claude/settings.json
+```
+
+Even without a hook, queries stay correct: every query runs an mtime check first and re-extracts anything stale.
+
+### MCP, wired automatically
+
+```bash
+pip install "graphscout[mcp]"
+graphscout install          # auto-detects and wires every agent found on PATH
+graphscout install cursor   # or target specific agents: claude-code, codex, gemini, cursor
+graphscout uninstall        # reverse it
+```
+
+`install` shells out to each agent's own `mcp add` command where one exists (Claude Code, Codex CLI, Gemini CLI — verified against their real CLIs, not guessed), and edits `~/.cursor/mcp.json` directly for Cursor, which has no such subcommand. It's idempotent — safe to re-run.
+
+Tools exposed: `build_graph`, `graph_map`, `file_outline`, `find_symbol`, `callers`, `callees`, `file_deps` — same output as the CLI.
+
+### Auto-sync (optional)
+
+```bash
+graphscout watch          # blocks, keeps the graph in sync as you/your agent edit files
+```
+
+Uses [watchdog](https://pypi.org/project/watchdog/) for instant, low-CPU filesystem events when installed (`pip install "graphscout[watch]"`); falls back to a ~1.5s mtime poll otherwise. This is the always-fresh alternative to the per-edit `touch` hook above — run one or the other, not both. Skip both and every query still self-heals via its own mtime check; `watch` just removes that per-query overhead.
+
+## Why not just let the agent read files?
+
+Reading a 1,500-line file to find one function costs ~15k tokens; `graphscout file` returns the outline in ~200 tokens, and the agent then reads only the 40-line range it needs. On large repos the difference compounds — structural questions (symbol lookup, call tracing, import mapping) stop costing file-reads entirely.
+
+Honest limitations, printed in the output when they apply:
+
+- **Dynamic dispatch isn't captured** — call edges come from static AST analysis; `getattr`-style calls need grep.
+- **Unsupported/exotic languages** fall back to "read it directly".
+- Caps: 5,000 files per repo, 1 MB per file (warned, not silent).
+
+## How it works
+
+1. `build` walks the repo (skipping `node_modules`, `venv`, `dist`, …), runs tree-sitter extraction via graphify, normalizes all paths root-relative, and writes `graph.json` + an mtime index to `~/.cache/graphscout/<repo-hash>/`.
+2. Every query calls `ensure` first: files whose mtime changed are re-extracted and spliced into the graph; deleted files are dropped. Typical refresh is a handful of files, so queries stay fast. `watch` does the same refresh on a timer/event loop instead of per-query.
+3. Output is deliberately plain text with `file:line` locations — clickable in most agent UIs and trivially parseable.
+
+Set `GRAPHSCOUT_CACHE` to relocate the cache (useful in CI and sandboxes).
+
+## License
+
+MIT

graphscout-0.2.0/README.md

@@ -0,0 +1,111 @@
+# graphscout
+
+**Cached, incremental code-graph maps so AI agents query code structure instead of reading whole files.**
+
+Agents burn most of their tokens reading source files to answer structural questions — "where is this defined?", "who calls this?", "what does this file import?". `graphscout` answers those questions from a cached tree-sitter AST graph in milliseconds, so the agent reads only the exact line ranges it needs.
+
+```
+$ graphscout sym cli_fallback
+CLIFallback  [class]  agent/cli_fallback.py:24-210
+run_cascade  [function]  agent/cli_fallback.py:96-158
+
+$ graphscout callers run_cascade
+handle_turn  [function]  agent/loop.py:311-360
+retry_turn   [function]  agent/loop.py:402-431
+```
+
+One `build` per repo; after that, every query auto-refreshes only the files that changed since the last call (mtime-based). No forced background process, no database, no API keys — a JSON cache under `~/.cache/graphscout`. Want it always fresh with zero per-query overhead instead? Run `graphscout watch` — see [Auto-sync](#auto-sync-optional).
+
+> Formerly published as `codegraph-kit` (repo `codegraph`) — renamed to avoid confusion with the unrelated, much larger [colbymchenry/codegraph](https://github.com/colbymchenry/codegraph) project. Same tool, same cache format (`$CODEGRAPH_CACHE` still works as a fallback env var).
+
+## Install
+
+```bash
+pip install graphscout          # CLI
+pip install "graphscout[mcp]"   # CLI + MCP server
+pip install "graphscout[watch]" # CLI + instant filesystem-event auto-sync
+```
+
+Python ≥ 3.10. Parsing is done by [graphify](https://pypi.org/project/graphifyy/) (tree-sitter), which extracts real defs/calls/imports for Python, JavaScript, TypeScript/TSX, Java, Groovy, C, C++, Ruby, C#, Kotlin, Scala, PHP, Lua, and Swift, and walks 40+ other extensions (Go, Rust, Vue, Svelte, Astro, Dart, Elixir, Terraform, and more) for outline/import-level structure.
+
+## Commands
+
+| Command | What it answers |
+|---|---|
+| `graphscout build [dir]` | full graph build (run once per repo) |
+| `graphscout map [dir]` | repo overview: size, per-directory breakdown, top hub symbols |
+| `graphscout file <path>` | outline of one file: definitions + line ranges |
+| `graphscout sym <name>` | where is this symbol defined? |
+| `graphscout callers <name>` | who calls it? |
+| `graphscout callees <name>` | what does it call? |
+| `graphscout deps <path>` | what does this file import? |
+| `graphscout ensure [dir]` | incremental refresh (queries do this automatically) |
+| `graphscout watch [dir]` | block, keeping the graph in sync as files change |
+| `graphscout touch <path>` | re-extract one file (for editor/agent hooks) |
+| `graphscout agent` | print an instruction snippet for your agent's context file |
+| `graphscout install [agent...]` | wire the MCP server into detected agents |
+| `graphscout uninstall [agent...]` | remove it again |
+| `graphscout mcp` | run as an MCP server (stdio) |
+
+## Integrate with any agent
+
+`graphscout` is plain CLI-over-stdout, so **any agent that can run shell commands can use it** — Claude Code, Codex CLI, Cursor, Aider, OpenHands, Goose, custom agents. Two steps:
+
+**1. Tell the agent the graph exists.** Append the ready-made snippet to your agent's context file:
+
+```bash
+graphscout agent >> AGENTS.md      # or CLAUDE.md, .cursorrules, .github/copilot-instructions.md
+```
+
+**2. (Optional) Keep the graph fresh on every edit.** For Claude Code, install the bundled PostToolUse hook so each `Edit`/`Write` re-extracts just that file:
+
+```bash
+cp integrations/claude-code/graphscout-touch.sh ~/.claude/hooks/
+chmod +x ~/.claude/hooks/graphscout-touch.sh
+# then merge integrations/claude-code/settings-snippet.json into ~/.claude/settings.json
+```
+
+Even without a hook, queries stay correct: every query runs an mtime check first and re-extracts anything stale.
+
+### MCP, wired automatically
+
+```bash
+pip install "graphscout[mcp]"
+graphscout install          # auto-detects and wires every agent found on PATH
+graphscout install cursor   # or target specific agents: claude-code, codex, gemini, cursor
+graphscout uninstall        # reverse it
+```
+
+`install` shells out to each agent's own `mcp add` command where one exists (Claude Code, Codex CLI, Gemini CLI — verified against their real CLIs, not guessed), and edits `~/.cursor/mcp.json` directly for Cursor, which has no such subcommand. It's idempotent — safe to re-run.
+
+Tools exposed: `build_graph`, `graph_map`, `file_outline`, `find_symbol`, `callers`, `callees`, `file_deps` — same output as the CLI.
+
+### Auto-sync (optional)
+
+```bash
+graphscout watch          # blocks, keeps the graph in sync as you/your agent edit files
+```
+
+Uses [watchdog](https://pypi.org/project/watchdog/) for instant, low-CPU filesystem events when installed (`pip install "graphscout[watch]"`); falls back to a ~1.5s mtime poll otherwise. This is the always-fresh alternative to the per-edit `touch` hook above — run one or the other, not both. Skip both and every query still self-heals via its own mtime check; `watch` just removes that per-query overhead.
+
+## Why not just let the agent read files?
+
+Reading a 1,500-line file to find one function costs ~15k tokens; `graphscout file` returns the outline in ~200 tokens, and the agent then reads only the 40-line range it needs. On large repos the difference compounds — structural questions (symbol lookup, call tracing, import mapping) stop costing file-reads entirely.
+
+Honest limitations, printed in the output when they apply:
+
+- **Dynamic dispatch isn't captured** — call edges come from static AST analysis; `getattr`-style calls need grep.
+- **Unsupported/exotic languages** fall back to "read it directly".
+- Caps: 5,000 files per repo, 1 MB per file (warned, not silent).
+
+## How it works
+
+1. `build` walks the repo (skipping `node_modules`, `venv`, `dist`, …), runs tree-sitter extraction via graphify, normalizes all paths root-relative, and writes `graph.json` + an mtime index to `~/.cache/graphscout/<repo-hash>/`.
+2. Every query calls `ensure` first: files whose mtime changed are re-extracted and spliced into the graph; deleted files are dropped. Typical refresh is a handful of files, so queries stay fast. `watch` does the same refresh on a timer/event loop instead of per-query.
+3. Output is deliberately plain text with `file:line` locations — clickable in most agent UIs and trivially parseable.
+
+Set `GRAPHSCOUT_CACHE` to relocate the cache (useful in CI and sandboxes).
+
+## License
+
+MIT

graphscout-0.2.0/integrations/claude-code/graphscout-touch.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# Claude Code PostToolUse hook (Edit|Write, async): keep code graphs fresh —
+# re-extract the edited file into its repo's graphscout cache.
+# No-op when the repo has no graph yet, so it's safe to install globally.
+set -uo pipefail
+FP=$(jq -r '.tool_input.file_path // .tool_response.filePath // empty')
+[[ -z "$FP" || ! -f "$FP" ]] && exit 0
+case "${FP##*.}" in
+  py|js|jsx|mjs|ts|tsx|vue|svelte|astro|go|rs|zig|java|groovy|kt|kts|scala|\
+  c|h|cpp|cc|cxx|hpp|cs|rb|php|swift|m|mm|lua|dart|ex|exs|jl|r|v|sv|sh|bash|ps1|tf) ;;
+  *) exit 0 ;;
+esac
+exec graphscout touch "$FP" 2>/dev/null

graphscout-0.2.0/integrations/claude-code/settings-snippet.json

@@ -0,0 +1,17 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/graphscout-touch.sh",
+            "timeout": 60,
+            "async": true
+          }
+        ]
+      }
+    ]
+  }
+}

graphscout-0.2.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "graphscout"
+version = "0.2.0"
+description = "Cached, incremental code-graph maps so AI agents query code structure instead of reading whole files. CLI + MCP server, wires into Claude Code, Codex, Gemini CLI, and Cursor. Auto-sync watch mode."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Duc Nguyen" }]
+keywords = ["ai-agents", "code-graph", "tree-sitter", "claude-code", "mcp", "token-efficiency", "codebase-map", "static-analysis"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = [
+    "graphifyy>=0.9",
+]
+
+[project.optional-dependencies]
+mcp = ["mcp>=1.0"]
+watch = ["watchdog>=4.0"]
+dev = ["pytest>=8", "build", "twine"]
+
+[project.scripts]
+graphscout = "graphscout.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/nguyenminhduc9988/graphscout"
+Repository = "https://github.com/nguyenminhduc9988/graphscout"
+Issues = "https://github.com/nguyenminhduc9988/graphscout/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/graphscout"]

graphscout-0.2.0/src/graphscout/__init__.py

@@ -0,0 +1,4 @@
+"""graphscout — cached, incremental code-graph maps so AI agents query structure
+instead of reading whole files."""
+
+__version__ = "0.2.0"

graphscout-0.2.0/src/graphscout/agents.py

@@ -0,0 +1,134 @@
+"""Wire the graphscout MCP server into agent CLIs, and remove it again.
+
+Each agent is either:
+  - "cli": has its own `<tool> mcp add/remove <name> -- <command> [args]`
+    subcommand, which we shell out to (most robust — we never guess at that
+    tool's own config file format or schema).
+  - "json": no MCP-management subcommand, so we edit its documented MCP
+    config file directly (mcpServers.<name> = {command, args}).
+
+Only agents whose registration mechanism was verified against the real CLI
+(or a stable, documented config schema) are listed here — silently guessing
+at an unverified format would ship a broken integration, which is worse than
+not shipping one.
+"""
+import json
+import shutil
+import subprocess
+from pathlib import Path
+
+SERVER_NAME = "graphscout"
+SERVER_CMD = ["graphscout", "mcp"]
+
+AGENTS = {
+    "claude-code": {
+        "kind": "cli",
+        "binary": "claude",
+        "add": lambda b: [b, "mcp", "add", SERVER_NAME, "-s", "user", "--", *SERVER_CMD],
+        "remove": lambda b: [b, "mcp", "remove", SERVER_NAME, "-s", "user"],
+    },
+    "codex": {
+        "kind": "cli",
+        "binary": "codex",
+        "add": lambda b: [b, "mcp", "add", SERVER_NAME, "--", *SERVER_CMD],
+        "remove": lambda b: [b, "mcp", "remove", SERVER_NAME],
+    },
+    "gemini": {
+        "kind": "cli",
+        "binary": "gemini",
+        "add": lambda b: [b, "mcp", "add", "-s", "user", SERVER_NAME, *SERVER_CMD],
+        "remove": lambda b: [b, "mcp", "remove", "-s", "user", SERVER_NAME],
+    },
+    "cursor": {
+        "kind": "json",
+        "path": Path.home() / ".cursor" / "mcp.json",
+    },
+}
+
+
+def detect() -> dict:
+    """Which configured agents are actually present on this machine."""
+    out = {}
+    for name, spec in AGENTS.items():
+        if spec["kind"] == "cli":
+            out[name] = shutil.which(spec["binary"]) is not None
+        else:
+            # A json-config agent counts as "present" if its config dir's
+            # parent exists (e.g. ~/.cursor) — the file itself may not yet.
+            out[name] = spec["path"].parent.exists()
+    return out
+
+
+def _run(argv):
+    try:
+        r = subprocess.run(argv, capture_output=True, text=True, timeout=20)
+        return r.returncode == 0, (r.stdout + r.stderr).strip()
+    except (OSError, subprocess.SubprocessError) as e:
+        return False, str(e)
+
+
+def _json_install(path: Path):
+    path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        cfg = json.loads(path.read_text()) if path.exists() else {}
+    except json.JSONDecodeError:
+        return f"skip {path} — not valid JSON, edit it by hand"
+    cfg.setdefault("mcpServers", {})[SERVER_NAME] = {"command": SERVER_CMD[0], "args": SERVER_CMD[1:]}
+    path.write_text(json.dumps(cfg, indent=2) + "\n")
+    return f"wired {path}"
+
+
+def _json_uninstall(path: Path):
+    if not path.exists():
+        return f"skip {path} — not present"
+    try:
+        cfg = json.loads(path.read_text())
+    except json.JSONDecodeError:
+        return f"skip {path} — not valid JSON, edit it by hand"
+    removed = cfg.get("mcpServers", {}).pop(SERVER_NAME, None) is not None
+    path.write_text(json.dumps(cfg, indent=2) + "\n")
+    return f"removed from {path}" if removed else f"not present in {path}"
+
+
+def install(names=None) -> list:
+    present = detect()
+    targets = names or [n for n, ok in present.items() if ok]
+    log = []
+    for name in targets:
+        spec = AGENTS.get(name)
+        if not spec:
+            log.append(f"unknown agent: {name}")
+            continue
+        if not present.get(name) and not names:
+            continue  # auto mode: skip agents that aren't installed
+        if spec["kind"] == "cli":
+            b = shutil.which(spec["binary"])
+            if not b:
+                log.append(f"skip {name} — `{spec['binary']}` not on PATH")
+                continue
+            _run(spec["remove"](b))  # idempotent: clear any stale entry first
+            ok, msg = _run(spec["add"](b))
+            log.append(f"{'wired' if ok else 'FAILED'} {name}" + (f" — {msg}" if not ok else ""))
+        else:
+            log.append(_json_install(spec["path"]))
+    return log
+
+
+def uninstall(names=None) -> list:
+    targets = names or list(AGENTS)
+    log = []
+    for name in targets:
+        spec = AGENTS.get(name)
+        if not spec:
+            log.append(f"unknown agent: {name}")
+            continue
+        if spec["kind"] == "cli":
+            b = shutil.which(spec["binary"])
+            if not b:
+                log.append(f"skip {name} — `{spec['binary']}` not on PATH")
+                continue
+            ok, msg = _run(spec["remove"](b))
+            log.append(f"{'removed' if ok else 'not present'} {name}")
+        else:
+            log.append(_json_uninstall(spec["path"]))
+    return log

graphscout-0.2.0/src/graphscout/cli.py

@@ -0,0 +1,125 @@
+"""graphscout — cached, incremental code-graph maps so agents query structure
+instead of reading whole files. Backed by graphify (tree-sitter AST extraction).
+
+  graphscout build [dir]          full graph build (registers repo root)
+  graphscout ensure [dir]         incremental refresh (only changed files re-extracted)
+  graphscout watch [dir]          block, keeping the graph in sync as files change
+  graphscout map [dir]            compact overview: counts, per-dir breakdown, top hubs
+  graphscout file <path>          outline of one file (defs + line ranges -> sliced reads)
+  graphscout sym <name> [dir]     locate symbol by substring -> file + lines
+  graphscout callers <name> [dir] who calls it
+  graphscout callees <name> [dir] what it calls
+  graphscout deps <path>          imports of a file
+  graphscout touch <path>         re-extract one file into its repo's cache (hook use)
+  graphscout agent                print an instruction snippet for AGENTS.md / CLAUDE.md
+  graphscout install [agent...]   wire the MCP server into detected agents (claude-code, codex, gemini, cursor)
+  graphscout uninstall [agent...] remove it again
+  graphscout mcp                  run as an MCP server (requires `pip install graphscout[mcp]`)
+  graphscout --version            print version
+
+Queries auto-run `ensure` first, so the graph tracks the working tree.
+"""
+import sys
+from pathlib import Path
+
+from . import __version__, core, queries
+
+AGENT_SNIPPET = """\
+## Code navigation — graph first, read only what you need
+
+This repo has `graphscout` (cached tree-sitter code graphs). Before reading
+source files, query the graph and then read ONLY the located line ranges:
+
+- `graphscout map` — repo overview: size, per-directory breakdown, top hub symbols
+- `graphscout file <path>` — outline of a file (definitions + line ranges)
+- `graphscout sym <name>` — locate a symbol -> file:lines
+- `graphscout callers <name>` / `graphscout callees <name>` — trace call edges
+- `graphscout deps <path>` — what a file imports
+
+Run `graphscout build` once per repo; afterwards every query refreshes changed
+files automatically. Fall back to reading whole files only when the graph
+can't answer (unsupported language, dynamic dispatch, subtle logic).
+"""
+
+
+def main(argv=None):
+    args = sys.argv[1:] if argv is None else argv
+    if not args or args[0] in ("-h", "--help", "help"):
+        print(__doc__)
+        return 0
+    cmd = args[0]
+    tail = args[1:]
+
+    if cmd in ("--version", "-V", "version"):
+        print(f"graphscout {__version__}")
+        return 0
+    if cmd == "agent":
+        print(AGENT_SNIPPET)
+        return 0
+    if cmd == "mcp":
+        from .mcp_server import run  # lazy: needs the [mcp] extra
+        run()
+        return 0
+    if cmd in ("install", "uninstall"):
+        from . import agents
+        fn = agents.install if cmd == "install" else agents.uninstall
+        names = tail or None
+        for line in fn(names):
+            print(line)
+        return 0
+
+    target = None
+    if cmd in ("build", "ensure", "watch", "map", "hubs"):
+        root = core.find_root(Path(tail[0]).resolve() if tail else Path.cwd())
+    elif cmd in ("file", "deps", "touch"):
+        if not tail:
+            print(f"usage: graphscout {cmd} <path>", file=sys.stderr)
+            return 2
+        target = Path(tail[0]).resolve()
+        root = core.find_root(target)
+    elif cmd in ("sym", "callers", "callees"):
+        if not tail:
+            print(f"usage: graphscout {cmd} <name> [dir]", file=sys.stderr)
+            return 2
+        root = core.find_root(Path(tail[1]).resolve() if len(tail) > 1 else Path.cwd())
+    else:
+        print(f"unknown command: {cmd}")
+        print(__doc__)
+        return 2
+
+    if cmd == "build":
+        g, idx, n = core.build(root)
+        print(f"built {root}: {n} files -> {len(g['nodes'])} nodes, {len(g['edges'])} edges")
+        return 0
+    if cmd == "touch":
+        core.touch(target, root)
+        return 0
+    if cmd == "watch":
+        print(f"[graphscout] watching {root} — Ctrl-C to stop", file=sys.stderr)
+        try:
+            for status in core.watch(root):
+                if status:
+                    print(status, file=sys.stderr)
+        except KeyboardInterrupt:
+            pass
+        return 0
+
+    g = core.ensure(root)
+
+    if cmd == "ensure":
+        print(f"{root}: {len(g['nodes'])} nodes, {len(g['edges'])} edges (fresh)")
+    elif cmd in ("map", "hubs"):
+        print(queries.q_map(root, g))
+    elif cmd == "file":
+        print(queries.q_file(root, g, target))
+    elif cmd == "sym":
+        print(queries.q_sym(root, g, tail[0]))
+    elif cmd in ("callers", "callees"):
+        print(queries.q_calls(root, g, tail[0], cmd))
+    elif cmd == "deps":
+        print(queries.q_deps(root, g, target))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

graphscout-0.2.0/src/graphscout/core.py

@@ -0,0 +1,239 @@
+"""Graph building, caching, and incremental refresh.
+
+Graphs are stored per-repo under the cache dir (default ~/.cache/graphscout,
+override with $GRAPHSCOUT_CACHE). Extraction is delegated to graphify
+(tree-sitter AST parsing); this layer adds root discovery, mtime-based
+incremental rebuilds, and root-relative path normalization.
+"""
+import hashlib
+import json
+import os
+import sys
+import time
+from pathlib import Path
+
+# Every extension graphify can walk into a real language extractor (defs, calls,
+# imports) — not just files it can list. Kept as a static set rather than
+# importing graphify.detect at module scope, since that's an internal API.
+CODE_EXTS = {
+    ".py", ".js", ".jsx", ".mjs", ".ts", ".tsx", ".ejs", ".ets", ".vue", ".svelte", ".astro",
+    ".go", ".rs", ".zig", ".java", ".groovy", ".kt", ".kts", ".scala",
+    ".c", ".h", ".cpp", ".cc", ".cxx", ".hpp", ".cs", ".razor", ".cshtml",
+    ".rb", ".php", ".swift", ".m", ".mm", ".lua", ".luau", ".dart",
+    ".ex", ".exs", ".jl", ".r", ".v", ".sv", ".svh",
+    ".pas", ".pp", ".dpr", ".dpk", ".lpr", ".lpk", ".dfm", ".lfm",
+    ".sh", ".bash", ".ps1", ".hcl", ".tf", ".tfvars",
+    ".f", ".f90", ".f95", ".f03", ".f08",
+}
+SKIP_DIRS = {".git", "node_modules", "venv", ".venv", "__pycache__", "dist", "build",
+             ".next", "target", ".cache", "vendor", "site-packages", ".tox", "coverage"}
+MAX_FILES = 5000
+MAX_FILE_BYTES = 1_000_000
+
+
+def cache_dir() -> Path:
+    env = os.environ.get("GRAPHSCOUT_CACHE") or os.environ.get("CODEGRAPH_CACHE")
+    return Path(env) if env else Path.home() / ".cache" / "graphscout"
+
+
+def roots_file() -> Path:
+    return cache_dir() / "roots.json"
+
+
+def repo_key(root: Path) -> Path:
+    return cache_dir() / hashlib.sha1(str(root).encode()).hexdigest()[:16]
+
+
+def find_root(start: Path) -> Path:
+    p = start if start.is_dir() else start.parent
+    for q in [p, *p.parents]:
+        if (q / ".git").exists():
+            return q
+    return p
+
+
+def code_files(root: Path):
+    out = []
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS and not d.startswith(".")]
+        for f in filenames:
+            fp = Path(dirpath) / f
+            if fp.suffix in CODE_EXTS and fp.stat().st_size < MAX_FILE_BYTES:
+                out.append(fp)
+    if len(out) > MAX_FILES:
+        print(f"WARNING: {len(out)} code files; graphing first {MAX_FILES} "
+              f"(largest dirs may be partial)", file=sys.stderr)
+        out = out[:MAX_FILES]
+    return out
+
+
+def load(root: Path):
+    d = repo_key(root)
+    try:
+        graph = json.loads((d / "graph.json").read_text())
+        idx = json.loads((d / "index.json").read_text())
+        return graph, idx
+    except Exception:
+        return None, None
+
+
+def save(root: Path, graph, idx):
+    d = repo_key(root)
+    d.mkdir(parents=True, exist_ok=True)
+    (d / "graph.json").write_text(json.dumps(graph))
+    (d / "index.json").write_text(json.dumps(idx))
+    rf = roots_file()
+    try:
+        roots = json.loads(rf.read_text()) if rf.exists() else {}
+    except Exception:
+        roots = {}
+    roots[str(root)] = time.strftime("%Y-%m-%dT%H:%M:%S")
+    rf.write_text(json.dumps(roots, indent=1))
+
+
+def extract_files(paths, root):
+    """Extract and normalize source_file to root-relative. graphify stores paths
+    relative to the common ancestor of the batch (basename for single/same-dir
+    batches), so we resolve via that ancestor. Unattributable ('' semantic) nodes
+    are dropped — they'd break incremental dedup."""
+    from graphify.extract import extract
+    ok_nodes, ok_edges, failed = [], [], []
+    resolved = [p.resolve() for p in paths]
+    if not resolved:
+        return ok_nodes, ok_edges, failed
+    common = Path(os.path.commonpath([str(p) for p in resolved])) if len(resolved) > 1 else resolved[0].parent
+    if common.is_file():
+        common = common.parent
+
+    def norm(sf):
+        if not sf:
+            return None
+        try:
+            return str((common / sf).resolve().relative_to(root))
+        except ValueError:
+            return None
+
+    def collect(r):
+        for n in r["nodes"]:
+            sf = norm(n.get("source_file", ""))
+            if sf:
+                n["source_file"] = sf
+                ok_nodes.append(n)
+        for e in r["edges"]:
+            sf = norm(e.get("source_file", ""))
+            if sf:
+                e["source_file"] = sf
+                ok_edges.append(e)
+
+    try:
+        collect(extract(paths=resolved, parallel=len(resolved) > 4))
+    except Exception:
+        for p in resolved:
+            common = p.parent
+            try:
+                collect(extract(paths=[p], parallel=False))
+            except Exception:
+                failed.append(str(p))
+    return ok_nodes, ok_edges, failed
+
+
+def build(root: Path, only_changed=False):
+    files = code_files(root)
+    graph, idx = load(root)
+    mtimes = {str(f.relative_to(root)): f.stat().st_mtime for f in files}
+    if only_changed and graph and idx:
+        old = idx.get("mtimes", {})
+        changed = [f for f in files if old.get(str(f.relative_to(root))) != f.stat().st_mtime]
+        deleted = set(old) - set(mtimes)
+        if not changed and not deleted:
+            return graph, idx, 0
+        drop = {str(f.relative_to(root)) for f in changed} | deleted
+        nodes = [n for n in graph["nodes"] if n.get("source_file", "") not in drop]
+        edges = [e for e in graph["edges"] if e.get("source_file", "") not in drop]
+        new_n, new_e, failed = extract_files(changed, root)
+        graph = {"nodes": nodes + new_n, "edges": edges + new_e}
+        n_processed = len(changed)
+    else:
+        new_n, new_e, failed = extract_files(files, root)
+        graph = {"nodes": new_n, "edges": new_e}
+        n_processed = len(files)
+    if failed:
+        print(f"WARNING: {len(failed)} files failed extraction: {failed[:5]}", file=sys.stderr)
+    idx = {"root": str(root), "mtimes": mtimes, "built": time.strftime("%Y-%m-%dT%H:%M:%S"),
+           "failed": failed}
+    save(root, graph, idx)
+    return graph, idx, n_processed
+
+
+def ensure(root: Path):
+    graph, idx, n = build(root, only_changed=True)
+    if n:
+        print(f"[graphscout] refreshed {n} file(s)", file=sys.stderr)
+    return graph
+
+
+def touch(target: Path, root: Path):
+    """Re-extract one file into its repo's cached graph. No-op when the repo
+    has no graph yet (hooks call this on every edit)."""
+    g, idx = load(root)
+    if not g:
+        return
+    f = str(target.relative_to(root))
+    nodes = [n for n in g["nodes"] if n.get("source_file", "") != f]
+    edges = [e for e in g["edges"] if e.get("source_file", "") != f]
+    if target.exists() and target.suffix in CODE_EXTS:
+        nn, ne, _ = extract_files([target], root)
+        nodes += nn
+        edges += ne
+    if target.exists():
+        idx["mtimes"][f] = target.stat().st_mtime
+    else:
+        idx["mtimes"].pop(f, None)
+    save(root, {"nodes": nodes, "edges": edges}, idx)
+
+
+def watch(root: Path, interval: float = 1.5):
+    """Block, keeping root's graph in sync as files change. Yields a status
+    line each time it re-syncs (empty string on no-op polls). No hook or
+    per-edit `touch` call needed while this runs — the opposite of `ensure`'s
+    on-demand model. Uses watchdog for instant, low-CPU events when installed
+    ($ pip install "graphscout[watch]"); falls back to mtime polling otherwise.
+    """
+    if not load(root)[0]:
+        build(root)
+        yield f"[graphscout] initial build of {root}"
+
+    try:
+        from watchdog.events import FileSystemEventHandler
+        from watchdog.observers import Observer
+    except ImportError:
+        while True:
+            time.sleep(interval)
+            _g, _idx, n = build(root, only_changed=True)
+            if n:
+                yield f"[graphscout] refreshed {n} file(s)"
+        return
+
+    import queue
+    q = queue.Queue()
+
+    class Handler(FileSystemEventHandler):
+        def on_any_event(self, event):
+            if not event.is_directory and Path(event.src_path).suffix in CODE_EXTS:
+                q.put(1)
+
+    observer = Observer()
+    observer.schedule(Handler(), str(root), recursive=True)
+    observer.start()
+    try:
+        while True:
+            q.get()
+            time.sleep(0.3)  # debounce bursts (saves, formatters, git checkouts)
+            while not q.empty():
+                q.get_nowait()
+            _g, _idx, n = build(root, only_changed=True)
+            if n:
+                yield f"[graphscout] refreshed {n} file(s)"
+    finally:
+        observer.stop()
+        observer.join()

graphscout-0.2.0/src/graphscout/mcp_server.py

@@ -0,0 +1,84 @@
+"""MCP server exposing graphscout queries as tools, for agents that speak MCP
+instead of shelling out. Requires the `mcp` extra: pip install graphscout[mcp]
+
+Run:  graphscout mcp        (stdio transport)
+"""
+from pathlib import Path
+
+from . import core, queries
+
+try:
+    from mcp.server.fastmcp import FastMCP
+except ImportError as e:  # pragma: no cover
+    raise SystemExit(
+        "MCP support needs the optional dependency: pip install graphscout[mcp]"
+    ) from e
+
+server = FastMCP(
+    "graphscout",
+    instructions=(
+        "Cached tree-sitter code graphs. Query structure (outlines, symbols, "
+        "call edges, imports) instead of reading whole files; then read only "
+        "the located line ranges."
+    ),
+)
+
+
+def _root(directory: str) -> Path:
+    return core.find_root(Path(directory).resolve())
+
+
+@server.tool()
+def graph_map(directory: str) -> str:
+    """Repo overview: node/edge counts, per-directory breakdown, top hub symbols."""
+    root = _root(directory)
+    return queries.q_map(root, core.ensure(root))
+
+
+@server.tool()
+def file_outline(path: str) -> str:
+    """Outline of one source file: definitions with line ranges."""
+    target = Path(path).resolve()
+    root = core.find_root(target)
+    return queries.q_file(root, core.ensure(root), target)
+
+
+@server.tool()
+def find_symbol(name: str, directory: str = ".") -> str:
+    """Locate a symbol by substring -> file:lines."""
+    root = _root(directory)
+    return queries.q_sym(root, core.ensure(root), name)
+
+
+@server.tool()
+def callers(name: str, directory: str = ".") -> str:
+    """Who calls this symbol (matched by substring)."""
+    root = _root(directory)
+    return queries.q_calls(root, core.ensure(root), name, "callers")
+
+
+@server.tool()
+def callees(name: str, directory: str = ".") -> str:
+    """What this symbol calls (matched by substring)."""
+    root = _root(directory)
+    return queries.q_calls(root, core.ensure(root), name, "callees")
+
+
+@server.tool()
+def file_deps(path: str) -> str:
+    """Imports of a source file."""
+    target = Path(path).resolve()
+    root = core.find_root(target)
+    return queries.q_deps(root, core.ensure(root), target)
+
+
+@server.tool()
+def build_graph(directory: str) -> str:
+    """Full (re)build of a repo's graph. Run once per repo; queries refresh incrementally."""
+    root = _root(directory)
+    g, _idx, n = core.build(root)
+    return f"built {root}: {n} files -> {len(g['nodes'])} nodes, {len(g['edges'])} edges"
+
+
+def run():
+    server.run()

graphscout-0.2.0/src/graphscout/queries.py

@@ -0,0 +1,81 @@
+"""Query functions over a built graph. Each returns a plain string ready to
+show to a human or an agent — the CLI prints it, the MCP server returns it."""
+from collections import Counter
+from pathlib import Path
+
+from . import core
+
+
+def loc(n):
+    return f"{n.get('source_file', '?')}:{n.get('source_location', '?')}"
+
+
+def fmt_node(n):
+    return f"{n.get('label', n['id'])}  [{n.get('type', n.get('_origin', '?'))}]  {loc(n)}"
+
+
+def fresh_graph(root: Path):
+    return core.ensure(root)
+
+
+def q_map(root: Path, g) -> str:
+    nodes, edges = g["nodes"], g["edges"]
+    deg = Counter()
+    for e in edges:
+        deg[e["source"]] += 1
+        deg[e["target"]] += 1
+    byid = {n["id"]: n for n in nodes}
+    per_dir = Counter(n.get("source_file", "?").split("/")[0] for n in nodes)
+    rels = Counter(e.get("relation", "?") for e in edges)
+    lines = [f"{root} — {len(nodes)} nodes, {len(edges)} edges",
+             f"per-dir: {dict(per_dir.most_common(12))}",
+             f"relations: {dict(rels.most_common())}",
+             "top hubs:"]
+    for nid, d in deg.most_common(15):
+        n = byid.get(nid)
+        if n:
+            lines.append(f"  {d:4d}  {fmt_node(n)}")
+    return "\n".join(lines)
+
+
+def q_file(root: Path, g, target: Path) -> str:
+    f = str(target.resolve().relative_to(root))
+    mine = [n for n in g["nodes"] if n.get("source_file", "") == f]
+    if not mine:
+        return f"(no graph entries for {f} — unsupported language or empty; read it directly)"
+    return "\n".join(fmt_node(n) for n in sorted(mine, key=lambda x: x.get("source_location", "")))
+
+
+def q_sym(root: Path, g, query: str, limit: int = 30) -> str:
+    q = query.lower()
+    hits = [n for n in g["nodes"] if q in n.get("label", "").lower() or q in n["id"].lower()]
+    if not hits:
+        return f"no symbol matching '{query}' — try grep"
+    lines = [fmt_node(n) for n in hits[:limit]]
+    if len(hits) > limit:
+        lines.append(f"... {len(hits) - limit} more (narrow the query)")
+    return "\n".join(lines)
+
+
+def q_calls(root: Path, g, query: str, direction: str, limit: int = 40) -> str:
+    """direction: 'callers' (who calls it) or 'callees' (what it calls)."""
+    q = query.lower()
+    byid = {n["id"]: n for n in g["nodes"]}
+    key, other = ("target", "source") if direction == "callers" else ("source", "target")
+    hits = [e for e in g["edges"] if e.get("relation") == "calls" and q in e[key].lower()]
+    if not hits:
+        return (f"no call edges matching '{query}' "
+                "(dynamic dispatch isn't captured — fall back to grep)")
+    lines = []
+    for e in hits[:limit]:
+        n = byid.get(e[other])
+        lines.append(fmt_node(n) if n else
+                     f"{e[other]}  ({e.get('source_file', '?')}:{e.get('source_location', '?')})")
+    return "\n".join(lines)
+
+
+def q_deps(root: Path, g, target: Path) -> str:
+    f = str(target.resolve().relative_to(root))
+    lines = [f"{e['relation']:13s} {e['target']}" for e in g["edges"]
+             if e.get("source_file", "") == f and e.get("relation") in ("imports", "imports_from")]
+    return "\n".join(lines) if lines else f"(no import edges recorded for {f})"

graphscout-0.2.0/tests/test_graphscout.py

@@ -0,0 +1,172 @@
+import json
+import os
+import time
+from pathlib import Path
+
+import pytest
+
+from graphscout import cli, core
+
+A_PY = '''\
+import os
+
+
+def helper(x):
+    return os.path.join("a", x)
+
+
+def main_entry():
+    return helper("b")
+'''
+
+B_PY = '''\
+from a import helper
+
+
+class Runner:
+    def run(self):
+        return helper("c")
+'''
+
+
+@pytest.fixture
+def repo(tmp_path, monkeypatch):
+    monkeypatch.setenv("GRAPHSCOUT_CACHE", str(tmp_path / "cache"))
+    root = tmp_path / "repo"
+    (root / ".git").mkdir(parents=True)
+    (root / "a.py").write_text(A_PY)
+    (root / "sub").mkdir()
+    (root / "sub" / "b.py").write_text(B_PY)
+    return root
+
+
+def run(capsys, *args):
+    rc = cli.main(list(args))
+    out = capsys.readouterr().out
+    return rc, out
+
+
+def test_build_and_map(repo, capsys):
+    rc, out = run(capsys, "build", str(repo))
+    assert rc == 0 and "built" in out and "0 nodes" not in out
+    rc, out = run(capsys, "map", str(repo))
+    assert "nodes" in out and "top hubs:" in out
+
+
+def test_file_outline_and_sym(repo, capsys):
+    run(capsys, "build", str(repo))
+    rc, out = run(capsys, "file", str(repo / "a.py"))
+    assert "helper" in out and "main_entry" in out
+    rc, out = run(capsys, "sym", "main_entry", str(repo))
+    assert "a.py" in out
+
+
+def test_callers_and_deps(repo, capsys):
+    run(capsys, "build", str(repo))
+    rc, out = run(capsys, "callers", "helper", str(repo))
+    assert "main_entry" in out or "run" in out
+    rc, out = run(capsys, "deps", str(repo / "a.py"))
+    assert "os" in out
+
+
+def test_incremental_refresh_no_node_growth(repo, capsys):
+    """Repeated ensure must not duplicate nodes; edits must be picked up."""
+    run(capsys, "build", str(repo))
+    g1, _ = core.load(repo)
+    run(capsys, "ensure", str(repo))
+    run(capsys, "ensure", str(repo))
+    g2, _ = core.load(repo)
+    assert len(g2["nodes"]) == len(g1["nodes"])
+
+    time.sleep(0.01)
+    (repo / "a.py").write_text(A_PY + "\n\ndef added_later():\n    return 1\n")
+    os.utime(repo / "a.py")
+    rc, out = run(capsys, "sym", "added_later", str(repo))
+    assert "a.py" in out
+    g3, _ = core.load(repo)
+    dupes = [n for n in g3["nodes"] if "helper" in n.get("label", "")
+             and n.get("source_file") == "a.py"]
+    assert len(dupes) == 1
+
+
+def test_deleted_file_dropped(repo, capsys):
+    run(capsys, "build", str(repo))
+    (repo / "sub" / "b.py").unlink()
+    rc, out = run(capsys, "sym", "Runner", str(repo))
+    assert "no symbol matching" in out
+
+
+def test_touch_single_file(repo, capsys):
+    run(capsys, "build", str(repo))
+    time.sleep(0.01)
+    (repo / "a.py").write_text(A_PY.replace("main_entry", "renamed_entry"))
+    core.touch(repo / "a.py", repo)
+    g, idx = core.load(repo)
+    labels = {n.get("label", "") for n in g["nodes"] if n.get("source_file") == "a.py"}
+    assert any("renamed_entry" in l for l in labels)
+    assert not any("main_entry" in l for l in labels)
+
+
+def test_agent_snippet_and_version(repo, capsys):
+    rc, out = run(capsys, "agent")
+    assert "graphscout map" in out and "graphscout sym" in out
+    rc, out = run(capsys, "--version")
+    assert out.startswith("graphscout ")
+
+
+def test_unknown_command(repo, capsys):
+    rc, out = run(capsys, "frobnicate")
+    assert rc == 2
+
+
+def test_cache_is_root_scoped(repo, capsys):
+    run(capsys, "build", str(repo))
+    d = core.repo_key(repo)
+    assert (d / "graph.json").exists()
+    roots = json.loads(core.roots_file().read_text())
+    assert str(repo) in roots
+
+
+def test_watch_polling_refresh(repo, monkeypatch):
+    """Without watchdog installed, watch() falls back to mtime polling."""
+    monkeypatch.setitem(__import__("sys").modules, "watchdog", None)
+    monkeypatch.setattr(core.time, "sleep", lambda _s: None)
+
+    gen = core.watch(repo, interval=0.01)
+    first = next(gen)
+    assert "initial build" in first
+
+    time.sleep(0.01)
+    (repo / "a.py").write_text(A_PY + "\n\ndef watched_fn():\n    return 1\n")
+    os.utime(repo / "a.py")
+    second = next(gen)
+    assert "refreshed" in second
+    gen.close()
+
+    g, _ = core.load(repo)
+    assert any("watched_fn" in n.get("label", "") for n in g["nodes"])
+
+
+def test_install_uninstall_json_agent(tmp_path, monkeypatch):
+    from graphscout import agents
+
+    cursor_path = tmp_path / "cursor" / "mcp.json"
+    monkeypatch.setitem(agents.AGENTS, "cursor", {"kind": "json", "path": cursor_path})
+
+    log = agents.install(["cursor"])
+    assert any("wired" in line for line in log)
+    cfg = json.loads(cursor_path.read_text())
+    assert cfg["mcpServers"]["graphscout"]["command"] == "graphscout"
+
+    log = agents.uninstall(["cursor"])
+    assert any("removed" in line for line in log)
+    cfg = json.loads(cursor_path.read_text())
+    assert "graphscout" not in cfg["mcpServers"]
+
+
+def test_detect_skips_missing_cli_agent(monkeypatch):
+    from graphscout import agents
+
+    monkeypatch.setattr(agents.shutil, "which", lambda _b: None)
+    present = agents.detect()
+    assert all(ok is False for name, ok in present.items() if agents.AGENTS[name]["kind"] == "cli")