Epic: Evaluate Pi (badlogic/pi-mono) architectural patterns for terraphim-ai

[AlexMikhalev]

Overview

Evaluate architectural patterns from Pi coding agent (badlogic/pi-mono, 24.5k stars, MIT) for adoption in terraphim-ai. Pi is a layered, extensible TypeScript coding agent toolkit with patterns that address known gaps in our current architecture.

Knowledge base article: cto-executive-system/knowledge/external/context-engineering/pi-coding-agent-architecture.md
Comparison article: cto-executive-system/knowledge/claude-code-architecture-deep-dive.md

Evaluation Items

• Tree-structured session storage for terraphim_persistence Evaluate: Tree-structured session storage (Pi pattern) for terraphim_persistence #683
• Layered crate architecture: extract standalone LLM interaction crate Evaluate: Extract standalone LLM interaction crate (Pi layered architecture pattern) #684
• Cross-provider context serialisation for ADF multi-model routing Evaluate: Cross-provider context serialisation for ADF multi-model routing #685
• Typed beforeToolCall/afterToolCall hook pattern for terraphim-skills Evaluate: Typed tool hooks (beforeToolCall/afterToolCall) for terraphim-skills #686
• Steering and follow-up message queues for ADF agent interaction Evaluate: Steering and follow-up message queues for ADF agent interaction #687

Context

Pi takes a fundamentally different approach from Claude Code: minimal core (4 built-in tools) with a TypeScript extension system that can replace any component. While we are not adopting Pi itself (our stack is Rust + Claude Code), several of its architectural patterns address real gaps:

1. Session branching: Our current linear JSONL sessions lose history on compaction. Pi's tree structure (id/parentId) preserves all branches in a single file.
2. Layered architecture: Pi cleanly separates LLM API, agent loop, and UI into independent packages. Our LLM interaction code is scattered across terraphim_orchestrator, terraphim_multi_agent, and ad-hoc scripts.
3. Cross-provider handoffs: Pi serialises context for mid-session model switching. ADF routes different agents to different models but cannot hand off context between them.
4. Tool hooks: Pi's typed beforeToolCall/afterToolCall at the agent-core level is simpler than Claude Code's JSON-based shell hooks. Pattern applicable to terraphim-skills.
5. Message queues: Pi's steering (interrupt) vs follow-up (after completion) queues are missing from ADF agent interaction.

Architecture Decision

Each evaluation item is independent. Successful evaluations may lead to implementation issues. Items that do not justify adoption should be closed with rationale.

What NOT to Adopt

• Pi itself (TypeScript, not Rust)
• Anti-MCP philosophy (MCP is integral to our workflow)
• Anti-sub-agents philosophy (agent teams are core to our approach)
• TypeScript extension system (our skills are Markdown + shell)