workspace-graph 0.1.0__tar.gz

workspace_graph-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,36 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6.0.2
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v6.2.0
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Run tests
+        run: uv run pytest
+
+      - name: Build
+        run: uv build
+
+      - name: Publish
+        run: uv publish --trusted-publishing always

workspace_graph-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.env
+.venv
+.codegraph/
+dist/
+*.egg-info/
+.coverage

workspace_graph-0.1.0/AGENTS.md

@@ -0,0 +1,105 @@
+# codegraph — Project DNA
+
+## Vision
+A thin orchestration layer that sits at the root of a multi-language, multi-repository
+workspace (monorepo or submodule-based). It auto-discovers every service, frontend,
+gateway, and library, orchestrates builds using language-specific tools (gograph,
+tsgraph, pygraph), merges all graph.json outputs into a single unified graph, and
+exposes one MCP server for querying any symbol across any service.
+
+## Design Philosophy (Orchestrator, not a parser)
+codegraph is not an indexer — it orchestrates indexers. Key design points:
+- **Language-agnostic** — no language is special. Every entry is equal in the schema.
+- **Resilient** — one failed entry build doesn't block others. Partial results are useful.
+- **Clean state** — single `.codegraph/` output directory. `codegraph clean` removes everything.
+- **User-enriched** — auto-detection is best-effort; override via `codegraph.jsonc`.
+- **Type classification** — entries get a `type` field (service, frontend, gateway, library,
+  proto, etc.) detected by heuristics and overridable by the user. Used as a query filter only.
+- **Unbuilt languages** — Rust, Java, and other languages are detected and listed but not
+  indexed (no graph tool yet). The user sees them in `status` output.
+
+### Boundaries
+- **gograph/tsgraph/pygraph**: Own all per-language extraction (symbols, calls, routes,
+  HTTP client calls, errors, env reads, test edges). One tool per language.
+- **codegraph**: Owns workspace orchestration, cross-service analysis, and unified MCP.
+  Does NOT duplicate per-language extraction that belongs in gograph/tsgraph/pygraph.
+- If a capability is language-specific, it belongs in the per-language tool first.
+  codegraph only combines, correlates, and queries outputs from those tools.
+
+## Tech Stack
+- Runtime: Python 3.11+
+- Package manager: `uv`
+- CLI: `typer`
+- MCP: `mcp` Python SDK
+- Config parsing: `pydantic` for schema validation
+- File scanning: `pathspec` for gitignore support
+- Testing: `pytest` + `pytest-cov`
+- Linting: `ruff`
+- Type checking: `mypy` (strict mode)
+
+## Installation (for AI Agents)
+
+Install all tools:
+
+```bash
+# Python tools
+pip install codegraph-mcp pygraph-mcp
+
+# TypeScript tool
+npm install -g @shvmgyl15/tsgraph
+
+# Go tool
+git clone https://github.com/shvmgyl15/gograph
+cd gograph && go build -o ~/.local/bin/gograph ./cmd/gograph
+
+# Verify
+codegraph status
+```
+
+Or install everything from git source in one step:
+
+```bash
+git clone https://github.com/shvmgyl15/codegraph
+cd codegraph && ./scripts/install.sh
+```
+
+## Agent Rules
+
+### Task Management
+- READ TODOS.md at session start to know what's done and what's next
+- UPDATE TODOS.md when you start/finish a task (`[.]` in-progress, `[x]` done)
+- Work in phase order unless a task has no blockers
+- After a phase completes (all items `[x]`), run `git init` if not yet done,
+  then commit and push: `git add -A && git commit -m "phase N: <title>" && git push origin main`
+
+### Orchestration
+- This is a single-orchestrator project. When a task has multiple independent
+  sub-tasks, delegate via the `task` tool (`subagent_type: general`) rather
+  than doing them sequentially.
+- For each delegated sub-task, specify:
+  1. Exact files the sub-agent may modify
+  2. Which phase from TODOS.md it belongs to
+  3. What to return (never let sub-agents commit or merge)
+- After all sub-tasks complete, run `uv run pytest && uv run mypy src && uv run ruff check`
+  and fix any issues directly. Do NOT re-delegate broken builds.
+
+### Quality
+- Run `uv run pytest`, `uv run mypy src`, and `uv run ruff check` after every task completion
+- Fix all failures before marking `[x]`
+- If the project is already broken when you start, note it in TODOS.md and fix it first
+
+### Research
+- Use webfetch when unsure about an API — check Python `ast` docs, typer docs, mcp SDK docs
+- Reference gograph, tsgraph, pygraph source for their graph.json output formats
+- DO NOT guess API signatures
+
+### Code Style
+- No comments in source files unless logic is non-obvious
+- Type annotations everywhere, avoid `Any`
+- Follow patterns from adjacent files in the codebase
+- No emojis in source code or commit messages
+- Follow PEP 8 conventions (enforced by ruff)
+
+### Communication
+- Be concise. Use TODOS.md for status, respond with only what's needed.
+- If stuck, explain the blocker clearly rather than overthinking.

