graphsnip 0.1.0__py3-none-any.whl

graphsnip/__init__.py

@@ -0,0 +1,3 @@
+"""graphsnip: a token-saving layer on top of Graphify."""
+
+__version__ = "0.1.0"

graphsnip/__main__.py

@@ -0,0 +1,4 @@
+from graphsnip.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

graphsnip/baseline.py

@@ -0,0 +1,89 @@
+"""The honest baseline.
+
+Graphify's own benchmark compares a query against reading the *entire corpus*,
+which no agent actually does. graphsnip instead prices what an agent without
+the graph would realistically do for the same question: grep for the terms,
+then read the best-matching files in full (capped at `max_files`).
+
+Both numbers are reported; the headline uses this one because it is the
+defensible one.
+"""
+from __future__ import annotations
+
+import re
+
+from graphsnip.project import MAX_FILE_BYTES, Project
+from graphsnip.tokens import count_tokens
+
+_STOP = set("""
+a an and are as at be by can do does for from how i in is it its of on or that the this to was what when where which who why with
+use used using work works get gets make makes find show tell explain code file files function functions class classes method
+methods please about into over under all any not our your their there then than also
+""".split())
+_WORD = re.compile(r"[A-Za-z][A-Za-z0-9_]{2,}")
+_CAMEL = re.compile(r"[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+|\d+")
+
+
+def query_terms(text: str, limit: int = 8) -> list[str]:
+    terms: list[str] = []
+    for w in _WORD.findall(text or ""):
+        parts = [w.lower()]
+        if "_" in w or re.search(r"[a-z][A-Z]", w):
+            parts.append(w.lower())
+            parts += [p.lower() for p in _CAMEL.findall(w.replace("_", " ")) if len(p) >= 3]
+        for p in parts:
+            if p not in _STOP and len(p) >= 3 and p not in terms:
+                terms.append(p)
+    return terms[:limit]
+
+
+class Baseline:
+    def __init__(self, project: Project):
+        self.p = project
+        self._text: dict[str, str] | None = None
+        self._tok: dict[str, int] = {}
+
+    def _index(self) -> dict[str, str]:
+        if self._text is None:
+            idx: dict[str, str] = {}
+            for f in self.p.files()[:20000]:
+                try:
+                    if f.stat().st_size > MAX_FILE_BYTES:
+                        continue
+                    idx[self.p.rel(f)] = f.read_text(encoding="utf-8", errors="replace")
+                except Exception:
+                    continue
+            self._text = idx
+        return self._text
+
+    def file_tokens(self, rel: str) -> int:
+        if rel not in self._tok:
+            t = self._index().get(rel)
+            if t is None:
+                t = self.p.read(rel) or ""
+            self._tok[rel] = count_tokens(t)
+        return self._tok[rel]
+
+    def grep_read(self, terms: list[str], max_files: int = 8) -> tuple[int, list[str]]:
+        """Tokens for: grep each term, read the top `max_files` matching files in full."""
+        if not terms:
+            return 0, []
+        scored: list[tuple[int, str]] = []
+        for rel, text in self._index().items():
+            low = text.lower()
+            s = 0
+            for t in terms:
+                c = low.count(t)
+                if c:
+                    s += min(c, 10)
+            if s:
+                scored.append((s, rel))
+        scored.sort(key=lambda x: (-x[0], x[1]))
+        chosen = [rel for _s, rel in scored[:max_files]]
+        tokens = sum(self.file_tokens(r) for r in chosen) + 150  # + the grep listing itself
+        return tokens, chosen
+
+    def symbol_name_files(self, name: str, max_files: int = 10) -> tuple[int, list[str]]:
+        """Tokens for: grep a symbol name, read every matching file (capped)."""
+        n = re.sub(r"\(.*\)\s*$", "", name).lstrip(".").split(".")[-1].lower()
+        return self.grep_read([n], max_files=max_files) if len(n) >= 2 else (0, [])

graphsnip/bench.py

