# π pi-context-optimizer
**Plan β Review β Execute β Walkthrough** β a structured, gate-driven workflow loop for the [pi coding agent](https://github.com/earendil-works/pi).
[](https://www.npmjs.com/package/pi-context-optimizer)
[](LICENSE)
[](package.json)
[](https://github.com/earendil-works/pi)
---
## β¨ What is it?
**pi-context-optimizer** brings a structured **human-in-the-loop** workflow to the `pi` coding agent. Instead of letting the agent code freely from the start, this extension enforces a disciplined five-phase cycle to optimize context, prevent runaway file writes, and align on goals before execution:
```
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β 5-PHASE LOOP β
β β
β INERT ββ/planβββΆ RESEARCHING ββwrite_planβββΆ PLAN_DRAFTING β
β β β
β βΌ β
β EXECUTING ββββ/approveβββββββββββββββ REVIEW_PENDING β
β β β
β βββ all done ββwrite_walkthroughβββΆ INERT β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
```
During **RESEARCHING** / **PLAN_DRAFTING** / **REVIEW_PENDING**, the agent is **blocked** from editing code β it can only read, explore, and reason. Once a plan is written and **you approve it**, the gates open and the agent executes step-by-step, reporting progress after each step.
Perfect for:
- π― **Complex, multi-step refactors** where you want a plan before any code changes
- π§ͺ **Code reviews with an AI** β see the plan, approve or reject, then watch it execute
- π **Knowledge capture** β the walkthrough artifact persists what changed and why
- π€ **Collaborative sessions** β `/grill` mode to interview the agent before it drafts
---
## π Prerequisites
To use `pi-context-optimizer`, ensure you have the following:
1. **Node.js**: `node >= 18`
2. **Pi Coding Agent**: `pi >= 0.78.0` installed globally or locally.
3. **Sub-agent Infrastructure**:
- **`kmmuntasir/pi-nested-subagents:src`** (or configured sub-agent tools on the agent system) for executing nested agent sessions.
- **`tsedr-runtime`** (`T-SEDR`) configured globally or locally to hook into agent sessions.
4. **VS Code Extension** (Optional): **`tufaan42.pi-context-optimizer`** for human-in-the-loop plan reviews and approval controls directly in the IDE.
5. **Peer Dependencies**:
- `@earendil-works/pi-coding-agent >= 0.78.0`
- `@earendil-works/pi-tui >= 0.78.0`
- `typebox >= 1.1.0`
---
## π Step-by-Step Integration Guide
### Step 1: Install the Extension
Install `pi-context-optimizer` in your project or globally alongside `pi`:
```bash
npm install pi-context-optimizer
```
### Step 2: Configure `pi` to Load the Extension
Add the extension name to your configuration. You can do this at the project level or globally.
#### Option A: Project-Level Configuration (Recommended)
Create a `.pirc.json` file in the root of your workspace:
```json
{
"extensions": [
"pi-context-optimizer"
]
}
```
#### Option B: Global Configuration
Add the extension to `~/.pi/config.json`:
```json
{
"extensions": [
"pi-context-optimizer"
]
}
```
### Step 3: Run the `pi` Agent
Launch `pi` in your workspace. You should see an initialization message confirming the optimizer is loaded:
```text
[CONTEXT OPTIMIZER] pi-context-optimizer is loaded. Use /plan to start a structured planβreviewβexecuteβwalkthrough workflow, or just start coding normally.
```
---
## π§βπ» Using the Workflow
### Interactive Slash Commands
The extension registers the following commands to control the workflow:
| Command | Phase | Description |
|---------|-------|-------------|
| `/plan` | `INERT` β `RESEARCHING` | Enter read-only research mode to draft a plan. |
| `/grill` | `RESEARCHING` / `PLAN_DRAFTING` | Open an interactive grill/interview session to align details. |
| `/done` | `PLAN_DRAFTING` | Exit grill mode and indicate readiness to finalize the plan. |
| `/approve` | `REVIEW_PENDING` β `EXECUTING` | Approve the plan, opening write permissions. |
| `/reject` | `REVIEW_PENDING` β `PLAN_DRAFTING` | Reject the plan and provide feedback for a revision. |
### CLI Flag
You can also start a session auto-booted in planning mode:
```bash
pi --ag-plan "Refactor the database layer to use Drizzle ORM"
```
---
## π Artifact Structure
During the session, `pi-context-optimizer` creates structured artifacts under `.pi/context-optimizer//`:
- **`plan.md`**: The human-reviewable implementation plan.
- **`tasks.md`**: A live checklist representing step progress.
- **`walkthrough.md`**: A summary of changes and verification results.
- **`status.json`**: Machine-readable state representing phase/approval.
- **`knowledge/`**: Directory containing cross-session knowledge items.
---
## π Host Integration (Bridge)
`pi-context-optimizer` is **host-agnostic**: any tool built on `pi` β the
original `pithings/pi-vscode` extension, **PiLot Studio**, a JetBrains plugin,
or a custom web UI β can integrate the planβreviewβexecuteβwalkthrough flow
**without HTTP, tokens, or in-process embedding.**
The primary contract is the **filesystem artifact protocol**: the plan/tasks/
walkthrough/status files are always written to disk, and a stable
`active.json` pointer lets a host discover the active session by watching one
file. The approval gate is file-based β approve/reject by writing `status.json`,
which the extension reconciles via `fs.watch`.
The original pi-vscode HTTP bridge (`openFile` / `setPlanStatus`) still works
but is now a **cosmetic, auto-detected enhancement**, not a dependency. A host
that provides nothing still gets a fully functional workflow.
π **Full contract, schemas, and a minimal integration recipe:** see
[`BRIDGE.md`](./BRIDGE.md).
---
## π§ Context Optimization & Parallel Sub-agents
### Context Window Optimization
To prevent context window bloat and keep sub-agents running fast and cost-effectively, `pi-context-optimizer` implements strict context isolation:
- **Strict Context Isolation**: Sub-agents are spawned with `inherit_context: false` so they do not inherit the massive main session chat history.
- **Targeted Context Propagation**: The dispatcher constructs a minimal, highly-focused prompt for each sub-agent containing only:
- The high-level plan summary.
- The specific step description to execute.
- The precise outputs of its direct and transitive prerequisite steps (predecessors in the dependency DAG).
### Parallel Sub-agent Spawning
When a plan is approved, the engine compiles the steps into a Directed Acyclic Graph (DAG) and executes independent branches concurrently:
- **DAG Resolution**: Steps that have all prerequisites completed are marked as ready.
- **Concurrent Dispatching**: Ready steps are dispatched in parallel using the `Agent` tool, adhering to a defined concurrency limit (`concurrencyLimit`).
### Framework & Registry Integration
`pi-context-optimizer` is designed to run in environments utilizing:
- **kmmuntasir/pi-nested-subagents**: The core execution engine relies on the nested sub-agent spawning API (`Agent` tool) exposed by the `kmmuntasir/pi-nested-subagents:src` package to spawn child tasks.
- **T-SEDR (`tsedr-runtime`)**: Fully integrates with `tsedr-runtime`. When a sub-agent session starts, T-SEDR's global `before_agent_start` hook executes within the sub-agent session to provide runtime validation and environment setup.
---
## π§ API Reference
### Programmatic Integration
If you are developing a custom extension wrapper for `pi`, you can import and register `pi-context-optimizer` programmatically:
```typescript
import contextOptimizer from "pi-context-optimizer";
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
export default function myExtension(pi: ExtensionAPI): void {
// Register the optimizer extension
contextOptimizer(pi);
}
```
---
## π§ͺ Development & Testing
If you are contributing to this extension:
1. Clone the repository:
```bash
git clone https://github.com/tufaan42/pi-context-optimizer.git
cd pi-context-optimizer
```
2. Install dependencies:
```bash
npm install
```
3. Run the development/build pipeline:
```bash
npm run build # Compile TypeScript (dist/)
npm run typecheck # Run type checking without emit
npm test # Execute unit and E2E tests
```
---
## π License
[MIT](LICENSE) Β© 2026 Tufaan