pi-next-ncb 🚀

The ultimate next-gen enhancement suite for pi coding agent.

Transform pi into a full-featured agent IDE with real-time agent orchestration visibility, intelligent compaction, streaming tool output, and deep session introspection.

pi install npm:@salahnecibi/pi-next-ncb

Restart pi → /pi-next-status → you're in the next generation.

---

What You Get

Pri	Component	What It Does	How To Access
🔴 P0	Orchestration Dashboard	Real-time TUI showing every subagent, its status, tool calls, and duration — live	Auto-widget + /dashboard
🔴 P0	Semantic Compaction 2.0	Structured compaction that preserves decisions, file changes, errors, and action items instead of vague summaries	Auto on compaction + /compact-status
🟡 P1	Streaming Tool Protocol	stream_bash — runs commands with output streaming to both the LLM and TUI in real-time	Tool: stream_bash
🟡 P1	Inspector Pane	Context token breakdown, tool call timeline with durations, cost estimates — visible instantly	Ctrl+I or /inspector
🟢 P2	Live Diff Viewer	Snapshots files before edits, computes unified diffs after — see exactly what changed	Auto + /diff
🟢 P2	pi Package Search	Search npm for pi packages without leaving your terminal	/pi-search <query> + CLI

---

Commands Reference

General

/pi-next-status              — Show all components with load state ✓ / ○
/pi-next-toggle <name>       — Enable/disable any component

Dashboard & Inspector

/dashboard                   — Open agent orchestration dashboard
Ctrl+I  or  /inspector       — Toggle context/tool/cost inspector pane

Compaction

/compact-status              — Show compaction statistics & history
/compact-pin <entry-id>      — Pin a message so compaction never loses it

Diffs

/diff [file]                 — Show recent unified diff from tool execution

Package Discovery

/pi-search <query>           — Search npm for pi packages
/pi-info <package>            — Show detailed package info
/pi-install <source>         — Quick install shorthand

---

Deep Dive

🎛️ Orchestration Dashboard (P0)

When you launch subagents via pi-subagents, a live TUI widget appears above the editor:

╭─ pi-next Orchestration Dashboard ─────────────────────────╮
│ ● Active Agents:                                           │
│   ▶ reviewer             12s      3 tools [tool: read]     │
│   ▶ worker               45s      8 tools                   │
│ ──────────────────────────────────────────────────          │
│   ✓ scout               2 tools, 1 turn                    │
╰────────────────────────────────────────────────────────────╯

No config needed. Hooks into tool_call, tool_execution_start/end, and turn_start events automatically. Shows:

• Status icons: ● queued, ▶ running, ⏸ paused, ✓ done, ✗ failed
• Elapsed time per agent
• Tool call count and current tool name

🧠 Semantic Compaction 2.0 (P0)

When pi auto-compacts or you run /compact, this intercepts session_before_compact and builds a structured summary:

Extracted	From	Example
Decisions	Pattern matching ("we decided X", "approved Y")	• Use PostgreSQL for the new schema
Files	edit/write tool call tracking	write: src/db/migrations/001_init.sql
Errors	Error/exception pattern detection	⚠ TypeError: Cannot read property 'x' of undefined
Action Items	Todo/follow-up patterns	☐ Update the API docs for the new endpoint

Use /compact-pin <entry-id> to mark entries as permanent — they survive all future compactions.

🌊 Streaming Tool Protocol (P1)

A new stream_bash tool that wraps bash execution with:

• Real-time streaming — output is piped to both the LLM and the TUI simultaneously
• LLM mid-execution awareness — the model sees progress updates every ~3 chunks
• Abort signal support — press Escape to cancel, and the partial output is preserved
• Smart truncation — 50KB limit keeps tail output, drops middle

Use it instead of bash for: npm test, long builds, deployment scripts, multi-minute installations.

🔍 Inspector Pane (P1)

Press Ctrl+I or run /inspector for an instant breakdown:

╭─ pi-next Inspector ───────────────────────────────────────╮
│ Model: deepseek/deepseek-v4-flash                          │
│ Context: 45,231 tokens                                     │
│   system: 8,120 tok                                        │
│   tools: 2,340 tok                                         │
│ ──────────────────────────────────────────────────          │
│ Recent tools (23 total):                                    │
│   ✓ read  path: src/index.ts                                │
│   ✓ bash  npm test -- --watch                                │ 12s
│   ✗ write path: dist/output.json                              │
╰────────────────────────────────────────────────────────────╯

📝 Live Diff Viewer (P2)

Every edit and write tool call snapshots the target file before modification. After execution, a unified diff is computed showing:

--- a/src/app.ts
+++ b/src/app.ts
@@ -10,5 +10,8 @@
   const port = 3000;
+  const db = await connect();
   app.listen(port);

Key changed lines are shown in notifications — /diff for the full view.

🔎 pi Package Search (P2)

Search npm for pi packages without leaving your editor:

/pi-search web                  →  Finds web-related pi packages
/pi-search pdf --limit 5       →  Top 5 PDF-processing packages  
/pi-search agent --sort downloads  →  Most popular agent packages
/pi-info @dotdotgod/pi          →  Detailed package info

Also works as a standalone terminal command:

pi-search web
pi-search info @salahnecibi/pi-next-ncb

---

Requirements

Dependency	Version
pi-coding-agent	>= 0.80.0
Node.js	>= 18
Terminal	Any ANSI-capable (most modern terminals)

---

Architecture

pi-next-ncb/
├── package.json               ← npm + pi package manifest
├── README.md                  ← This file
├── LICENSE                    ← MIT
├── bin/
│   └── pi-search.mjs          ← Standalone CLI for package search
├── src/
│   ├── index.ts               ← Main entry: loads & coordinates all components
│   ├── orchestration-dashboard.ts  ← P0: TUI agent dashboard
│   ├── semantic-compaction.ts      ← P0: Structured compaction hooks
│   ├── streaming-tools.ts          ← P1: stream_bash tool
│   ├── inspector-pane.ts           ← P1: Context/tool/cost inspector
│   ├── diff-viewer.ts              ← P2: Live diff on tool execution
│   └── pi-search.ts                ← P2: npm package discovery commands
└── skills/
    └── pi-next/
        └── SKILL.md            ← Skill: teaches LLM how to use pi-next features

---

Development

git clone https://github.com/salahnecibi/pi-next-ncb.git
cd pi-next-ncb
npm install

# Test locally
pi -e ./src/index.ts

# Publish
npm version patch
npm publish

---

License

MIT — Use it, fork it, ship it.