@@ -0,0 +1,208 @@
+"""Offline, reproducible benchmark.
+
+For each task it prices three approaches and checks the answer is actually there:
+
+  naive       grep the terms, read the best-matching files in full (capped)   <- realistic baseline
+  graphify    Graphify's own `query` (budgeted)                              <- graph map, no source code
+  graphsnip   pack / find+symbol / impact+symbol                             <- map + exact code
+
+Quality is checked, not assumed: a task counts as answered only when the
+expected symbol shows up in the output (and, for graphsnip, with its source).
+"""
+from __future__ import annotations
+
+import json
+import re
+import time
+from pathlib import Path
+
+from graphsnip.baseline import Baseline, query_terms
+from graphsnip.engine import Engine
+from graphsnip.project import Project
+from graphsnip.tokens import count_tokens, method
+
+TYPES = ("understand", "impact", "locate")
+
+
+def _short(label: str) -> str:
+    return re.sub(r"\([^()]*\)\s*$", "", label).strip()
+
+
+def _resolvable(G, project: Project, name: str) -> bool:
+    """Auto-generated tasks must be answerable by the tools; user-written tasks are never filtered."""
+    try:
+        from graphify.affected import resolve_seed_outcome
+        from graphify.serve import _resolve_single_node
+
+        nid, err = _resolve_single_node(G, name.split(".")[-1] if "." not in name else name)
+        seed, _ = resolve_seed_outcome(G, name.split(".")[-1], project.root)
+        return nid is not None and not err and seed is not None
+    except Exception:
+        return False
+
+
+def default_tasks(project: Project, n: int = 8) -> list[dict]:
+    eng = Engine(project.root, source="bench", auto_refresh=False)
+    G = project.graph()
+    seen_files: dict[str, int] = {}
+    picks = []
+    idx = project.label_index()
+    from graphsnip.project import bare
+
+    for row in project.top_symbols(80):
+        lab = _short(str(row["label"]))
+        if len(lab) < 4 or lab.startswith("_") or row["file"] in seen_files and seen_files[row["file"]] >= 1:
+            continue
+        if len(idx.get(bare(lab), [])) != 1:  # ambiguous names make impact/symbol lookups refuse; skip them
+            continue
+        if not _resolvable(G, project, eng._display(G, row["id"]).replace("()", "")):
+            continue
+        seen_files[row["file"]] = seen_files.get(row["file"], 0) + 1
+        picks.append(row)
+        if len(picks) >= n:
+            break
+    tasks = []
+    for i, row in enumerate(picks):
+        name = _short(eng._display(G, row["id"]))
+        t = TYPES[i % 3]
+        q = {"understand": f"how does {name} work and what does it depend on",
+             "impact": f"what breaks if I change {name}",
+             "locate": f"where is {name} defined and where is it used"}[t]
+        tasks.append({"id": f"t{i + 1}", "type": t, "question": q, "expect": [name.split(".")[-1]],
+                      "target_file": row["file"]})
+    return tasks
+
+
+def load_tasks(project: Project, path: str | None) -> list[dict]:
+    p = Path(path) if path else project.gs_dir / "tasks.json"
+    if p.exists():
+        data = json.loads(p.read_text(encoding="utf-8"))
+        tasks = data["tasks"] if isinstance(data, dict) else data
+        for i, t in enumerate(tasks):
+            t.setdefault("id", f"t{i + 1}")
+            t.setdefault("type", "understand")
+            t.setdefault("expect", [])
+        return tasks
+    return default_tasks(project)
+
+
+def save_default_tasks(project: Project) -> Path:
+    project.gs_dir.mkdir(parents=True, exist_ok=True)
+    p = project.gs_dir / "tasks.json"
+    p.write_text(json.dumps({"_note": "Edit freely. type: understand | impact | locate. expect: symbol names that must appear in a correct answer.",
+                             "tasks": default_tasks(project)}, indent=2) + "\n", encoding="utf-8")
+    return p
+
+
+def run_bench(root: str = ".", tasks_path: str | None = None, quiet: bool = False) -> dict:
+    eng = Engine(root, source="bench")
+    p = eng.p
+    p.ensure_graph(True)
+    G = p.graph()
+    tasks = load_tasks(p, tasks_path)
+    base = Baseline(p)
+    eng.ledger.clear(source="bench")
+    from graphify.serve import _query_graph_text
+
+    corpus_tokens = sum(base.file_tokens(p.rel(f)) for f in p.files()[:20000])
+    rows = []
+    t0 = time.time()
+    for t in tasks:
+        q = t["question"]
+        expect = [e.lower() for e in t.get("expect", [])]
+        e2 = Engine(root, source="bench", auto_refresh=False)  # fresh session per task
+        naive_tokens, naive_files = base.grep_read(query_terms(q))
+        naive_text = " ".join((p.read(f) or "") for f in naive_files).lower()
+        naive_hit = all(x in naive_text for x in expect) if expect else bool(naive_files)
+
+        gtext = _query_graph_text(G, q, mode="bfs", depth=3, token_budget=2000, graph_path=str(p.graph_json))
+        gtokens = 0 if gtext.startswith("No matching") else count_tokens(gtext)
+        ghit = all(x in gtext.lower() for x in expect) if expect else bool(gtokens)
+        # what an agent using Graphify alone then does: read the files its top hits point to
+        g_files: list[str] = []
+        for m in re.finditer(r"src=([^\s\]]+)", gtext):
+            f = m.group(1)
+            if f and f not in g_files and (p.root / f).is_file():
+                g_files.append(f)
+            if len(g_files) >= 3:
+                break
+        gread_tokens = (gtokens + sum(base.file_tokens(f) for f in g_files)) if gtokens else 0
+
+        typ = t.get("type", "understand")
+        name = (t.get("expect") or [q])[0]
+        parts = []
+        if typ == "understand":
+            parts.append(e2.pack(q, budget=3500))
+        elif typ == "impact":
+            parts.append(e2.impact(name))
+            parts.append(e2.symbol(name))
+        else:
+            parts.append(e2.find(q, budget=1200))
+            parts.append(e2.symbol(name))
+        gs_text = "\n".join(r.text for r in parts if r.ok)
+        gs_tokens = sum(r.returned for r in parts if r.ok)
+        has_code = "```" in gs_text
+        gs_hit = (all(x in gs_text.lower() for x in expect) if expect else bool(gs_tokens)) and has_code
+        # second read of the same symbol in the same session
+        again = e2.symbol(name)
+        rows.append({
+            "id": t["id"], "type": typ, "question": q, "expect": t.get("expect", []),
+            "naive_tokens": naive_tokens, "naive_files": len(naive_files), "naive_hit": naive_hit,
+            "graphify_tokens": gtokens, "graphify_hit": ghit, "graphify_read_tokens": gread_tokens,
+            "graphsnip_tokens": gs_tokens, "graphsnip_hit": gs_hit, "graphsnip_has_code": has_code,
+            "reread_tokens": again.returned if again.ok else None,
+            "reduction_vs_naive": round(naive_tokens / gs_tokens, 1) if gs_tokens else None,
+        })
+    ok = [r for r in rows if r["graphsnip_tokens"]]
+    tot_n = sum(r["naive_tokens"] for r in ok)
+    tot_c = sum(r["graphsnip_tokens"] for r in ok)
+    tot_g = sum(r["graphify_tokens"] for r in rows)
+    tot_gr = sum(r["graphify_read_tokens"] for r in rows)
+    result = {
+        "ts": time.strftime("%Y-%m-%dT%H:%M:%S%z"),
+        "root": str(p.root),
+        "token_method": method(),
+        "baseline_definition": "grep the question's terms, read the top 8 matching files in full",
+        "graph": p.graph_stats(),
+        "corpus_tokens": corpus_tokens,
+        "tasks": rows,
+        "totals": {
+            "naive_tokens": tot_n, "graphsnip_tokens": tot_c, "graphify_tokens": tot_g, "graphify_read_tokens": tot_gr,
+            "saved_vs_graphify_read_pct": round(100 * (tot_gr - tot_c) / tot_gr, 1) if tot_gr else 0.0,
+            "saved_tokens": tot_n - tot_c,
+            "saved_pct": round(100 * (tot_n - tot_c) / tot_n, 1) if tot_n else 0.0,
+            "ratio": round(tot_n / tot_c, 1) if tot_c else 0.0,
+            "vs_corpus_ratio": round(corpus_tokens / (tot_c / len(ok)), 1) if ok and tot_c else 0.0,
+            "answered": sum(1 for r in rows if r["graphsnip_hit"]),
+            "naive_answered": sum(1 for r in rows if r["naive_hit"]),
+            "graphify_answered": sum(1 for r in rows if r["graphify_hit"]),
+            "tasks": len(rows),
+            "seconds": round(time.time() - t0, 1),
+        },
+    }
+    p.gs_dir.mkdir(parents=True, exist_ok=True)
+    (p.gs_dir / "bench.json").write_text(json.dumps(result, indent=2), encoding="utf-8")
+    return result
+
+
+def format_table(res: dict) -> str:
+    rows = res["tasks"]
+    t = res["totals"]
+    w = max(8, min(44, max(len(r["question"]) for r in rows)))
+    hdr = f"{'task':<{w}}  {'grep+read':>9}  {'graphify':>8}  {'gfy+read':>8}  {'graphsnip':>9}  {'saved':>6}  ok"
+    out = [hdr, "-" * len(hdr)]
+    for r in rows:
+        saved = f"{100 * (1 - r['graphsnip_tokens'] / r['naive_tokens']):.0f}%" if r["naive_tokens"] and r["graphsnip_tokens"] else "-"
+        out.append(f"{r['question'][:w]:<{w}}  {r['naive_tokens']:>9,}  {r['graphify_tokens']:>8,}  {r['graphify_read_tokens']:>8,}  "
+                   f"{r['graphsnip_tokens']:>9,}  {saved:>6}  {'✓' if r['graphsnip_hit'] else '✗'}")
+    out.append("-" * len(hdr))
+    out.append(f"{'TOTAL':<{w}}  {t['naive_tokens']:>9,}  {t['graphify_tokens']:>8,}  {t['graphify_read_tokens']:>8,}  "
+               f"{t['graphsnip_tokens']:>9,}  {t['saved_pct']:>5}%  {t['answered']}/{t['tasks']}")
+    out.append(f"\ngrep+read  = {res['baseline_definition']} (what an agent does with no graph)")
+    out.append("graphify   = Graphify `query` alone: a map with no source code")
+    out.append("gfy+read   = that map, then reading the whole files its top hits point to (3 files max)")
+    out.append("graphsnip  = exact code, ranked and budgeted (pack / find+symbol / impact+symbol)")
+    out.append(f"Saved column is vs grep+read; vs graphify+read it is {t['saved_vs_graphify_read_pct']}%. Tokens: {res['token_method']}.")
+    out.append(f"Answered (expected symbol + source present): graphsnip {t['answered']}/{t['tasks']}, "
+               f"grep+read {t['naive_answered']}/{t['tasks']}.")
+    return "\n".join(out)

