ctxgraph-code 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

ctxgraph_code/cli.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import os
+import time
 from pathlib import Path
 from typing import Optional
 
@@ -8,6 +9,12 @@ import typer
 from rich.console import Console
 from rich.table import Table
 
+from ctxgraph_code.config.build_status import (
+    get_build_status,
+    get_status_message,
+    mark_build_complete,
+    mark_build_started,
+)
 from ctxgraph_code.config.global_paths import get_global_claude_commands_dir
 from ctxgraph_code.config.init import init_project
 from ctxgraph_code.config.settings import Settings
@@ -66,19 +73,30 @@ def _resolve_storage(
     if dir_name:
         s = get_storage(path, dir_name=dir_name)
         if s:
+            msg = get_status_message(path)
+            if msg:
+                console.print(msg)
             return s
-        console.print(f"[red]Error: No graph found for directory '[bold]{dir_name}[/bold]'.[/red]")
+        console.print("[red]Error: No graph found for directory '[bold]{dir_name}[/bold]'.[/red]")
         _print_avail(avail)
         raise typer.Exit(1)
 
     if avail["_combined"]:
-        return get_storage(path)
+        s = get_storage(path)
+        if s:
+            msg = get_status_message(path)
+            if msg:
+                console.print(msg)
+            return s
 
     if file_arg:
         d = _resolve_dir(path, file_arg)
         if d and d in avail["dirs"]:
             s = get_storage(path, dir_name=d)
             if s:
+                msg = get_status_message(path)
+                if msg:
+                    console.print(msg)
                 return s
 
     if avail["dirs"]:
@@ -237,17 +255,28 @@ def init(
 
 
 def _print_build_hint(path: Path):
-    console.print("\n[yellow]Run [bold]ctxgraph-code build[/bold] to scan files and build the graph.[/yellow]")
+    console.print(
+        "\n[yellow]Run [bold]ctxgraph-code build[/bold]"
+        " to scan files and build the graph.[/yellow]"
+    )
 
 
-def _build_single_graph(path, exts, user_patterns, db_path, label):
+def _build_single_graph(path, exts, user_patterns, db_path, label,
+                         incremental=False, verbose=False, no_summary=False):
+    ctx_dir = path / ".ctxgraph"
+    mark_build_started(ctx_dir, os.getpid())
+    start = time.time()
     with console.status(f"Scanning {', '.join(exts)} files for '{label}'..."):
         stats = build_graph(
             path,
             db_path=db_path,
             exclude_patterns=user_patterns,
             extensions=exts,
+            incremental=incremental,
+            verbose=verbose,
+            no_summary=no_summary,
         )
+    mark_build_complete(ctx_dir, time.time() - start)
 
     table = Table(title=f"Graph Build: {label}")
     table.add_column("Metric", style="cyan")
@@ -261,6 +290,88 @@ def _build_single_graph(path, exts, user_patterns, db_path, label):
     return stats
 
 
+def _build_dir_worker(path, exts, user_patterns, db_path, label,
+                       incremental=False, verbose=False, no_summary=False):
+    """Silent build worker for parallel execution. No console output."""
+    ctx_dir = path / ".ctxgraph"
+    mark_build_started(ctx_dir, os.getpid())
+    start = time.time()
+    stats = build_graph(
+        path,
+        db_path=db_path,
+        exclude_patterns=user_patterns,
+        extensions=exts,
+        incremental=incremental,
+        verbose=verbose,
+        no_summary=no_summary,
+    )
+    mark_build_complete(ctx_dir, time.time() - start)
+    return label, stats
+
+
+def _build_dirs_parallel(path, exts, user_patterns, top_dirs, graphs_dir, jobs,
+                          incremental=False, verbose=False, no_summary=False):
+    """Build per-directory graphs in parallel using a thread pool."""
+    from concurrent.futures import ThreadPoolExecutor, as_completed
+
+    n_workers = max(1, jobs) if jobs > 0 else os.cpu_count() or 1
+    console.print(f"[dim]Building {len(top_dirs)} graphs with {n_workers} workers...[/dim]")
+
+    futures = []
+    with ThreadPoolExecutor(max_workers=n_workers) as pool:
+        for d in top_dirs:
+            db_path = graphs_dir / f"{d.name}.db"
+            fut = pool.submit(
+                _build_dir_worker, path, exts, user_patterns, db_path, d.name,
+                incremental, verbose, no_summary,
+            )
+            futures.append(fut)
+
+        results = []
+        for f in as_completed(futures):
+            try:
+                label, stats = f.result()
+                results.append((label, stats))
+            except Exception as e:
+                results.append(("error", str(e)))
+
+    results.sort(key=lambda x: x[0] if isinstance(x[0], str) else "")
+
+    summary = Table(title="Build Summary")
+    summary.add_column("Directory", style="cyan")
+    summary.add_column("Files", style="green")
+    summary.add_column("Nodes", style="blue")
+    summary.add_column("Edges", style="yellow")
+    summary.add_column("Time", style="magenta")
+
+    total_files = 0
+    total_nodes = 0
+    total_edges = 0
+    total_time = 0.0
+
+    for label, stats in results:
+        if isinstance(stats, str):
+            summary.add_row(f"{label}/", "[red]ERROR[/red]", stats, "", "")
+        else:
+            files = stats.get("files_analyzed", 0)
+            nodes = stats.get("total_nodes", 0)
+            edges = stats.get("total_edges", 0)
+            t = stats.get("elapsed_seconds", 0)
+            summary.add_row(f"{label}/", str(files), str(nodes), str(edges), f"{t}s")
+            total_files += files
+            total_nodes += nodes
+            total_edges += edges
+            total_time = max(total_time, t)
+
+    console.print(summary)
+    console.print(
+        f"\n[green]Built {len(top_dirs)} graphs: "
+        f"{total_files} files, {total_nodes} nodes, {total_edges} edges "
+        f"in {total_time}s[/green]"
+    )
+    return results
+
+
 @app.command()
 def build(
     repo_path: Optional[str] = typer.Argument(
@@ -275,10 +386,22 @@ def build(
     all_graph: bool = typer.Option(
         False, "--all", "-a", help="Build a single combined graph instead of per-directory"
     ),
+    jobs: int = typer.Option(
+        0, "--jobs", "-j", help="Number of parallel workers (0 = auto, default: CPU count)"
+    ),
+    incremental: bool = typer.Option(
+        False, "--incremental", "-i", help="Only rebuild files that changed since last build"
+    ),
+    verbose: bool = typer.Option(
+        False, "--verbose", "-v", help="Show per-file progress"
+    ),
+    no_summary: bool = typer.Option(
+        False, "--no-summary", help="Skip docstring extraction for faster builds"
+    ),
 ):
     """Build the knowledge graph from source files.
 
-    Default: builds a separate graph per top-level directory.
+    Default: builds a separate graph per top-level directory in parallel.
     Use --all to build one combined graph instead.
     """
     path = Path(repo_path).resolve() if repo_path else Path.cwd()
@@ -297,9 +420,9 @@ def build(
 
     if all_graph:
         db_path = ctx_dir / "graph.db"
-        _build_single_graph(path, exts, user_patterns, db_path, "combined")
+        _build_single_graph(path, exts, user_patterns, db_path, "combined",
+                            incremental, verbose, no_summary)
     else:
-        # Per-directory: find top-level dirs (skip excluded ones)
         from ctxgraph_code.exclude.patterns import should_exclude
         top_dirs = sorted([
             d for d in path.iterdir()
@@ -308,34 +431,18 @@ def build(
         ])
 
         if not top_dirs:
-            console.print("[yellow]No top-level source directories found. Building combined graph.[/yellow]")
+            console.print(
+                "[yellow]No top-level source directories found."
+                " Building combined graph.[/yellow]"
+            )
             db_path = ctx_dir / "graph.db"
-            _build_single_graph(path, exts, user_patterns, db_path, "combined")
+            _build_single_graph(path, exts, user_patterns, db_path, "combined",
+                                incremental, verbose, no_summary)
         else:
             graphs_dir = ctx_dir / "graphs"
             graphs_dir.mkdir(parents=True, exist_ok=True)
-
-            total_nodes = 0
-            total_edges = 0
-            for d in top_dirs:
-                db_path = graphs_dir / f"{d.name}.db"
-                s = _build_single_graph(path, exts, user_patterns, db_path, d.name)
-                total_nodes += s.get("total_nodes", 0)
-                total_edges += s.get("total_edges", 0)
-
-            summary = Table(title="Build Summary")
-            summary.add_column("Directory", style="cyan")
-            for d in top_dirs:
-                db = graphs_dir / f"{d.name}.db"
-                if db.exists():
-                    from ctxgraph_code.graph.storage import Storage
-                    st = Storage(db)
-                    st.connect()
-                    nd = st.stats()["nodes"]
-                    ed = st.stats()["edges"]
-                    summary.add_row(f"{d.name}/: {nd} nodes, {ed} edges")
-            console.print(summary)
-            console.print(f"\n[green]Built {len(top_dirs)} graphs in {graphs_dir}[/green]")
+            _build_dirs_parallel(path, exts, user_patterns, top_dirs, graphs_dir, jobs,
+                                 incremental, verbose, no_summary)
 
 
 @app.command()
@@ -490,6 +597,21 @@ def setup(
         False, "--project-slash",
         help="Install slash command in project .claude/ instead of globally",
     ),
+    jobs: int = typer.Option(
+        0, "--jobs", "-j", help="Number of parallel workers (0 = auto, default: CPU count)"
+    ),
+    incremental: bool = typer.Option(
+        False, "--incremental", "-i", help="Only rebuild files that changed since last build"
+    ),
+    verbose: bool = typer.Option(
+        False, "--verbose", "-v", help="Show per-file progress"
+    ),
+    no_summary: bool = typer.Option(
+        False, "--no-summary", help="Skip docstring extraction for faster builds"
+    ),
+    background: bool = typer.Option(
+        False, "--background", "-b", help="Launch build in background and exit immediately"
+    ),
 ):
     """Initialize config, build the graph, and install the Claude Code slash command.
 
@@ -529,7 +651,51 @@ def setup(
     init_project(path, extensions=exts, exclude_patterns=excl)
     console.print("[green][OK] Initialized .ctxgraph/[/green]")
 
-    # Build per-directory graphs
+    # Install slash command FIRST (immediate)
+    if project_slash:
+        claude_dir = path / ".claude" / "commands"
+    else:
+        claude_dir = get_global_claude_commands_dir()
+    slash_path = claude_dir / "ctxgraph-code.md"
+    _write_slash_command(slash_path, path)
+
+    # Build in background via detached subprocess
+    if background:
+        import subprocess
+        import sys
+
+        build_args = [sys.executable, "-m", "ctxgraph_code", "build"]
+        if repo_path:
+            build_args.append(repo_path)
+        if extensions:
+            build_args.extend(["--extensions", extensions])
+        if exclude:
+            build_args.extend(["--exclude", exclude])
+        if jobs:
+            build_args.extend(["--jobs", str(jobs)])
+        if incremental:
+            build_args.append("--incremental")
+        if verbose:
+            build_args.append("--verbose")
+        if no_summary:
+            build_args.append("--no-summary")
+
+        subprocess.Popen(
+            build_args,
+            creationflags=subprocess.DETACHED_PROCESS,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+        console.print("[yellow]Build launched in background.[/yellow]")
+        console.print("Check status with: [bold]ctxgraph-code build-status[/bold]")
+        console.print()
+        console.print("[bold green]Setup complete! Slash command installed.[/bold green]")
+        console.print(
+            "Open any Claude Code project and type [bold]/ctxgraph-code[/bold] to get started."
+        )
+        return
+
+    # Build (synchronous)
     ctx_dir = path / ".ctxgraph"
     graphs_dir = ctx_dir / "graphs"
     graphs_dir.mkdir(parents=True, exist_ok=True)
@@ -539,22 +705,14 @@ def setup(
     ])
 
     if top_dirs:
-        for d in top_dirs:
-            db_path = graphs_dir / f"{d.name}.db"
-            _build_single_graph(path, exts, excl, db_path, d.name)
-        console.print(f"[green][OK] Built graphs for {len(top_dirs)} directories[/green]")
+        _build_dirs_parallel(path, exts, excl, top_dirs, graphs_dir, jobs,
+                             incremental, verbose, no_summary)
     else:
         db_path = ctx_dir / "graph.db"
-        _build_single_graph(path, exts, excl, db_path, "combined")
+        _build_single_graph(path, exts, excl, db_path, "combined",
+                            incremental, verbose, no_summary)
         console.print("[green][OK] Built combined graph[/green]")
 
-    if project_slash:
-        claude_dir = path / ".claude" / "commands"
-    else:
-        claude_dir = get_global_claude_commands_dir()
-    slash_path = claude_dir / "ctxgraph-code.md"
-    _write_slash_command(slash_path, path)
-
     console.print()
     console.print("[bold green]Setup complete![/bold green]")
     console.print(
@@ -586,6 +744,30 @@ def install_slash(
     _write_slash_command(slash_path, path)
 
 
+@app.command(name="build-status")
+def build_status(
+    repo_path: Optional[str] = typer.Option(
+        None, "--repo", "-r", help="Repository path"
+    ),
+):
+    """Show the status of the last or current graph build."""
+    path = Path(repo_path).resolve() if repo_path else Path.cwd()
+    msg = get_status_message(path)
+    if msg:
+        console.print(msg)
+    else:
+        status = get_build_status(path)
+        if not status:
+            console.print("[yellow]No build history found.[/yellow]")
+            console.print("Run [bold]ctxgraph-code build[/bold] to start one.")
+        elif status["status"] == "complete":
+            dur = status.get("duration_s", "?")
+            console.print(f"[green]Last build completed[/green] (duration: {dur}s)")
+        elif status["status"] == "failed":
+            err = status.get("error", "unknown")
+            console.print(f"[red]Last build failed: {err}[/red]")
+
+
 @app.command()
 def view(
     repo_path: Optional[str] = typer.Option(
@@ -684,7 +866,7 @@ def version():
     try:
         ver = _v("ctxgraph-code")
     except Exception:
-        ver = "0.2.0"
+        ver = "0.3.0"
     console.print(f"ctxgraph-code version [bold]{ver}[/bold]")
 
 

ctxgraph_code/config/build_status.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+
+BUILD_STATUS_FILE = "build_status.json"
+
+
+def _status_path(repo_path: Path) -> Path:
+    return repo_path / ".ctxgraph" / BUILD_STATUS_FILE
+
+
+def mark_build_started(repo_path: Path, pid: int) -> dict:
+    data = {
+        "status": "in_progress",
+        "pid": pid,
+        "started_at": datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
+    }
+    p = _status_path(repo_path)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(json.dumps(data), encoding="utf-8")
+    return data
+
+
+def mark_build_complete(repo_path: Path, duration_s: float):
+    p = _status_path(repo_path)
+    data = {"status": "complete", "duration_s": round(duration_s, 1)}
+    p.write_text(json.dumps(data), encoding="utf-8")
+
+
+def mark_build_failed(repo_path: Path, error: str):
+    p = _status_path(repo_path)
+    data = {"status": "failed", "error": error}
+    p.write_text(json.dumps(data), encoding="utf-8")
+
+
+def get_build_status(repo_path: Path) -> Optional[dict]:
+    p = _status_path(repo_path)
+    if not p.exists():
+        return None
+    try:
+        data = json.loads(p.read_text(encoding="utf-8"))
+        return data
+    except (json.JSONDecodeError, OSError):
+        return None
+
+
+def check_pid_running(pid: int) -> bool:
+    """Check if a process with the given PID is still running (Windows)."""
+    try:
+        import ctypes
+        kernel32 = ctypes.windll.kernel32
+        handle = kernel32.OpenProcess(0x1000, False, pid)
+        if not handle:
+            return False
+        kernel32.CloseHandle(handle)
+        return True
+    except Exception:
+        return False
+
+
+def get_status_message(repo_path: Path) -> Optional[str]:
+    status = get_build_status(repo_path)
+    if not status:
+        return None
+
+    if status["status"] == "in_progress":
+        pid = status.get("pid", 0)
+        if pid and not check_pid_running(pid):
+            mark_build_failed(repo_path, "process exited unexpectedly")
+            return (
+                "[red]Previous build appears to have crashed. "
+                "Run [bold]ctxgraph-code build[/bold] to retry.[/red]"
+            )
+        started = status.get("started_at", "unknown")
+        return (
+            f"[yellow]Graph build in progress (PID {pid}, started {started})."
+            f" Results may be partial. Check [bold]ctxgraph-code info[/bold]"
+            f" for status.[/yellow]"
+        )
+
+    if status["status"] == "failed":
+        err = status.get("error", "unknown error")
+        return (
+            f"[red]Previous build failed: {err}."
+            f" Run [bold]ctxgraph-code build[/bold] to retry.[/red]"
+        )
+
+    return None

ctxgraph_code/graph/builder.py

@@ -1,8 +1,10 @@
 from __future__ import annotations
 
 import ast
+import json
 import os
 import time
+from functools import lru_cache
 from pathlib import Path
 from typing import Optional
 
@@ -13,6 +15,28 @@ from ctxgraph_code.exclude.patterns import should_exclude
 from ctxgraph_code.graph.models import Graph
 from ctxgraph_code.graph.storage import Storage
 
+MTIMES_FILE = "file_mtimes.json"
+
+
+def _mtimes_path(repo_path: Path) -> Path:
+    return repo_path / ".ctxgraph" / MTIMES_FILE
+
+
+def _load_mtimes(repo_path: Path) -> dict[str, float]:
+    p = _mtimes_path(repo_path)
+    if not p.exists():
+        return {}
+    try:
+        return json.loads(p.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return {}
+
+
+def _save_mtimes(repo_path: Path, mtimes: dict[str, float]):
+    p = _mtimes_path(repo_path)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(json.dumps(mtimes, indent=1), encoding="utf-8")
+
 
 def build_graph(
     repo_path: str | Path,
@@ -20,6 +44,9 @@ def build_graph(
     exclude_patterns: Optional[list[str]] = None,
     extensions: Optional[list[str]] = None,
     jobs: int = 0,
+    incremental: bool = False,
+    verbose: bool = False,
+    no_summary: bool = False,
 ) -> dict:
     repo_path = Path(repo_path).resolve()
     if db_path is None:
@@ -31,23 +58,32 @@ def build_graph(
     if jobs <= 0:
         jobs = (os.cpu_count() or 1)
 
-    # Walk files with early-exclude pruning + build path_index
+    @lru_cache(maxsize=None)
+    def _should_exclude(path: Path) -> bool:
+        return should_exclude(path, repo_path, exclude_patterns)
+
+    # ── walk files + collect mtimes ────────────────────────────────────────
     path_index: set[str] = set()
     scan_files: list[Path] = []
+    current_mtimes: dict[str, float] = {}
 
     for dirpath, dirnames, filenames in os.walk(repo_path):
-        rel = os.path.relpath(dirpath, repo_path).replace("\\", "/")
         dirnames[:] = [
             d for d in dirnames
-            if not should_exclude(repo_path / d, repo_path, exclude_patterns)
+            if not _should_exclude(repo_path / d)
         ]
         for fn in filenames:
+            if Path(fn).suffix not in exts:
+                continue
             fp = Path(dirpath) / fn
-            if fp.suffix in exts and fp.is_file():
-                rp = str(fp.relative_to(repo_path)).replace("\\", "/")
-                if not should_exclude(fp, repo_path, exclude_patterns):
-                    path_index.add(rp)
-                    scan_files.append(fp)
+            rp = str(fp.relative_to(repo_path)).replace("\\", "/")
+            if not _should_exclude(fp):
+                path_index.add(rp)
+                scan_files.append(fp)
+                try:
+                    current_mtimes[rp] = os.path.getmtime(fp)
+                except OSError:
+                    current_mtimes[rp] = 0.0
 
     if not scan_files:
         elapsed = time.time() - start
@@ -57,69 +93,160 @@ def build_graph(
             "total_nodes": 0, "total_edges": 0,
         }
 
-    stats = {"files_analyzed": 0, "errors": 0}
-
-    use_mp = jobs > 1 and len(scan_files) > 50
+    # ── incremental: filter to changed files only ─────────────────────────
+    changed_files: list[Path] = list(scan_files)
+    old_mtimes: dict[str, float] = {}
+
+    if incremental:
+        old_mtimes = _load_mtimes(repo_path)
+        filtered: list[Path] = []
+        for fp in scan_files:
+            rp = str(fp.relative_to(repo_path)).replace("\\", "/")
+            old_mtime = old_mtimes.get(rp)
+            current_mtime = current_mtimes.get(rp, 0)
+            if old_mtime is None or old_mtime != current_mtime:
+                filtered.append(fp)
+        changed_files = filtered
+
+        removed_paths = old_mtimes.keys() - current_mtimes.keys()
+
+        if not changed_files:
+            elapsed = time.time() - start
+            return {
+                "files_analyzed": 0, "files_skipped": len(scan_files), "errors": 0,
+                "elapsed_seconds": round(elapsed, 2),
+                "total_nodes": 0, "total_edges": 0,
+            }
+
+    stats: dict = {"files_analyzed": 0, "errors": 0}
     all_nodes: list[dict] = []
     all_edges: list[dict] = []
 
+    n_total = len(changed_files)
+    use_mp = jobs > 1 and n_total > 10
+
+    if verbose:
+        from rich.console import Console
+        vconsole = Console()
+        vconsole.log(f"Processing {n_total} files ({len(scan_files)} total) with {jobs} workers...")
+
+    # ── process files ─────────────────────────────────────────────────────
     if use_mp:
         import multiprocessing as mp
-        chunk_size = max(1, len(scan_files) // jobs)
-        chunks = [scan_files[i:i + chunk_size] for i in range(0, len(scan_files), chunk_size)]
+        chunk_size = max(1, n_total // jobs)
+        chunks = [changed_files[i:i + chunk_size] for i in range(0, n_total, chunk_size)]
 
         with mp.Pool(jobs) as pool:
             results = [
-                pool.apply_async(_worker_batch, (chunk, repo_path, path_index))
+                pool.apply_async(_worker_batch, (chunk, repo_path, path_index, no_summary))
                 for chunk in chunks
             ]
-            for r in results:
+            for i, r in enumerate(results):
                 try:
                     nds, eds, ok, err = r.get(timeout=600)
                     all_nodes.extend(nds)
                     all_edges.extend(eds)
                     stats["files_analyzed"] += ok
                     stats["errors"] += err
+                    if verbose:
+                        done = min((i + 1) * chunk_size, n_total)
+                        vconsole.log(f"  [{done}/{n_total}] files done...")
                 except Exception:
-                    pass
+                    stats["errors"] += chunk_size
     else:
-        for file_path in scan_files:
+        for i, file_path in enumerate(changed_files):
             try:
-                nds, eds = _process_file(file_path, repo_path, path_index)
+                nds, eds = _process_file(file_path, repo_path, path_index, no_summary)
                 all_nodes.extend(nds)
                 all_edges.extend(eds)
                 stats["files_analyzed"] += 1
             except Exception:
                 stats["errors"] += 1
+            if verbose and (i + 1) % 50 == 0:
+                from rich.console import Console
+                vconsole = Console()
+                vconsole.log(f"  [{i + 1}/{n_total}] files done...")
 
+    # ── save to DB ────────────────────────────────────────────────────────
     graph = Graph.from_batch(all_nodes, all_edges)
-
     storage = Storage(db_path)
     storage.connect()
+
+    if incremental:
+        for fp in changed_files:
+            rp = str(fp.relative_to(repo_path)).replace("\\", "/")
+            storage.delete_nodes_for_file(rp)
+        for rp in removed_paths:
+            storage.delete_nodes_for_file(rp)
+
     storage.save_graph(graph)
     storage.save_metadata("build_time", str(time.time()))
     storage.save_metadata("repo_path", str(repo_path))
     storage.save_metadata("file_count", str(stats["files_analyzed"]))
     storage.close()
 
+    # ── save mtimes for incremental ───────────────────────────────────────
+    if incremental:
+        _save_mtimes(repo_path, current_mtimes)
+
     elapsed = time.time() - start
     stats["elapsed_seconds"] = round(elapsed, 2)
     stats["total_nodes"] = len(graph.nodes)
     stats["total_edges"] = len(graph.edges)
 
+    if verbose:
+        from rich.console import Console
+        vconsole = Console()
+        vconsole.log(
+            f"Done: {stats['files_analyzed']} files, {stats['total_nodes']} nodes, "
+            f"{stats['total_edges']} edges in {elapsed:.1f}s"
+        )
+
     return stats
 
 
 # ── worker helpers ───────────────────────────────────────────────────────────
 
 
+def _quick_scan(source: str) -> bool:
+    """Quick pre-check: does this file have imports, classes, functions,
+    or decorators? Returns True if full AST parsing is needed."""
+    for line in source.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if any(line.startswith(kw) for kw in ("import ", "from ", "class ", "def ", "@")):
+            return True
+    return False
+
+
 def _process_file(
     file_path: Path,
     root_path: Path,
     path_index: set[str],
+    no_summary: bool = False,
 ) -> tuple[list[dict], list[dict]]:
+    rel = str(file_path.relative_to(root_path)).replace("\\", "/")
+
     try:
         source = file_path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return [], []
+
+    if not _quick_scan(source):
+        return [{
+            "id": f"{root_path}:{rel}",
+            "type": "file",
+            "name": file_path.name,
+            "path": rel,
+            "parent_id": None,
+            "summary": None,
+            "importance": 0.5,
+            "size_bytes": len(source),
+            "lineno": 0,
+        }], []
+
+    try:
         tree = ast.parse(source)
     except SyntaxError:
         return [], []
@@ -139,19 +266,20 @@ def _process_file(
     for ed in sg.edges:
         edges.append(ed.to_dict())
 
-    for nd in sg.nodes.values():
-        if nd.summary is None:
-            enriched = enrich_node_summary(nd, file_path, source=source, tree=tree)
+    if not no_summary:
+        for nd in sg.nodes.values():
+            if nd.summary is None:
+                enriched = enrich_node_summary(nd, file_path, source=source, tree=tree)
+                if enriched:
+                    nd.summary = enriched
+                    nodes.append(nd.to_dict())
+
+        file_node = next((nd for nd in ig.nodes.values() if nd.type == "file"), None)
+        if file_node and file_node.summary is None:
+            enriched = enrich_node_summary(file_node, file_path, source=source, tree=tree)
             if enriched:
-                nd.summary = enriched
-                nodes.append(nd.to_dict())
-
-    file_node = next((nd for nd in ig.nodes.values() if nd.type == "file"), None)
-    if file_node and file_node.summary is None:
-        enriched = enrich_node_summary(file_node, file_path, source=source, tree=tree)
-        if enriched:
-            file_node.summary = enriched
-            nodes.append(file_node.to_dict())
+                file_node.summary = enriched
+                nodes.append(file_node.to_dict())
 
     return nodes, edges
 
@@ -160,6 +288,7 @@ def _worker_batch(
     file_paths: list[Path],
     root_path: Path,
     path_index: set[str],
+    no_summary: bool = False,
 ) -> tuple[list[dict], list[dict], int, int]:
     nodes: list[dict] = []
     edges: list[dict] = []
@@ -167,7 +296,7 @@ def _worker_batch(
     err = 0
     for fp in file_paths:
         try:
-            nds, eds = _process_file(fp, root_path, path_index)
+            nds, eds = _process_file(fp, root_path, path_index, no_summary)
             nodes.extend(nds)
             edges.extend(eds)
             ok += 1

ctxgraph_code/graph/storage.py

@@ -75,37 +75,31 @@ class Storage:
         )
         self.conn.commit()
 
-    def save_node(self, node: Node):
-        self.conn.execute(
-            """INSERT OR REPLACE INTO nodes
-               (id, type, name, path, parent_id, summary, importance, size_bytes, lineno)
-               VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)""",
-            (
-                node.id,
-                node.type,
-                node.name,
-                node.path,
-                node.parent_id,
-                node.summary,
-                node.importance,
-                node.size_bytes,
-                node.lineno,
-            ),
-        )
-
-    def save_edge(self, edge: Edge):
-        self.conn.execute(
-            """INSERT OR REPLACE INTO edges
-               (source_id, target_id, relation, weight)
-               VALUES (?, ?, ?, ?)""",
-            (edge.source_id, edge.target_id, edge.relation, edge.weight),
-        )
-
     def save_graph(self, graph: Graph):
-        for node in graph.nodes.values():
-            self.save_node(node)
-        for edge in graph.edges:
-            self.save_edge(edge)
+        nodes_data = [
+            (n.id, n.type, n.name, n.path, n.parent_id, n.summary,
+             n.importance, n.size_bytes, n.lineno)
+            for n in graph.nodes.values()
+        ]
+        if nodes_data:
+            self.conn.executemany(
+                """INSERT OR REPLACE INTO nodes
+                   (id, type, name, path, parent_id, summary, importance, size_bytes, lineno)
+                   VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+                nodes_data,
+            )
+
+        edges_data = [
+            (e.source_id, e.target_id, e.relation, e.weight)
+            for e in graph.edges
+        ]
+        if edges_data:
+            self.conn.executemany(
+                """INSERT OR REPLACE INTO edges
+                   (source_id, target_id, relation, weight)
+                   VALUES (?, ?, ?, ?)""",
+                edges_data,
+            )
         self.conn.commit()
 
     def get_node(self, node_id: str) -> Optional[Node]:
@@ -210,6 +204,26 @@ class Storage:
             "types": {r["type"]: r["cnt"] for r in type_counts},
         }
 
+    def delete_nodes_for_file(self, file_path: str):
+        """Remove all nodes and edges belonging to a file (for incremental rebuild)."""
+        cursor = self.conn.execute(
+            "SELECT id FROM nodes WHERE path = ?", (file_path,)
+        )
+        node_ids = [r[0] for r in cursor.fetchall()]
+        if not node_ids:
+            return
+        placeholders = ",".join("?" for _ in node_ids)
+        self.conn.execute(
+            "DELETE FROM edges WHERE source_id IN ({}) OR target_id IN ({})".format(
+                placeholders, placeholders
+            ),
+            node_ids + node_ids,
+        )
+        self.conn.execute(
+            f"DELETE FROM nodes WHERE id IN ({placeholders})", node_ids
+        )
+        self.conn.commit()
+
     def save_metadata(self, key: str, value: str):
         self.conn.execute(
             "INSERT OR REPLACE INTO metadata (key, value) VALUES (?, ?)",

{ctxgraph_code-0.2.0.dist-info → ctxgraph_code-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ctxgraph-code
-Version: 0.2.0
+Version: 0.3.0
 Summary: Code knowledge graph for Claude Code. Build a relationship graph of your Python codebase and query it during coding sessions.
 Author: ctxgraph-code contributors
 License: MIT
@@ -76,15 +76,23 @@ Interactive walkthrough — prompts for:
 
 Does everything in one step:
 1. Creates `.ctxgraph/config.toml` with your chosen extensions and excludes
-2. Builds the knowledge graph from all matching files
-3. Creates `.claude/commands/ctxgraph-code.md` with instructions for Claude Code
+2. Installs the `/ctxgraph-code` slash command globally (works in every Claude Code session)
+3. Builds the knowledge graph from all matching files
 
-Non-interactive mode (skip prompts):
+Non-interactive mode:
 ```bash
 ctxgraph-code setup --extensions .py,.js,.ts --exclude tests/,examples/
 ctxgraph-code setup -y                                 # all defaults
 ```
 
+Options:
+- `--project-slash` — install slash command in project's `.claude/` instead of globally
+- `--background` / `-b` — launch build in background and exit immediately (check with `build-status`)
+- `--jobs` / `-j` — number of parallel workers (default: CPU count)
+- `--incremental` / `-i` — only rebuild files that changed since last build
+- `--verbose` / `-v` — show per-file progress
+- `--no-summary` — skip docstring extraction for faster builds
+
 ### `init`
 
 ```bash
@@ -103,24 +111,27 @@ ctxgraph-code build --exclude tests/ --exclude *.generated.py
 
 Scans all matching files in the project, runs AST analysis. Extensions are read from config (`.py` by default, or whatever was set in `setup`).
 
-- **Imports**: which files import other files
-- **Class definitions**: class names, base classes, methods
-- **Function definitions**: function names, arguments
-- **Function calls**: which functions call which (within the project)
-- **Docstrings**: extracted as node summaries
+**By default, builds a separate graph per top-level directory** (e.g., `src/`, `api/`, `tests/`) in parallel. This keeps each graph small and fast to query. Use `--dir <name>` on query commands to select one, or let it auto-detect from file paths.
+
+- `--all` / `-a` — build a single combined graph instead of per-directory
+- `--jobs` / `-j` — number of parallel workers (default: CPU count)
+- `--incremental` / `-i` — only rebuild files that changed since last build
+- `--verbose` / `-v` — show per-file progress
+- `--no-summary` — skip docstring extraction for faster builds
 
-Stores the result in `.ctxgraph/graph.db`.
+Stores graphs in `.ctxgraph/graphs/<dir>.db` (per-directory) or `.ctxgraph/graph.db` (combined).
 
-> The graph is a **static snapshot**. If code changes, run `ctxgraph-code build` again to refresh. Claude Code will also rebuild when it detects the graph is stale.
+> The graph is a **static snapshot**. If code changes, run `ctxgraph-code build` again to refresh. Use `--incremental` to only reprocess changed files.
 
 ### `query`
 
 ```bash
 ctxgraph-code query "user authentication"
 ctxgraph-code query "database connection" --max 20
+ctxgraph-code query "api routes" --dir src
 ```
 
-Searches the graph by relevance scoring (name matches > summary matches > path matches) and expands to neighboring nodes via BFS up to depth 2.
+Searches the graph by relevance scoring (name matches > summary matches > path matches) and expands to neighboring nodes via BFS up to depth 2. Use `--dir` to scope to a specific per-directory graph.
 
 ### `deps`
 
@@ -128,7 +139,7 @@ Searches the graph by relevance scoring (name matches > summary matches > path m
 ctxgraph-code deps src/api/routes.py
 ```
 
-Shows all relationships for a file: imports, imported-by, function calls, class definitions.
+Shows all relationships for a file: imports, imported-by, function calls, class definitions. Auto-detects the per-directory graph from the file path.
 
 ### `usedby`
 
@@ -142,9 +153,10 @@ Shows every file that imports or calls something in the given file. Useful to un
 
 ```bash
 ctxgraph-code overview
+ctxgraph-code overview --dir src
 ```
 
-Prints the project structure: every file with its summary and top-level symbols.
+Prints the project structure: every file with its summary and top-level symbols. Use `--dir` to scope to a per-directory graph.
 
 ### `symbols`
 
@@ -181,10 +193,28 @@ Use `--tree` for a terminal-friendly text view of the directory hierarchy with s
 
 ```bash
 ctxgraph-code info
+ctxgraph-code info --dir src
 ```
 
 Shows graph statistics: node/edge counts, type distribution, build time.
 
+### `install-slash`
+
+```bash
+ctxgraph-code install-slash
+ctxgraph-code install-slash --project-slash   # project-local instead of global
+```
+
+Install or update the `/ctxgraph-code` slash command for Claude Code. By default installs globally so it works in every Claude Code session. Use `--project-slash` to install in the project's `.claude/commands/` directory instead.
+
+### `build-status`
+
+```bash
+ctxgraph-code build-status
+```
+
+Check whether a background build (`ctxgraph-code setup --background` or `ctxgraph-code build`) completed, failed, or is still running. Shows PID and start time for in-progress builds.
+
 ---
 
 ## How It Works
@@ -192,7 +222,7 @@ Shows graph statistics: node/edge counts, type distribution, build time.
 ```
 Python files  ──AST──>  Import/Symbol/Call analysis  ──>  SQLite graph.db
                                                                │
-Claude Code  ──/ctxgraph-code──>  CLI query/deps/overview  <────┘
+Claude Code  ──/ctxgraph-code──>  CLI query/deps/overview  <───┘
 ```
 
 1. **Build phase**: `ctxgraph-code build` parses every `.py` file with Python's `ast` module. It extracts imports, class/function definitions, function calls, and docstrings. The result is a graph of **nodes** (files, classes, functions) and **edges** (imports, defines, extends, calls) stored in SQLite.
@@ -226,25 +256,43 @@ Edge weights: `imports=1.0`, `defines=1.0`, `extends=0.8`, `calls=0.7`
 
 ---
 
-## Using with Claude Code
+## Performance
 
-After `ctxgraph-code setup`, Claude Code in the project directory will have the `/ctxgraph-code` slash command available.
+`ctxgraph-code` includes several optimizations for large codebases:
 
-When you type `/ctxgraph-code`, Claude sees:
+| Optimization | Details |
+|---|---|
+| **Parallel builds** | Per-directory graphs build concurrently via `ThreadPoolExecutor` |
+| **Multiprocessing** | Combined graphs split files across CPU cores via `multiprocessing.Pool` |
+| **`--jobs`** | Control parallelism level (default: CPU count) |
+| **Incremental builds** | `--incremental` caches file mtimes, only reprocesses changed files |
+| **Trivial file skip** | `_quick_scan()` pre-checks before AST parse for files with no imports/classes/functions |
+| **Cached excludes** | `lru_cache` on `should_exclude()` during `os.walk` |
+| **Batch SQLite inserts** | `executemany` instead of per-row `INSERT` statements |
+| **`--no-summary`** | Skips docstring extraction (fastest rebuilds) |
+| **`--background`** | Detach build process and continue working immediately |
+
+---
+
+## Using with Claude Code
+
+After `ctxgraph-code setup`, the `/ctxgraph-code` slash command is installed globally by default — it works in every Claude Code session. Claude sees:
 
 ```
 # ctxgraph-code: Code Relationship Graph
 
-This project has a knowledge graph at `.ctxgraph/graph.db`.
-The graph knows about imports, class hierarchies, and function calls.
-
-Available commands:
-- ctxgraph-code query "search terms"  -- Find relevant files, classes, and functions
-- ctxgraph-code deps <path>           -- Show what a file imports and what calls it
-- ctxgraph-code usedby <path>         -- Show what depends on a file
-- ctxgraph-code overview              -- Show the full project structure
-- ctxgraph-code symbols <path>        -- List classes/functions defined in a file
-- ctxgraph-code context "task"        -- Generate a focused context summary
+**First time in this project?** Tell the user to run `ctxgraph-code setup`.
+**Graph needs refresh?** Tell the user to run `ctxgraph-code build`.
+**Available graphs:** src api tests
+
+**Commands:**
+- `ctxgraph-code query "terms"` -- Find relevant files, classes, and functions
+- `ctxgraph-code deps <path>` -- Show what a file imports and what calls it
+- `ctxgraph-code usedby <path>` -- Show what depends on a file
+- `ctxgraph-code overview --dir <name>` -- Show project structure for a specific graph
+- `ctxgraph-code symbols <path>` -- List classes/functions defined in a file
+- `ctxgraph-code context "task"` -- Generate a focused context summary
+- `ctxgraph-code view --dir <name>` -- Visualize a graph interactively
 ```
 
 Claude then uses these commands as needed during the conversation.
@@ -287,7 +335,7 @@ Built-in default exclusion patterns (always applied): `__pycache__`, `*.pyc`, `.
 
 | Feature | ctxgraph | ctxgraph-code |
 |---------|----------|---------------|
-| CLI commands | 9 (build, capsule, query, view, serve, info, init, ask, chat, history, skill) | 9 (init, build, query, deps, usedby, overview, symbols, context, setup, view, info) |
+| CLI commands | 9+ | 12 (init, build, query, deps, usedby, overview, symbols, context, setup, view, info, install-slash, build-status) |
 | LLM integration | Built-in (Ollama, Claude, OpenAI, Azure) | None (delegates to Claude Code) |
 | Chat sessions | Yes | No |
 | Visualizer | D3.js HTML + SVG | D3.js HTML (`view` opens in browser, `--tree` for text) |

{ctxgraph_code-0.2.0.dist-info → ctxgraph_code-0.3.0.dist-info}/RECORD

@@ -1,6 +1,6 @@
 ctxgraph_code/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 ctxgraph_code/__main__.py,sha256=AfV3Onj_9FoL9W8B5jOWOeIyYF2MwX6S4-wyF9U90wM,41
-ctxgraph_code/cli.py,sha256=1D5PwRWp-GrVlfbBEsv2rngJpLVhB_WFap_OHDr_khw,23884
+ctxgraph_code/cli.py,sha256=5ShvEYTi5JzN01_bPLhsds0oZfAnbQOOiAlyLz4OgxI,30322
 ctxgraph_code/render.py,sha256=zic5X5gKfuqZSL0sAxsAOCkZcHnac0eta2FXO_DNaHQ,12619
 ctxgraph_code/analyzers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 ctxgraph_code/analyzers/python/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -8,20 +8,21 @@ ctxgraph_code/analyzers/python/importer.py,sha256=_5WV-RHK9IzbjCaVi_-1rWCYSuJIu0
 ctxgraph_code/analyzers/python/semantic.py,sha256=gS_y2J6uZ5DoFdEz6fF1lp2cBte7hKOIBz2nrrA5db4,2489
 ctxgraph_code/analyzers/python/symbols.py,sha256=xKtpn-78sh8H_xf7TBs9bzIAO42NnuiY1X92d11nNJ4,6330
 ctxgraph_code/config/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ctxgraph_code/config/build_status.py,sha256=e2tdNc34oJd-iDAi4aFEi-TkY9lIhkicCjmSj6VpvHY,2754
 ctxgraph_code/config/global_paths.py,sha256=Ot1YIzdTqOValsvN_oEstcg8dFcFGCtHo6OnwOp1IYE,511
 ctxgraph_code/config/init.py,sha256=tXVcDTPAJGVbzPavABRfnCXUsf9Pt-VzDUgV5YX09Tc,501
 ctxgraph_code/config/settings.py,sha256=t0Mu0U9T43ztDxxqj2NXGB3BbaY7Ll7e8UMhTLlY-Xw,4873
 ctxgraph_code/exclude/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 ctxgraph_code/exclude/patterns.py,sha256=4jBbiVeMgMmK5c0Kucl5g2xiBtAQ1tVtH8dDXA7lz7g,1624
 ctxgraph_code/graph/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-ctxgraph_code/graph/builder.py,sha256=VreInNG1BuDyCanBzXPe1Q3RQySxDZz563BlmUeFZcw,6759
+ctxgraph_code/graph/builder.py,sha256=XgPfR7ssMaehS3-LwQ4ZGC5MpVJR4N-LPMPfPIyBh8c,11650
 ctxgraph_code/graph/models.py,sha256=0h3qVDHNUvE8zqBBSaTFlY_mBS1A-WrEW66nPU5oouA,2860
 ctxgraph_code/graph/query.py,sha256=qwGIdmTZ7-csL_FMkIdABfwpUCQ1ph9TbDeE3eY_YSU,3414
-ctxgraph_code/graph/storage.py,sha256=BMhcbybFP_hZv58WQTgR1SBldgFPWTuvk6im70MBMpU,7007
+ctxgraph_code/graph/storage.py,sha256=9qy1OEjLozFZSaxaecrQKHNhyAJxIXYIhWxeagHyWDE,7648
 ctxgraph_code/view/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 ctxgraph_code/view/visualizer.py,sha256=xvPn9eSDYAk_HICpL6Nt7CQ_5FOKX0EXpZGM6wwyv9s,10555
-ctxgraph_code-0.2.0.dist-info/METADATA,sha256=T3zcBQSKD4B7Sc2ZAO_JhnB4_4oIYaaVsNVGsOS_SDw,11129
-ctxgraph_code-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-ctxgraph_code-0.2.0.dist-info/entry_points.txt,sha256=Q6poS8LApu1uGl_T9hjoZ7VMC8-iXZFCMslDx6OjlRo,56
-ctxgraph_code-0.2.0.dist-info/top_level.txt,sha256=ZOmow7lPtFHkcRJhLFOP5DVbt_SVaFrzsgXsawzMsq8,14
-ctxgraph_code-0.2.0.dist-info/RECORD,,
+ctxgraph_code-0.3.0.dist-info/METADATA,sha256=MJ3lilCdCVHMn2aVtjVlkQYIf8okvXegFvE1LX3aRe4,13816
+ctxgraph_code-0.3.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+ctxgraph_code-0.3.0.dist-info/entry_points.txt,sha256=Q6poS8LApu1uGl_T9hjoZ7VMC8-iXZFCMslDx6OjlRo,56
+ctxgraph_code-0.3.0.dist-info/top_level.txt,sha256=ZOmow7lPtFHkcRJhLFOP5DVbt_SVaFrzsgXsawzMsq8,14
+ctxgraph_code-0.3.0.dist-info/RECORD,,