workspace_graph-0.1.0/PKG-INFO

@@ -0,0 +1,250 @@
+Metadata-Version: 2.4
+Name: workspace-graph
+Version: 0.1.0
+Summary: Multi-language workspace code graph orchestrator
+Project-URL: Homepage, https://github.com/shvmgyl15/codegraph
+Project-URL: Repository, https://github.com/shvmgyl15/codegraph
+Project-URL: Issues, https://github.com/shvmgyl15/codegraph/issues
+Author-email: Shivam Goel <sg15rokz@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: mcp>=1.0
+Requires-Dist: pathspec>=1.1.1
+Requires-Dist: pydantic>=2.0
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# codegraph
+
+Multi-language workspace code graph orchestrator.
+
+Auto-discovers services, frontends, gateways, and libraries in a workspace,
+orchestrates builds using language-specific tools ([gograph](https://github.com/shvmgyl15/gograph),
+[tsgraph](https://github.com/shvmgyl15/tsgraph), [pygraph](https://github.com/shvmgyl15/pygraph)),
+merges their graph.json outputs into a unified graph, and exposes a single MCP
+server for querying any symbol across any service.
+
+**Install from git source only.** Do not use PyPI or npm — there are unrelated
+packages with the same names. All 4 repos must be installed together from
+source to stay in sync.
+
+## Quick Start
+
+```bash
+# 1. Clone all 4 repos as siblings
+git clone https://github.com/shvmgyl15/gograph
+git clone https://github.com/shvmgyl15/tsgraph
+git clone https://github.com/shvmgyl15/pygraph
+git clone https://github.com/shvmgyl15/codegraph
+
+# 2. Run the install script (builds all tools from source)
+cd codegraph && ./scripts/install.sh
+
+# 3. Create workspace config
+#    (or run from a directory with go.mod/package.json/pyproject.toml subdirectories)
+echo '{"version":1,"entries":[{"name":"frontend","path":"./frontend","language":"typescript","type":"frontend"},{"name":"api","path":"./api","language":"python","type":"service"}]}' > ../codegraph.json
+
+# 4. Build the unified graph
+codegraph build
+
+# 5. Query across all services
+codegraph query "getUser"
+codegraph callers "get_user"
+codegraph routes
+codegraph orphans
+
+# 6. Start MCP server for AI agents
+codegraph mcp
+
+# 7. Generate .opencode.json for AI agent integration
+codegraph add-opencode-plugin
+
+# 8. Clean up
+codegraph clean
+```
+
+## Requirements
+
+- Python 3.11+
+- Go 1.22+ (for gograph)
+- Node.js 20+ (for tsgraph)
+- [uv](https://docs.astral.sh/uv/) (Python package manager)
+
+## Install
+
+```bash
+# Install all tools from local git source:
+./scripts/install.sh
+
+# This builds:
+#   gograph  → ~/.local/bin/gograph   (from ../gograph)
+#   tsgraph  → ~/.local/bin/tsgraph   (from ../tsgraph)
+#   pygraph  → ~/.local/bin/pygraph   (from ../pygraph)
+#   codegraph → ~/.local/bin/codegraph (from current dir)
+```
+
+The script looks for sibling repos (`../gograph`, `../tsgraph`, `../pygraph`).
+It builds each from source and installs binaries to `~/.local/bin/`.
+
+## Uninstall
+
+```bash
+./scripts/uninstall.sh
+```
+
+Removes all binaries from `~/.local/bin/`, all `.gograph`/`.tsgraph`/`.pygraph`/`.codegraph`
+output directories, virtual envs, `node_modules`, caches, and lock files from all 4 repos.
+
+## Configuration
+
+Create `codegraph.jsonc` or `codegraph.json` at your workspace root:
+
+```jsonc
+{
+  "version": 1,
+  "auto_discover": true,
+  "entries": [
+    { "name": "frontend",     "path": "./frontend",    "language": "typescript", "type": "frontend" },
+    { "name": "api-gateway",  "path": "./api-gateway", "language": "python",     "type": "gateway" },
+    { "name": "user-svc",     "path": "./user-svc",    "language": "go",         "type": "service" },
+    { "name": "py-common",    "path": "./libs/py-common", "language": "python",  "type": "library" }
+  ],
+  "plugins": ["./scripts/custom_enrichment.py"]
+}
+```
+
+When `auto_discover: true`, codegraph probes subdirectories for `go.mod`,
+`package.json`, `pyproject.toml`, `Cargo.toml`, `pom.xml` etc.
+
+### The `--root` parameter
+
+`--root` specifies the **workspace root directory** — the same directory where
+you ran `codegraph build`. It tells codegraph where to find the `.codegraph/`
+output folder. It is NOT a query scope filter.
+
+```bash
+# Build in /home/user/myproject
+codegraph build --root /home/user/myproject
+
+# Query the same workspace
+codegraph context get_user --root /home/user/myproject
+```
+
+If you pass the wrong `--root`, codegraph suggests the correct one.
+
+## CLI Commands
+
+| Command | Description |
+|---|---|
+| `status` | List discovered entries with build status |
+| `build` | Build graph for all entries (`--entry` for one) |
+| `clean` | Remove `.codegraph/` output directory |
+| `query <pattern>` | Search symbols by regex or substring |
+| `callers <name>` | Who calls a given symbol |
+| `callees <name>` | What a symbol calls |
+| `routes` | List all HTTP routes (`--entry`, `--type`) |
+| `impact <name>` | BFS downstream blast radius (`--max-depth`) |
+| `orphans` | Dead code detection (`--all`, `--exclude-type`) |
+| `context <name>` | Full bundle: symbol + callers + callees + tests |
+| `trace <message>` | Error flow search with reverse call chain |
+| `cross-service` | Cross-service HTTP call edges |
+| `add-opencode-plugin` | Generate `.opencode.json` for AI agent config |
+| `mcp` | Start MCP stdio server |
+
+## MCP Tools (for AI Agents)
+
+All MCP tool responses include a `duration_ms` field showing how long the query
+took. List responses are wrapped in `{"items": [...], "duration_ms": N}`.
+
+| Tool | Description |
+|---|---|
+| `entry_status` | List entries with language, type, build status |
+| `query_symbols` | Search symbols across all entries |
+| `callers` / `callees` | Who calls / what a symbol calls |
+| `context` | Symbol + callers + callees + tests |
+| `routes` | HTTP routes with entry/type filters |
+| `impact` | Blast radius with max depth |
+| `orphans` | Dead code with include-public and exclude-type |
+| `trace` | Error message search with backtrace |
+| `cross_service_calls` | Cross-service HTTP call edges |
+| `add_opencode_plugin` | Generate AI agent config |
+
+## Performance
+
+- **Build**: Entries are built in parallel (4 workers). Per-entry timing shown.
+- **MCP queries**: The graph is loaded and indexed once, then cached in memory
+  for subsequent queries within the same MCP session. Each response includes
+  `duration_ms` so you can monitor performance.
+
+## Plugin System
+
+User-provided Python scripts that run post-merge to enrich the graph. Configured
+in `codegraph.jsonc`:
+
+```jsonc
+{ "plugins": ["./scripts/enrich.py"] }
+```
+
+Plugin script interface:
+
+```python
+from codegraph.graph.types import UnifiedGraph
+
+def run(graph: UnifiedGraph) -> None:
+    # Mutate graph in-place
+    graph.cross_service_edges.append({
+        "source_entry": "frontend",
+        "source_file": "src/api.ts",
+        "source_line": 10,
+        "source_symbol": "loadUsers",
+        "method": "GET",
+        "url_pattern": "/api/users",
+        "target_entry": "api",
+        "target_route_path": "/api/users",
+        "target_route_handler": "get_users",
+        "confidence": "high",
+    })
+```
+
+## Troubleshooting
+
+| Problem | Solution |
+|---|---|
+| `codegraph: command not found` | Run `./scripts/install.sh` — make sure `~/.local/bin` is on PATH |
+| `Graph not found at ...` | You passed a wrong `--root`. Run `codegraph build` in your workspace root first, then use the same root for queries. |
+| MCP queries are slow | First call loads and indexes the graph (takes a few seconds for large workspaces). Subsequent calls use the in-memory cache and are fast. |
+| `pip install codegraph` installs wrong package | codegraph is NOT on PyPI. Use `./scripts/install.sh` from the git repo. |
+| `npm install tsgraph` installs wrong package | tsgraph is NOT on npm. Use `./scripts/install.sh` from the git repo. |
+
+## Architecture
+
+```
+codegraph (orchestrator)
+  ├── gograph  ─── indexes Go codebases
+  ├── tsgraph  ─── indexes TypeScript/Next.js codebases
+  └── pygraph  ─── indexes Python/Flask codebases
+
+Output: .codegraph/workspace.graph.json  (merged)
+        .codegraph/manifest.json          (entry metadata)
+```
+
+- Each per-language tool produces its own `graph.json`
+- codegraph merges them, stamps entries with metadata
+- Cross-service edges are detected via URL → route matching
+- Plugins can enrich the graph post-merge
+- Single MCP server exposes all query tools
+- WorkspaceQuery is cached in memory across MCP calls
+
+## Related
+
+- [gograph](https://github.com/shvmgyl15/gograph) — Go codebase indexer
+- [tsgraph](https://github.com/shvmgyl15/tsgraph) — TypeScript/React/Next.js indexer
+- [pygraph](https://github.com/shvmgyl15/pygraph) — Python/Flask codebase indexer

workspace_graph-0.1.0/README.md

@@ -0,0 +1,226 @@
+# codegraph
+
+Multi-language workspace code graph orchestrator.
+
+Auto-discovers services, frontends, gateways, and libraries in a workspace,
+orchestrates builds using language-specific tools ([gograph](https://github.com/shvmgyl15/gograph),
+[tsgraph](https://github.com/shvmgyl15/tsgraph), [pygraph](https://github.com/shvmgyl15/pygraph)),
+merges their graph.json outputs into a unified graph, and exposes a single MCP
+server for querying any symbol across any service.
+
+**Install from git source only.** Do not use PyPI or npm — there are unrelated
+packages with the same names. All 4 repos must be installed together from
+source to stay in sync.
+
+## Quick Start
+
+```bash
+# 1. Clone all 4 repos as siblings
+git clone https://github.com/shvmgyl15/gograph
+git clone https://github.com/shvmgyl15/tsgraph
+git clone https://github.com/shvmgyl15/pygraph
+git clone https://github.com/shvmgyl15/codegraph
+
+# 2. Run the install script (builds all tools from source)
+cd codegraph && ./scripts/install.sh
+
+# 3. Create workspace config
+#    (or run from a directory with go.mod/package.json/pyproject.toml subdirectories)
+echo '{"version":1,"entries":[{"name":"frontend","path":"./frontend","language":"typescript","type":"frontend"},{"name":"api","path":"./api","language":"python","type":"service"}]}' > ../codegraph.json
+
+# 4. Build the unified graph
+codegraph build
+
+# 5. Query across all services
+codegraph query "getUser"
+codegraph callers "get_user"
+codegraph routes
+codegraph orphans
+
+# 6. Start MCP server for AI agents
+codegraph mcp
+
+# 7. Generate .opencode.json for AI agent integration
+codegraph add-opencode-plugin
+
+# 8. Clean up
+codegraph clean
+```
+
+## Requirements
+
+- Python 3.11+
+- Go 1.22+ (for gograph)
+- Node.js 20+ (for tsgraph)
+- [uv](https://docs.astral.sh/uv/) (Python package manager)
+
+## Install
+
+```bash
+# Install all tools from local git source:
+./scripts/install.sh
+
+# This builds:
+#   gograph  → ~/.local/bin/gograph   (from ../gograph)
+#   tsgraph  → ~/.local/bin/tsgraph   (from ../tsgraph)
+#   pygraph  → ~/.local/bin/pygraph   (from ../pygraph)
+#   codegraph → ~/.local/bin/codegraph (from current dir)
+```
+
+The script looks for sibling repos (`../gograph`, `../tsgraph`, `../pygraph`).
+It builds each from source and installs binaries to `~/.local/bin/`.
+
+## Uninstall
+
+```bash
+./scripts/uninstall.sh
+```
+
+Removes all binaries from `~/.local/bin/`, all `.gograph`/`.tsgraph`/`.pygraph`/`.codegraph`
+output directories, virtual envs, `node_modules`, caches, and lock files from all 4 repos.
+
+## Configuration
+
+Create `codegraph.jsonc` or `codegraph.json` at your workspace root:
+
+```jsonc
+{
+  "version": 1,
+  "auto_discover": true,
+  "entries": [
+    { "name": "frontend",     "path": "./frontend",    "language": "typescript", "type": "frontend" },
+    { "name": "api-gateway",  "path": "./api-gateway", "language": "python",     "type": "gateway" },
+    { "name": "user-svc",     "path": "./user-svc",    "language": "go",         "type": "service" },
+    { "name": "py-common",    "path": "./libs/py-common", "language": "python",  "type": "library" }
+  ],
+  "plugins": ["./scripts/custom_enrichment.py"]
+}
+```
+
+When `auto_discover: true`, codegraph probes subdirectories for `go.mod`,
+`package.json`, `pyproject.toml`, `Cargo.toml`, `pom.xml` etc.
+
+### The `--root` parameter
+
+`--root` specifies the **workspace root directory** — the same directory where
+you ran `codegraph build`. It tells codegraph where to find the `.codegraph/`
+output folder. It is NOT a query scope filter.
+
+```bash
+# Build in /home/user/myproject
+codegraph build --root /home/user/myproject
+
+# Query the same workspace
+codegraph context get_user --root /home/user/myproject
+```
+
+If you pass the wrong `--root`, codegraph suggests the correct one.
+
+## CLI Commands
+
+| Command | Description |
+|---|---|
+| `status` | List discovered entries with build status |
+| `build` | Build graph for all entries (`--entry` for one) |
+| `clean` | Remove `.codegraph/` output directory |
+| `query <pattern>` | Search symbols by regex or substring |
+| `callers <name>` | Who calls a given symbol |
+| `callees <name>` | What a symbol calls |
+| `routes` | List all HTTP routes (`--entry`, `--type`) |
+| `impact <name>` | BFS downstream blast radius (`--max-depth`) |
+| `orphans` | Dead code detection (`--all`, `--exclude-type`) |
+| `context <name>` | Full bundle: symbol + callers + callees + tests |
+| `trace <message>` | Error flow search with reverse call chain |
+| `cross-service` | Cross-service HTTP call edges |
+| `add-opencode-plugin` | Generate `.opencode.json` for AI agent config |
+| `mcp` | Start MCP stdio server |
+
+## MCP Tools (for AI Agents)
+
+All MCP tool responses include a `duration_ms` field showing how long the query
+took. List responses are wrapped in `{"items": [...], "duration_ms": N}`.
+
+| Tool | Description |
+|---|---|
+| `entry_status` | List entries with language, type, build status |
+| `query_symbols` | Search symbols across all entries |
+| `callers` / `callees` | Who calls / what a symbol calls |
+| `context` | Symbol + callers + callees + tests |
+| `routes` | HTTP routes with entry/type filters |
+| `impact` | Blast radius with max depth |
+| `orphans` | Dead code with include-public and exclude-type |
+| `trace` | Error message search with backtrace |
+| `cross_service_calls` | Cross-service HTTP call edges |
+| `add_opencode_plugin` | Generate AI agent config |
+
+## Performance
+
+- **Build**: Entries are built in parallel (4 workers). Per-entry timing shown.
+- **MCP queries**: The graph is loaded and indexed once, then cached in memory
+  for subsequent queries within the same MCP session. Each response includes
+  `duration_ms` so you can monitor performance.
+
+## Plugin System
+
+User-provided Python scripts that run post-merge to enrich the graph. Configured
+in `codegraph.jsonc`:
+
+```jsonc
+{ "plugins": ["./scripts/enrich.py"] }
+```
+
+Plugin script interface:
+
+```python
+from codegraph.graph.types import UnifiedGraph
+
+def run(graph: UnifiedGraph) -> None:
+    # Mutate graph in-place
+    graph.cross_service_edges.append({
+        "source_entry": "frontend",
+        "source_file": "src/api.ts",
+        "source_line": 10,
+        "source_symbol": "loadUsers",
+        "method": "GET",
+        "url_pattern": "/api/users",
+        "target_entry": "api",
+        "target_route_path": "/api/users",
+        "target_route_handler": "get_users",
+        "confidence": "high",
+    })
+```
+
+## Troubleshooting
+
+| Problem | Solution |
+|---|---|
+| `codegraph: command not found` | Run `./scripts/install.sh` — make sure `~/.local/bin` is on PATH |
+| `Graph not found at ...` | You passed a wrong `--root`. Run `codegraph build` in your workspace root first, then use the same root for queries. |
+| MCP queries are slow | First call loads and indexes the graph (takes a few seconds for large workspaces). Subsequent calls use the in-memory cache and are fast. |
+| `pip install codegraph` installs wrong package | codegraph is NOT on PyPI. Use `./scripts/install.sh` from the git repo. |
+| `npm install tsgraph` installs wrong package | tsgraph is NOT on npm. Use `./scripts/install.sh` from the git repo. |
+
+## Architecture
+
+```
+codegraph (orchestrator)
+  ├── gograph  ─── indexes Go codebases
+  ├── tsgraph  ─── indexes TypeScript/Next.js codebases
+  └── pygraph  ─── indexes Python/Flask codebases
+
+Output: .codegraph/workspace.graph.json  (merged)
+        .codegraph/manifest.json          (entry metadata)
+```
+
+- Each per-language tool produces its own `graph.json`
+- codegraph merges them, stamps entries with metadata
+- Cross-service edges are detected via URL → route matching
+- Plugins can enrich the graph post-merge
+- Single MCP server exposes all query tools
+- WorkspaceQuery is cached in memory across MCP calls
+
+## Related
+
+- [gograph](https://github.com/shvmgyl15/gograph) — Go codebase indexer
+- [tsgraph](https://github.com/shvmgyl15/tsgraph) — TypeScript/React/Next.js indexer
+- [pygraph](https://github.com/shvmgyl15/pygraph) — Python/Flask codebase indexer

workspace_graph-0.1.0/TODOS.md

@@ -0,0 +1,56 @@
+# codegraph — Multi-language Workspace Code Graph
+
+## Vision
+
+`codegraph` is a thin orchestration layer that sits at the root of a multi-language,
+multi-repository workspace (monorepo or submodule-based). It:
+
+1. **Auto-discovers** every service, frontend, gateway, and library in the workspace
+2. **Orchestrates builds** by shelling out to language-specific tools (`gograph`,
+   `tsgraph`, `pygraph`) in each entry's directory
+3. **Merges** all per-entry `graph.json` outputs into a single unified graph
+4. **Exposes a single MCP server** with tools that can query any symbol in any
+   service, regardless of language
+
+### Design principles
+
+- **Language-agnostic** — no language is special. All entries are equal in the schema.
+- **Resilient** — one entry failing to build doesn't block others. Partial results are useful.
+- **Clean state** — single `.codegraph/` output directory. `codegraph clean` removes everything.
+- **User-enriched** — auto-detection is a best-effort default. The user overrides via `codegraph.jsonc`.
+
+---
+
+## Completed
+
+- [x] Phase 1: Scaffold + Config + Auto-Discovery
+- [x] Phase 2: Merge + Query Engine
+- [x] Phase 3: MCP Server
+- [x] Phase 4: Cross-Service Edges
+- [x] Phase 5: Plugin System + README + OpenCode
+
+## Phase 6: Performance + Install/Uninstall Scripts
+
+### Batch A — Performance fixes
+
+MCP was slow because the full graph was deserialized and indexed on every tool call.
+Build was slow because entries were built sequentially with no output.
+
+- [x] A1: Cache WorkspaceQuery in MCP server by root path (loaded once per session)
+- [x] A2: Return duration_ms in every MCP tool response
+- [x] A3: Parallelize builds with ThreadPoolExecutor (max_workers=4)
+- [x] A4: Print per-entry build progress with timing
+- [x] A5: Improve `--root` error message (suggest where graph was actually built)
+
+### Batch B — Install/Uninstall scripts (from git source, never PyPI/npm)
+
+- [x] B1: `scripts/install.sh` — clone/build all 4 tools from git source, install to ~/.local/bin
+- [x] B2: `scripts/uninstall.sh` — remove all tool binaries, .*graph/ output dirs, venvs, caches
+
+### Batch C — README rewrite
+
+- [x] C1: Replace `pip install` with `git clone + scripts/install.sh`
+- [x] C2: Document `--root` clearly (workspace root, not query scope)
+- [x] C3: Add troubleshooting section for performance
+- [x] C4: Add uninstall instructions
+- [x] C5: Run tests + lint, commit, push