Architecture

Architecture

Overview

The extension is a single TypeScript module (extensions/agentic-harness/index.ts) that integrates with pi via the Extension API.

Entry Point

export default function (pi: ExtensionAPI) {
  // Tool registration
  // Event handlers
  // Commands
  // Session hooks
}

Event Hooks

resources_discover

Registers skills/ directory so pi discovers bundled skill rulesets.

before_agent_start

Injects into the system prompt:

• Phase guidance — context-specific instructions for /clarify, /plan, /ultraplan
• Delegation guards — current depth, cycle prevention status, ancestor stack
• Available subagents — dynamically discovered agent list

context

Microcompaction — truncates old tool results to manage context window usage.

session_before_compact

Phase-aware custom summarization:

• Preserves workflow state (phase, active goal document) across compaction
• Skips for idle phase with no active goal (lets pi's default handle it)
• Uses the current LLM model for summarization

session_compact

Restores workflow phase and goal document from compaction details.

tool_result

Tracks goal document creation (files under docs/engineering-discipline/).

tool_execution_start / tool_execution_end

Tracks active tool executions for the footer display.

session_start

• Restores saved workflow state
• Sets up custom ROACH PI ASCII banner header
• Sets up branded footer (directory, branch, model, context bar, cache hit rate, active tools)

message_end

Accumulates cache hit rate statistics for the footer display.

Workflow State Machine

idle → clarifying → planning → idle
idle → clarifying → ultraplanning → idle
idle → planning → idle
idle → ultraplanning → idle

State is persisted to ~/.pi/extension-state.json and survives compaction.

TUI Customization

Header

ROACH PI ASCII art banner with random tips.

Footer

Displays: working directory │ git branch │ model name │ context usage bar │ cache hit rate │ active tools

Concurrency Model

Mode	Max Tasks	Max Concurrent
Parallel	8	4
Chain	unlimited	1 (sequential)
Single	1	1

All modes include:

• Cycle detection via ancestor stack comparison
• Depth limit (max 3)
• Heartbeat progress updates (1s interval)