alex/pi-map
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: refresh README

Browse Source
This commit is contained in:
Alex
2026-07-27 15:24:01 +02:00
parent 3e7410b6bd
commit 97a4dd22f5
1 changed files with 49 additions and 125 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+49 -125
View File
@@ -1,140 +1,74 @@
# pi-project-map # pi-project-map
> Pi skill and CLI for hierarchical project analysis. 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.
`pi-project-map` generates and maintains paired, machine-readable analysis artifacts throughout a codebase so agents can navigate quickly, orient themselves, and then verify details from source. ## Status and limitations
## What it is - 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.
For every non-ignored directory, the tool produces two files: ## Install and develop
| File | Purpose | Install the published CLI globally:
|------|---------|
| `.pi-map.index.md` | Routing-first index for deciding what to open next. |
| `.pi-map.md` | Orientation-first rich map for understanding a directory. |
Together they form a **paired artifact model**:
- indexes are small and routing-optimized
- maps are denser and architecture-optimized
- source remains the final authority
`pi-project-map` runs as both:
- a **CLI** (`project-map`)
- a **Pi extension** (`pi-extension.ts`) that registers tools and optional runtime prompt injection
## Quick start
Install:
```bash ```bash
npm install -g pi-project-map npm install -g pi-project-map
``` ```
Generate paired artifacts in a repo: For local development, install dependencies and build from this repository:
```bash ```bash
cd my-project npm install
project-map init npm run build
``` ```
For standalone CLI usage, provide an LLM provider/API key. For example: Available development checks:
```bash ```bash
export OPENAI_API_KEY=... npm run test
project-map init npm run lint
npm run typecheck
npm run dev
``` ```
Inside Pi, the extension uses Pi's configured model automatically. `npm run dev` runs TypeScript in watch mode. The project declares no deployment command.
## Command overview ## Use the CLI
| CLI command | Pi tool | Purpose | Run the installed `project-map` command from the project to map. Use `--help` or `--version` for CLI metadata.
|-------------|---------|---------|
| `project-map init [path]` | `project_map_init` | Generate paired artifacts for the whole project or a subdirectory. | ```bash
| `project-map patch <file>` | `project_map_patch` | Regenerate artifacts for the directory containing the changed file and refresh ancestors appropriately. | project-map init [path]
| `project-map validate [--fix]` | `project_map_validate` | Check paired artifacts for staleness or inconsistency. | project-map patch <file>
| `project-map reinit [path]` | `project_map_reinit` | Force full regeneration of all artifacts. | project-map validate [--fix] [path]
| `project-map context <query>` | `project_map_context` | Return a ranked context bundle for a natural-language query. | project-map reinit [path]
project-map context <query>
```
Typical workflow: Typical workflow:
1. `project-map init` on first use 1. Run `project-map init` to generate maps for a project.
2. after editing source, `project-map patch <changed-file>` 2. After editing a file, run `project-map patch <file>`.
3. before broad architectural decisions, `project-map validate` 3. Run `project-map validate` before relying on maps; use `--fix` only when you intend to repair artifacts.
4. for targeted exploration, `project-map context "<query>"` 4. Use `project-map context "<query>"` to retrieve a ranked context bundle.
## Operating model `init`, `patch`, `reinit`, and `validate --fix` mutate `.pi-map.md` and/or `.pi-map.index.md` artifacts. `context` retrieves from existing artifacts.
Follow a three-tier model when consuming project maps: ### Pi extension
1. **Tier 0 — Protocol and root index** 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`.
Start with the root `Project Map Protocol` and root `.pi-map.index.md`.
2. **Tier 1 — Indexes and maps**
Use indexes to route, then open the strongest-match `.pi-map.md` files for orientation.
3. **Tier 2 — Source and tests**
Read actual source, config, tests, and docs before editing or making exact runtime claims.
The trust boundary is always: ## LLM configuration
> **index routes, map orients, source decides.** Standalone CLI use needs credentials for the selected provider. Do not commit keys.
## Prompt injection policy - `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.
The Pi extension can automatically inject lightweight project-map guidance into the agent context. Behavior is controlled by `promptInjectionMode` in `.pi-project-map.json`. Create an optional `.pi-project-map.json` in the project being mapped. It is merged with the defaults:
### Before init
No synthetic map content is injected. The agent sees only a visible startup hint telling it to run `project_map_init`.
### After init
The root pair is guaranteed to load first:
- root `.pi-map.index.md`
- root `.pi-map.md`
Additional directory pairs are expanded only while the configured context budget allows.
### Mode ladder
| Mode | Behavior |
|------|----------|
| `off` | No automatic injection. |
| `advisory` | Visible hints/reminders only; maps are read manually. |
| `strong` | Root pair injection, budgeted expansion, reinjection on relevant turns. |
| `strict` | Same as `strong`, plus a visible guard for sensitive turns when the protocol path is missing. |
The **protocol path** is present when outgoing context contains:
- the canonical root-pair marker/block
- the trust-boundary instruction
In `strict` mode, a sensitive action can be bypassed explicitly with:
```text
[PI_MAP_BYPASS: <brief justification>]
```
### Context budget
Default automatic-injection budget is the smaller of:
- **15%** of the active model context window
- **100,000 tokens** absolute cap
If the runtime cannot discover the model context window, it falls back to the absolute cap.
## Retrieval is separate
`project-map context <query>` and `project_map_context` are **separate, on-demand retrieval** paths. They do **not** replace automatic prompt injection.
Retrieval is deterministic and metadata-driven:
1. score every directory's paired map/index metadata against the query
2. keep the top matches (default: 3)
3. return a compact markdown bundle with indexes, maps, likely files, and symbols
Use retrieval for targeted navigation when you already have a specific question.
## Configuration overview
Create `.pi-project-map.json` in the project root:
```json ```json
{ {
@@ -149,26 +83,16 @@ Create `.pi-project-map.json` in the project root:
} }
``` ```
Providing `ignorePatterns` replaces the built-in default list, so include any defaults you want to keep. `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`.
Key knobs: ## Repository layout
- `promptInjectionMode` — `off`, `advisory`, `strong`, `strict`
- `contextBudgetPercent` — relative share of model context used for automatic injection
- `contextBudgetMaxTokens` — hard absolute cap on automatic injection
- `llmProvider` / `llmModel` / `llmBaseUrl` — standalone CLI provider settings
- `ignorePatterns` — directories/files to skip
- `tagCap` / `workflowHintCap` — routing metadata limits
## Documentation map - `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
- [`SKILL.md`](SKILL.md) — skill definition and agent/operator instructions ## Operations
- [`usage-guide.md`](usage-guide.md) — practical workflows and examples
- [`design-doc.md`](design-doc.md) — architecture and implementation details
- [`troubleshooting.md`](troubleshooting.md) — common issues and recovery steps
## Known limitations 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.
- token budgeting is best-effort, not tokenizer-exact
- relevant-turn detection uses explicit event types plus heuristics
- provider payload fallback depends on runtime serialization shapes
- retrieval routes and orients; it never replaces source verification