graphsnip/cli.py

@@ -0,0 +1,368 @@
+"""graphsnip command line."""
+from __future__ import annotations
+
+import argparse
+import importlib.metadata as md
+import json
+import shutil
+import sys
+import webbrowser
+
+from graphsnip import __version__
+from graphsnip import ledger as _ledger
+from graphsnip.engine import Engine, Result
+from graphsnip.project import GraphError, Project
+
+
+def _common() -> argparse.ArgumentParser:
+    c = argparse.ArgumentParser(add_help=False)
+    c.add_argument("--root", default=".", help="project root (default: current directory)")
+    return c
+
+
+def _emit(r: Result, quiet: bool = False) -> int:
+    print(r.text)
+    if r.ok and not quiet:
+        pct = f"{100 * (1 - r.returned / r.baseline):.0f}%" if r.baseline else "n/a"
+        note = " (duplicate, suppressed)" if r.deduped else ""
+        sys.stderr.write(f"\n[graphsnip] ~{r.returned:,} tokens returned vs ~{r.baseline:,} for grep+read → saved {pct}{note}\n")
+    return 0 if r.ok else 1
+
+
+def cmd_build(a) -> int:
+    p = Project(a.root)
+    s = p.build(force=a.force)
+    print(f"Graph ready ({s['mode']}, {s['seconds']}s): {s['nodes']:,} nodes, {s['edges']:,} edges, "
+          f"{s['communities']:,} communities, {s['symbols']:,} code symbols.")
+    print(f"  map:    {p.graph_html}")
+    print(f"  report: {p.report_md}")
+    return 0
+
+
+def cmd_status(a) -> int:
+    p = Project(a.root)
+    if not p.has_graph():
+        print("No graph yet. Run `graphsnip build` or `graphsnip init`.")
+        return 1
+    s = p.graph_stats()
+    print(f"Project: {p.root}")
+    print(f"Graph:   {s['nodes']:,} nodes · {s['edges']:,} edges · {s['communities']:,} communities · {s['symbols']:,} code symbols")
+    print(f"Stale:   {'yes, run `graphsnip build` (the server refreshes automatically)' if p.is_stale(0) else 'no'}")
+    print(f"Mode:    {p.config()['mode']}")
+    return 0
+
+
+def cmd_find(a) -> int:
+    return _emit(Engine(a.root, source="cli").find(a.question, budget=a.budget, depth=a.depth), a.quiet)
+
+
+def cmd_symbol(a) -> int:
+    return _emit(Engine(a.root, source="cli").symbol(a.name, max_lines=a.max_lines, docs="full" if a.full_docs else "short"), a.quiet)
+
+
+def cmd_pack(a) -> int:
+    return _emit(Engine(a.root, source="cli").pack(a.task, budget=a.budget), a.quiet)
+
+
+def cmd_impact(a) -> int:
+    return _emit(Engine(a.root, source="cli").impact(a.name, depth=a.depth), a.quiet)
+
+
+def cmd_outline(a) -> int:
+    return _emit(Engine(a.root, source="cli").outline(a.path), a.quiet)
+
+
+def cmd_stats(a) -> int:
+    p = Project(a.root)
+    recs = _ledger.Ledger(p.gs_dir).read()
+    price = float(p.config().get("price_per_mtok", 3.0))
+    if a.json:
+        print(json.dumps({"live": _ledger.summarize(recs, price, {"agent", "cli", "shell"}),
+                          "bench": _ledger.summarize(recs, price, {"bench"})}, indent=2, default=str))
+        return 0
+    for title, src in (("Live usage (agents + CLI + shell)", {"agent", "cli", "shell"}), ("Benchmark", {"bench"})):
+        s = _ledger.summarize(recs, price, src)
+        print(f"\n{title}")
+        if not s["calls"]:
+            print("  nothing recorded yet")
+            continue
+        print(f"  {s['calls']} calls · {s['returned']:,} tokens returned vs {s['baseline']:,} baseline")
+        print(f"  saved {s['saved']:,} tokens ({s['pct']}%, {s['ratio']}x) ≈ ${s['usd_saved']} at ${price:g}/M input tokens")
+        for tool, t in sorted(s["by_tool"].items(), key=lambda kv: -(kv[1]["baseline"] - kv[1]["returned"])):
+            print(f"    {tool:<8} {t['calls']:>4} calls  {t['returned']:>9,} vs {t['baseline']:>10,}")
+        if s["hooks"]:
+            print("  hooks: " + ", ".join(f"{k} ×{v}" for k, v in s["hooks"].items()))
+    return 0
+
+
+def cmd_report(a) -> int:
+    from graphsnip.dashboard import write_dashboard
+
+    p = Project(a.root)
+    if not p.has_graph():
+        print("No graph yet. Run `graphsnip build` first.")
+        return 1
+    out = write_dashboard(p, bundle=a.bundle)
+    print(f"Dashboard written: {out}")
+    if a.bundle:
+        print("The folder is self-contained (dashboard.html + graph.html): zip or share it as is.")
+    if a.open:
+        webbrowser.open(out.as_uri())
+    return 0
+
+
+def cmd_bench(a) -> int:
+    from graphsnip.bench import format_table, run_bench, save_default_tasks
+
+    p = Project(a.root)
+    p.ensure_graph(True)
+    if a.init_tasks or (not (p.gs_dir / "tasks.json").exists() and not a.tasks):
+        path = save_default_tasks(p)
+        print(f"Wrote starter tasks to {path} (edit them to use your own questions).\n")
+    res = run_bench(a.root, a.tasks)
+    if a.json:
+        print(json.dumps(res, indent=2))
+    else:
+        print(format_table(res))
+    return 0
+
+
+def cmd_demo(a) -> int:
+    from graphsnip.bench import format_table, run_bench, save_default_tasks
+    from graphsnip.dashboard import write_dashboard
+
+    p = Project(a.root)
+    if not p.has_graph():
+        print("Building the Graphify graph (code only, local, no LLM)…")
+        s = p.build()
+        print(f"  {s['nodes']:,} nodes, {s['edges']:,} edges in {s['seconds']}s\n")
+    if not (p.gs_dir / "tasks.json").exists():
+        save_default_tasks(p)
+    print("Running benchmark…\n")
+    res = run_bench(a.root)
+    print(format_table(res))
+    out = write_dashboard(p, bundle=a.bundle)
+    print(f"\nDashboard: {out}")
+    if a.open:
+        webbrowser.open(out.as_uri())
+    return 0
+
+
+def cmd_serve(a) -> int:
+    from graphsnip.mcp_server import serve
+
+    serve(a.root)
+    return 0
+
+
+def cmd_hook(a) -> int:
+    from graphsnip.hooks import main_stdin
+
+    return main_stdin(a.root)
+
+
+def cmd_run(a) -> int:
+    from graphsnip.shellfilter import run
+
+    argv = list(a.cmd)
+    if argv and argv[0] == "--":
+        argv = argv[1:]
+    return run(argv, a.root)
+
+
+def _clients(s: str) -> list[str]:
+    return [x.strip().lower() for x in s.split(",") if x.strip()]
+
+
+def cmd_install(a) -> int:
+    from graphsnip.installer import install
+
+    try:
+        for ln in install(a.root, _clients(a.clients), dry_run=a.dry_run, allow_tools=a.allow_tools,
+                          codex_scope=a.codex_scope, strict=a.strict, portable=a.portable):
+            print(ln)
+    except (ValueError, RuntimeError) as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+    if not a.dry_run:
+        print("\nRestart your agent/IDE so it picks up the MCP server. `graphsnip doctor` checks the setup.")
+    return 0
+
+
+def cmd_uninstall(a) -> int:
+    from graphsnip.installer import uninstall
+
+    for ln in uninstall(a.root, _clients(a.clients), a.codex_scope):
+        print(ln)
+    return 0
+
+
+def cmd_init(a) -> int:
+    from graphsnip.bench import format_table, run_bench, save_default_tasks
+    from graphsnip.dashboard import write_dashboard
+    from graphsnip.installer import install
+
+    p = Project(a.root)
+    if a.dry_run:
+        print("1/4 [dry-run] skipping graph build")
+    elif not a.no_build:
+        print("1/4 Building the Graphify graph (code only, local, no LLM)…")
+        s = p.build()
+        print(f"    {s['nodes']:,} nodes, {s['edges']:,} edges, {s['communities']:,} communities in {s['seconds']}s")
+    print("2/4 Installing agent integrations…")
+    try:
+        for ln in install(a.root, _clients(a.clients), dry_run=a.dry_run, allow_tools=a.allow_tools,
+                          codex_scope=a.codex_scope, strict=a.strict, portable=a.portable):
+            print("    " + ln)
+    except (ValueError, RuntimeError) as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+    if a.dry_run or not p.has_graph():
+        return 0
+    if not a.no_bench:
+        print("3/4 Benchmarking on this repo…")
+        save_default_tasks(p) if not (p.gs_dir / "tasks.json").exists() else None
+        res = run_bench(a.root)
+        print("\n" + format_table(res) + "\n")
+    print("4/4 Writing the dashboard…")
+    out = write_dashboard(p)
+    print(f"    {out}")
+    print("\nDone. Restart your agent/IDE, then ask it a code question. `graphsnip report --open` shows the savings.")
+    return 0
+
+
+def cmd_doctor(a) -> int:
+    from graphsnip.installer import CLIENTS, HOOK_MARK
+
+    p = Project(a.root)
+    ok = True
+
+    def line(good: bool, msg: str, fix: str = ""):
+        nonlocal ok
+        ok &= good
+        print(f"{'✓' if good else '✗'} {msg}" + (f"  → {fix}" if (fix and not good) else ""))
+
+    line(sys.version_info >= (3, 10), f"Python {sys.version.split()[0]}", "needs Python 3.10+")
+    try:
+        gv = md.version("graphifyy")
+        line(True, f"Graphify {gv}")
+    except Exception:
+        line(False, "Graphify not installed", "pip install graphifyy")
+    try:
+        import tree_sitter  # noqa: F401
+        line(True, "tree-sitter available (exact symbol slicing)")
+    except Exception:
+        line(False, "tree-sitter missing; slicing falls back to heuristics", "pip install graphifyy")
+    exe = shutil.which("graphsnip")
+    line(bool(exe), f"`graphsnip` on PATH ({exe})" if exe else "`graphsnip` not on PATH (configs will use `python -m graphsnip`)", "pipx install graphsnip")
+    line(p.has_graph(), f"graph present ({p.graph_json})" if p.has_graph() else "no graph yet", "graphsnip build")
+    if p.has_graph():
+        line(not p.is_stale(0), "graph is up to date" if not p.is_stale(0) else "graph is older than some source files", "graphsnip build (the server also refreshes itself)")
+        s = p.graph_stats()
+        line(s["symbols"] > 0, f"{s['symbols']:,} code symbols indexed")
+    mcp_claude = (p.root / ".mcp.json")
+    st = p.root / ".claude" / "settings.json"
+    found = {
+        "claude": mcp_claude.exists() and "graphsnip" in mcp_claude.read_text(encoding="utf-8", errors="ignore"),
+        "copilot": (p.root / ".vscode" / "mcp.json").exists() and "graphsnip" in (p.root / ".vscode" / "mcp.json").read_text(encoding="utf-8", errors="ignore"),
+        "codex": (p.root / ".codex" / "config.toml").exists() and "graphsnip" in (p.root / ".codex" / "config.toml").read_text(encoding="utf-8", errors="ignore"),
+    }
+    for c in CLIENTS:
+        print(f"{'✓' if found[c] else '·'} {c}: {'MCP server registered' if found[c] else 'not installed here (graphsnip install --clients ' + c + ')'}")
+    hook_on = st.exists() and HOOK_MARK in st.read_text(encoding="utf-8", errors="ignore")
+    print(f"{'✓' if hook_on else '·'} claude hook: {'installed' if hook_on else 'not installed'}  (mode: {p.config()['mode']})")
+    print("\nAll good." if ok else "\nSome checks failed; see arrows above.")
+    return 0 if ok else 1
+
+
+def main(argv=None) -> int:
+    common = _common()
+    ap = argparse.ArgumentParser(prog="graphsnip", description="Token-saving layer on top of Graphify.")
+    ap.add_argument("--version", action="version", version=f"graphsnip {__version__}")
+    sub = ap.add_subparsers(dest="cmd")
+
+    def add(name, fn, help_, **kw):
+        sp = sub.add_parser(name, parents=[common], help=help_, **kw)
+        sp.set_defaults(fn=fn)
+        return sp
+
+    sp = add("init", cmd_init, "build graph + install integrations + benchmark + dashboard")
+    sp.add_argument("--clients", default="all", help="claude,copilot,codex or all (default: all)")
+    sp.add_argument("--dry-run", action="store_true")
+    sp.add_argument("--allow-tools", action="store_true", help="Claude Code: pre-approve the read-only graphsnip tools")
+    sp.add_argument("--strict", action="store_true", help="hooks deny redirectable calls instead of nudging")
+    sp.add_argument("--portable", action="store_true", help="write bare `graphsnip` into configs (safe to commit) instead of this machine's path")
+    sp.add_argument("--codex-scope", choices=["project", "user"], default="project")
+    sp.add_argument("--no-build", action="store_true")
+    sp.add_argument("--no-bench", action="store_true")
+
+    sp = add("build", cmd_build, "build or refresh the Graphify graph (code only, no LLM)")
+    sp.add_argument("--force", action="store_true")
+    add("status", cmd_status, "show graph status")
+    sp = add("find", cmd_find, "locate symbols and connections (budgeted map)")
+    sp.add_argument("question")
+    sp.add_argument("--budget", type=int, default=1500)
+    sp.add_argument("--depth", type=int, default=2)
+    sp.add_argument("--quiet", action="store_true")
+    sp = add("symbol", cmd_symbol, "read one function/class with callers and callees")
+    sp.add_argument("name")
+    sp.add_argument("--max-lines", type=int, default=120)
+    sp.add_argument("--full-docs", action="store_true")
+    sp.add_argument("--quiet", action="store_true")
+    sp = add("pack", cmd_pack, "token-budgeted context pack for a task")
+    sp.add_argument("task")
+    sp.add_argument("--budget", type=int, default=4000)
+    sp.add_argument("--quiet", action="store_true")
+    sp = add("impact", cmd_impact, "what depends on a symbol")
+    sp.add_argument("name")
+    sp.add_argument("--depth", type=int, default=2)
+    sp.add_argument("--quiet", action="store_true")
+    sp = add("outline", cmd_outline, "symbols in a file with line numbers")
+    sp.add_argument("path")
+    sp.add_argument("--quiet", action="store_true")
+    sp = add("stats", cmd_stats, "token savings so far")
+    sp.add_argument("--json", action="store_true")
+    sp = add("report", cmd_report, "write the HTML dashboard")
+    sp.add_argument("--open", action="store_true")
+    sp.add_argument("--bundle", metavar="DIR", help="write a self-contained folder (dashboard + graph.html) for sharing")
+    sp = add("bench", cmd_bench, "offline benchmark: grep+read vs Graphify vs graphsnip")
+    sp.add_argument("--tasks", help="tasks JSON (default .graphsnip/tasks.json, auto-generated)")
+    sp.add_argument("--init-tasks", action="store_true", help="(re)write starter tasks")
+    sp.add_argument("--json", action="store_true")
+    sp = add("demo", cmd_demo, "one command for a live demo: graph + benchmark + dashboard")
+    sp.add_argument("--open", action="store_true")
+    sp.add_argument("--bundle", metavar="DIR")
+    add("serve", cmd_serve, "run the MCP server over stdio")
+    sp = add("hook", cmd_hook, "agent hook entry point (reads JSON on stdin)")
+    sp.add_argument("event", choices=["pretooluse"])
+    sp = add("run", cmd_run, "run a command and compress its output (exact token savings)")
+    sp.add_argument("cmd", nargs=argparse.REMAINDER)
+    sp = add("install", cmd_install, "write MCP + hooks + guidance for Claude Code / Copilot / Codex")
+    sp.add_argument("--clients", default="all")
+    sp.add_argument("--dry-run", action="store_true")
+    sp.add_argument("--allow-tools", action="store_true")
+    sp.add_argument("--strict", action="store_true")
+    sp.add_argument("--portable", action="store_true")
+    sp.add_argument("--codex-scope", choices=["project", "user"], default="project")
+    sp = add("uninstall", cmd_uninstall, "remove everything install added")
+    sp.add_argument("--clients", default="all")
+    sp.add_argument("--codex-scope", choices=["project", "user"], default="project")
+    add("doctor", cmd_doctor, "check the setup")
+
+    args = ap.parse_args(argv)
+    if not getattr(args, "fn", None):
+        ap.print_help()
+        return 0
+    try:
+        return int(args.fn(args) or 0)
+    except GraphError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+    except BrokenPipeError:
+        return 0
+    except KeyboardInterrupt:
+        return 130
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())