pi-project-map

A Pi extension and command-line tool that generates paired project-navigation artifacts: .pi-map.index.md files for routing and .pi-map.md files for directory orientation. The artifacts help agents navigate a codebase; source remains the authority.

Status and limitations

Generation and repair commands call an LLM and write map artifacts into the target project.
validate without --fix checks artifacts without creating an LLM client; validate --fix can modify them and requires an LLM.
Token budgeting and relevant-turn detection are best-effort. Retrieved maps route and orient work but do not replace source verification.
No Node.js version requirement or deployment configuration is declared in this repository.

Install and develop

Install the published CLI globally:

npm install -g pi-project-map

For local development, install dependencies and build from this repository:

npm install
npm run build

Available development checks:

npm run test
npm run lint
npm run typecheck
npm run dev

npm run dev runs TypeScript in watch mode. The project declares no deployment command.

Use the CLI

Run the installed project-map command from the project to map. Use --help or --version for CLI metadata.

project-map init [path]
project-map patch <file>
project-map validate [--fix] [path]
project-map reinit [path]
project-map context <query>

Typical workflow:

Run project-map init to generate maps for a project.
After editing a file, run project-map patch <file>.
Run project-map validate before relying on maps; use --fix only when you intend to repair artifacts.
Use project-map context "<query>" to retrieve a ranked context bundle.

init, patch, reinit, and validate --fix mutate .pi-map.md and/or .pi-map.index.md artifacts. context retrieves from existing artifacts.

Pi extension

The repository exposes pi-extension.ts as a Pi extension. Inside Pi it uses Pi's configured model and registers equivalent project_map_* tools. The extension can also inject project-map guidance according to promptInjectionMode.

LLM configuration

Standalone CLI use needs credentials for the selected provider. Do not commit keys.

openai (the default) reads OPENAI_API_KEY; its model can be set with OPENAI_MODEL or LLM_MODEL.
kimi reads KIMI_API_KEY (or KIMI_COM_API_KEY); its model can be set with KIMI_MODEL or LLM_MODEL.
CLI options --llm-provider=openai|kimi, --llm-model=<model>, and --llm-base-url=<url> override corresponding settings for a command.

Create an optional .pi-project-map.json in the project being mapped. It is merged with the defaults:

{
  "promptInjectionMode": "strong",
  "contextBudgetPercent": 15,
  "contextBudgetMaxTokens": 100000,
  "llmProvider": "openai",
  "llmModel": "gpt-4o-mini",
  "ignorePatterns": ["node_modules", ".git"],
  "tagCap": 8,
  "workflowHintCap": 5
}

promptInjectionMode accepts off, advisory, strong, or strict. Supplying ignorePatterns replaces the built-in ignore list rather than extending it. Additional supported settings include llmBaseUrl and reinitFullThresholdPercent.

Repository layout

src/ — CLI, map generation, validation, retrieval, configuration, and LLM clients
pi-extension.ts — Pi extension entry point
SKILL.md — Pi skill definition and operator guidance
usage-guide.md, design-doc.md, troubleshooting.md — additional usage and design documentation
package.json — package metadata, dependencies, and npm scripts

Operations

There is no server or deployment manifest. Operate the tool from the project being mapped and keep generated maps under the target project's normal review and version-control practices.

3.8 KiB Raw Permalink Blame History