pi-project-map

Pi skill and CLI for hierarchical project analysis.

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.

What it is

For every non-ignored directory, the tool produces two files:

File	Purpose
.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:

npm install -g pi-project-map

Generate paired artifacts in a repo:

cd my-project
project-map init

For standalone CLI usage, provide an LLM provider/API key. For example:

export OPENAI_API_KEY=...
project-map init

Inside Pi, the extension uses Pi's configured model automatically.

Command overview

CLI command	Pi tool	Purpose
project-map init [path]	project_map_init	Generate paired artifacts for the whole project or a subdirectory.
project-map patch <file>	project_map_patch	Regenerate artifacts for the directory containing the changed file and refresh ancestors appropriately.
project-map validate [--fix]	project_map_validate	Check paired artifacts for staleness or inconsistency.
project-map reinit [path]	project_map_reinit	Force full regeneration of all artifacts.
project-map context <query>	project_map_context	Return a ranked context bundle for a natural-language query.

Typical workflow:

1. project-map init on first use
2. after editing source, project-map patch <changed-file>
3. before broad architectural decisions, project-map validate
4. for targeted exploration, project-map context "<query>"

Operating model

Follow a three-tier model when consuming project maps:

1. Tier 0 — Protocol and root index
   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:

index routes, map orients, source decides.

Prompt injection policy

The Pi extension can automatically inject lightweight project-map guidance into the agent context. Behavior is controlled by promptInjectionMode in .pi-project-map.json.

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:

[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:

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

Providing ignorePatterns replaces the built-in default list, so include any defaults you want to keep.

Key knobs:

• 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

• SKILL.md — skill definition and agent/operator instructions
• usage-guide.md — practical workflows and examples
• design-doc.md — architecture and implementation details
• troubleshooting.md — common issues and recovery steps

Known limitations

• 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