A close reading of oh-my-pi (OMP) source: streaming internals, the rulebook and TTSR, slash and custom tools, memory, and the task hub/advisor design.
omp's runLoopBody uses a double while loop: the inner loop drives the core model call → tool execution rhythm; the outer loop, when the agent would stop, drains queued steering / follow-up / asides to decide whether to run another turn. This design solves delivery timing for 'user typing while model streams' and 'background tasks quietly queueing messages'.
omp uses StablePrefix to freeze system prompt + tool specs, AppendOnlyLog for append-only messages, and digest-based longestStablePrefix algorithm. When prune/shake/steering rewrite history, only the tail after the divergence point is resent. This maximizes Anthropic/DeepSeek prompt cache hit rate, fixing the old issue where every turn forced ~40k token re-prefill on llama.cpp (issue #3406).
omp doesn't have just one compaction: context-full uses LLM summarization with iterative windows and budget halving retries; snapcompact skips the LLM entirely, rendering history as dense PNG bitmaps for vision models to read — solving no-API-key, low-latency, vision-model-cheaper scenarios; branch summary summarizes the abandoned branch during `/tree` navigation so file ops aren't lost; shake mechanically replaces tool-result text and large fenced/XML blocks with placeholders — an emergency hatch when summary is too heavy and prune isn't enough. Four strategies, distinct failure modes, orchestrated by session maintenance or manual triggers.
omp's resolveApproval resolves in three layers: tool declaration → user override → mode tier. Undeclared or malformed approvals default to exec (fail-closed). Tool declares tier + optional policy/override/reason/policyKey; user overrides via tools.approval.<tool>; mode (always-ask/write/yolo) sets auto-allow tier ceiling. Iron laws: tool-side deny and user-side deny can never be crossed by mode; yolo ignores override: true but still honors policy: deny|allow|prompt. bash tokenizes approval: allow must cover whole line, deny/prompt match per segment. Same tool switches read/write via policyKey. checkpoint/rewind are paired sisters. subagent runs headless yolo; parent task is the only auth boundary.
omp's bash approval engine tokenizes commands into segments via a shared shell tokenizer (split on `;`, `&&`, `||`, `|`, `&`, newline, subshell). deny/prompt rules match glob against each segment individually — any hit triggers. allow rules require whole-line match AND no shell control syntax, preventing `cd x && rm -rf /` from slipping through. CRITICAL_BASH_PATTERNS hardcodes 45 dangerous command regexes (`rm -rf /`, `chmod -R 777 /`, `curl | bash`, `kill -9 1`, etc.) that fire before user patterns and cannot be disabled. Design tradeoff: allow is strict for safety, deny/prompt permissive for catch-all.
OMP replaces traditional line-number patches with hashline: 4-hex content hash + N* syntactic block locators eliminate whitespace drift. noop-loop-guard tracks per-session, per-canonical-path, per-input-hash consecutive no-ops; after 3 (NOOP_HARD_LIMIT) it throws a ToolError so the agent loop sees a tool failure — breaking the model's 182/205 retry loop from issue #2081 where soft hints were completely ignored.
OMP expresses routing, compat, thinking, quota, and pricing policies for 60+ providers entirely in KDL (taxonomy/classes/providers/runtime), compiles to rules.json, and resolves at runtime via a typed engine. Three reasons: layered ownership, compile-time validation, and mechanical priority resolution—all three would scatter, become unverifiable, or rely on human judgment if hardcoded in TS.
OMP encodes all provider-specific wire behaviors as KDL rules, compiled to JSON and applied by a pure cascade resolver — avoiding TS if-else sprawl, enabling static conflict detection at CI, and making behavior versionable.
omp stores sessions as append-only JSONL with id/parentId forming a tree; a mutable leaf pointer selects the active path. /tree uses TreeSelectorComponent for navigation; navigateTree() switches leaf with optional branch summary, handles checkpoint/rewind, supports Claude/Codex foreign session import. Fork duplicates the session file inheriting providerPromptCacheKey. Resume/switchSession uses captureState/rollback for atomic transitions. Three-layer storage (indexed/history/artifact) separates concerns.
OMP unifies hooks, skills, MCP, and marketplace into a cohesive extensibility layer: hooks merge into extension runner's event bus, skills use description for semantic triggering, MCP adopts a 250ms fast-start gate with deferred fallback, marketplace supports dual scopes with Claude Code catalog compatibility.
OMP builds a custom TUI engine (packages/tui + packages/coding-agent/src/tui) rather than using React/Ink. Core designs: differential rendering (repaint only changed lines via reference equality), explicit history contract, composer multi-modal input & keybindings system. This article analyzes architecture decisions and implementation details from source code.
OMP sinks performance-sensitive, correctness-critical, and determinism-requiring subsystems (grep, AST, PTY, isolation, file walking) into 6 independent Rust crates, then exposes a unified N-API surface via pi-natives; bindings are generated by napi-rs with gen-enums.ts patching runtime enums and explicit ESM exports.
omp collab uses a hub topology (host authoritative, guests never peer) with AES-256-GCM sealed JSON frames, 4-byte envelope, and snapshot-chunk sharding. Guest permissions are bound to a 16-byte write token in the link, verified by the host via timing-safe comparison.
OMP's metaharness isn't just a benchmark runner—it's experiment-grade infrastructure for hardware-isolated microVMs, unified auth gateway, and baseline-controlled experimental design.
14 posts in, back to the big picture: append-only context, compaction strategy split, three-layer approval, KDL rule tree, session tree/fork are the five most borrowable; snapcompact, metaharness self-built infra are over-engineered; looplane shouldn't self-build full provider catalog, full TUI, or full collab yet. Philosophy diff: omp = batteries-included in-process, looplane = minimal + external runtime.
OMP's Agent stream does more than print tokens: it separates agent, turn, message, and tool-execution events. Understand the contract to render text deltas, tool progress, and errors without mistaking a partial message for committed conversation state.