{"_id":"@allenmuu/pi-codegraph","_rev":"2-6c4d0f1ed3e64fa9903f1f346778685b","name":"@allenmuu/pi-codegraph","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@allenmuu/pi-codegraph","version":"1.0.0","keywords":["pi","pi-extension","codegraph","code-exploration"],"author":{"name":"AllenMuu"},"license":"MIT","_id":"@allenmuu/pi-codegraph@1.0.0","maintainers":[{"name":"allenmuu","email":"allenqiao666@gmail.com"}],"homepage":"https://github.com/AllenMuu/pi-codegraph#readme","bugs":{"url":"https://github.com/AllenMuu/pi-codegraph/issues"},"dist":{"shasum":"b77e19a1855b7c149a9c6ddbfe6a50ecc8212b5e","tarball":"https://registry.npmjs.org/@allenmuu/pi-codegraph/-/pi-codegraph-1.0.0.tgz","fileCount":27,"integrity":"sha512-5+xxoMnWH76t1b2bLLFncnkizaijjPSkAT03upUiJSH2uYKEI0lY3LCTwqxzoTkJeZp/IOI0pMermvGCMqaG+g==","signatures":[{"sig":"MEUCIQCqhcPyKkW/HOtd7LJnkVSyRsH1CMOc+iMjdWZ3B1nJjAIgJxbpTdxOKsvTlIjXmy3/ZipvX4uu9uCsh7ghjTg2Zjs=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":42564},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=22.0.0"},"gitHead":"5073f1d15e064587105b1e3051bd829590cfb23d","scripts":{"lint":"tsc --noEmit","test":"node --import tsx --test \"test/**/*.test.ts\"","build":"tsc","prepack":"npm run build"},"_npmUser":{"name":"allenmuu","email":"allenqiao666@gmail.com"},"repository":{"url":"git+https://github.com/AllenMuu/pi-codegraph.git","type":"git"},"_npmVersion":"10.9.8","description":"Pi-native extension for CodeGraph structural code exploration","directories":{},"_nodeVersion":"22.23.2","dependencies":{"@sinclair/typebox":"^0.34.48"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.3","typescript":"^5.8.2","@types/node":"^22.13.9"},"_npmOperationalInternal":{"tmp":"tmp/pi-codegraph_1.0.0_1787745405532_0.49029211674254225","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"pi":{"extensions":["./dist/index.js"]},"_id":"@allenmuu/pi-codegraph@1.0.1","bugs":{"url":"https://github.com/AllenMuu/pi-codegraph/issues"},"dist":{"shasum":"bf5d165e8889d77743e65d4bd0fe2f2fe69d9287","tarball":"https://registry.npmjs.org/@allenmuu/pi-codegraph/-/pi-codegraph-1.0.1.tgz","fileCount":27,"integrity":"sha512-gGedmuOXcskJ4J6qwbce18orcYZ1OVZuYe/c49sj9MuJ0BagGOhsxyOs0AA93j7uGboadpu3KwsJrdJFM+4YZQ==","signatures":[{"sig":"MEQCIDjKkYiSb2rFZyIDYcABUmNovbzWoF29nhgJHPf5cf7FAiAGg2lLBJLlcApYAwKPjccUyyEx5jkiP0JYH3Qh+M1fzA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCHwDmF7wPpoXMyuEKB55PPTCXiHGq6iAdixqd/M68RRECIQC5rv1l/utbV/C/hNm0UwH+aLiHBxfau2Pkm/c+ospMwg=="}],"unpackedSize":42715},"main":"dist/index.js","name":"@allenmuu/pi-codegraph","type":"module","types":"dist/index.d.ts","author":{"name":"AllenMuu"},"engines":{"node":">=22.0.0"},"gitHead":"8ee0e437dc8065a914683fe1bb2b23287c9ae817","license":"MIT","scripts":{"lint":"tsc --noEmit","test":"node --import tsx --test \"test/**/*.test.ts\"","build":"tsc","prepack":"npm run build"},"version":"1.0.1","_npmUser":{"name":"allenmuu","email":"allenqiao666@gmail.com"},"homepage":"https://github.com/AllenMuu/pi-codegraph#readme","keywords":["pi-package","pi","pi-extension","codegraph","code-exploration"],"repository":{"url":"git+https://github.com/AllenMuu/pi-codegraph.git","type":"git"},"_npmVersion":"10.9.8","description":"Pi-native extension for CodeGraph structural code exploration","directories":{},"maintainers":[{"name":"allenmuu","email":"allenqiao666@gmail.com"}],"_nodeVersion":"22.23.2","dependencies":{"@sinclair/typebox":"^0.34.48"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.3","typescript":"^5.8.2","@types/node":"^22.13.9"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-codegraph_1.0.1_1788418746008_0.48348779156312705"}}},"time":{"created":"2026-08-26T11:56:45.331Z","modified":"2026-09-03T06:59:06.215Z","1.0.0":"2026-08-26T11:56:45.665Z","1.0.1":"2026-09-03T06:59:06.079Z"},"bugs":{"url":"https://github.com/AllenMuu/pi-codegraph/issues"},"author":{"name":"AllenMuu"},"license":"MIT","homepage":"https://github.com/AllenMuu/pi-codegraph#readme","keywords":["pi-package","pi","pi-extension","codegraph","code-exploration"],"repository":{"url":"git+https://github.com/AllenMuu/pi-codegraph.git","type":"git"},"description":"Pi-native extension for CodeGraph structural code exploration","maintainers":[{"name":"allenmuu","email":"allenqiao666@gmail.com"}],"readme":"# pi-codegraph\n\nA Pi-native extension that provides the [Pi coding agent](https://github.com/badlogic/pi-mono) with structural code exploration capabilities through the [CodeGraph](https://github.com/colbymchenry/codegraph) CLI.\n\n## Core Philosophy\n\n- **Pi-native:** Integrates using Pi's native extension APIs (`registerTool`, `addPromptGuidelines`, `addPromptSnippet`) rather than introducing an MCP server lifecycle or adapter layer.\n- **CodeGraph-compatible:** Interacts strictly through CodeGraph's public CLI interface (`codegraph explore <query>`). It does not touch `.codegraph` database internals or import internal CodeGraph packages.\n- **Upstream-independent:** Functions independently without requiring CodeGraph upstream modifications, forks, or PRs.\n\n## Prerequisites\n\n1. **Node.js 22+** (macOS, Linux; Windows experimental).\n2. **CodeGraph CLI** installed and available on your system `PATH`:\n   ```sh\n   # Verify CodeGraph CLI is available\n   codegraph --version\n   ```\n3. **Initialized Workspace Index:** The active workspace must have a `.codegraph/` index:\n   ```sh\n   # Run in your project root once\n   codegraph init\n   ```\n\n## Installation\n\n### Option 1: npm Package\n\nInstall the package as a Pi package:\n\n```sh\npi install npm:@allenmuu/pi-codegraph\n```\n\nPi will load the extension from the package manifest automatically. For a manual import in a custom Pi setup:\n\n```ts\nimport registerPiExtension from \"@allenmuu/pi-codegraph\";\n\nexport default function (pi) {\n  registerPiExtension(pi);\n}\n```\n\n### Option 2: Copyable Single-File Extension\n\nFor local trial or direct audit without npm dependencies, copy [`examples/pi-codegraph.ts`](examples/pi-codegraph.ts) into your local Pi extensions directory.\n\n## Features & LLM Capabilities\n\n### `codegraph_explore`\n\nExposes exactly one focused LLM-callable tool:\n\n```json\n{\n  \"query\": \"How does authentication flow from API endpoints to the database?\"\n}\n```\n\n### Prompt Routing Guidance\n\nThe extension injects native prompt guidelines advising the agent when to choose `codegraph_explore`:\n\n- **Use `codegraph_explore` for:**\n  - System or module architecture\n  - Multi-file feature implementations\n  - Symbol relationships and implementations\n  - Call paths and request lifecycles\n  - Cross-file dependencies and change blast radius\n- **Use built-in `grep` / `find` / `read` for:**\n  - Exact literal string matching\n  - Known files and line numbers\n  - Documentation, configuration, build scripts, or generated files\n\n## Security & Reliability Guardrails\n\n- **Workspace Sandbox:** Derived exclusively from the active Pi session (`cwd`); LLM cannot supply arbitrary directory paths.\n- **Safe Process Spawning:** Uses argument arrays (`spawn`), strictly preventing shell interpolation and injection risks.\n- **Output Bounds:** Exploration output is capped at 50 KB or 2,000 lines with an explicit truncation notice to prevent model context exhaustion.\n- **Timeout & Cancellation:** 30-second timeout (`CODEGRAPH_TIMEOUT`) and `AbortSignal` cancellation propagation ensure child processes are terminated promptly.\n- **Zero Network & Zero Telemetry:** Sends no external network requests and collects no telemetry.\n\n## Normalized Error Codes\n\nProcess failures return actionable error messages without leaking internal Node stack traces:\n\n| Error Code | Meaning | Remediation |\n| --- | --- | --- |\n| `CODEGRAPH_NOT_FOUND` | CLI binary not located on `PATH` | Install CodeGraph or update system `PATH`. |\n| `CODEGRAPH_NOT_INITIALIZED` | Workspace missing `.codegraph/` | Run `codegraph init` in workspace. |\n| `CODEGRAPH_TIMEOUT` | Process exceeded 30 seconds | Refine query to be more specific. |\n| `CODEGRAPH_ABORTED` | Cancelled by agent signal | Re-run if cancelled unintentionally. |\n| `CODEGRAPH_COMMAND_FAILED` | CLI returned non-zero exit | Inspect the bounded stderr tail (up to 4 KB). |\n\n## Development\n\n```sh\nnpm install       # Install dependencies\nnpm run build     # Compile TypeScript (tsc)\nnpm test          # Run test suite\nnpm run lint      # Static type-check\n```\n\n## License\n\n[MIT](LICENSE)\n","readmeFilename":"README.md"}