Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
189 lines (138 loc) · 9.75 KB

ARCHITECTURE.md

File metadata and controls

189 lines (138 loc) · 9.75 KB
Raw

ARCHITECTURE.md — every component, explained

The full anatomy of the stack: what each piece does, where it installs, and why it's here. Install targets:

  • pi/* → ~/.pi/agent/
  • config-skills/* → ~/.config/agents/skills/
  • orchestration/* → ~/pi-orchestration/

0. Current v2.1 personal layer

The portable stack in this repo is the base. The current personal Pi architecture adds the v2.1 quality spine on top: requirement ledgers, .pi/quality/* proof artifacts, /proof/proof_check, package-layer routing, worker timeout metadata, startup skill-conflict filters, Overstory helper aliases, codebase-memory pruning hygiene, and an Obsidian receipt rule for big completed tasks.

Read the current layer here: docs/PI-ARCHITECTURE-V2.1.md.

source-truth intake → routed execution → package organs → quality ledgers → proof gate → obsidian receipt

Key rule: package tools and subagents can assist, but they do not prove completion. Completion needs requirements evidence, quality-ledger evidence, and proof-gate evidence.

1. Extensions → ~/.pi/agent/extensions/

Extension What it does
editor/ Custom bordered TUI editor; status labels for context %, cost, model, git branch; enlarged prompt bar
command-palette/ Ctrl+Shift+P fuzzy command overlay
tools/ The 25-tool suite — replaces the built-ins and adds sub-agents, GitHub, and web tools (see §2)
mentions.ts @oracle / @finder / @codereview / @task — forces the model to route to a specific sub-agent
system-prompt.ts Injects the Amp-style system prompt with runtime template variables
tool-harness.ts Env-gated tool filtering for sandboxing sub-agents
todos.ts File-based todo manager with a TUI (/todos)
btw.ts /btw — async side conversations while the agent works
notify.ts Desktop notifications when the agent finishes (OSC 777: Ghostty/iTerm2/WezTerm)
session-name.ts Auto-generates a short session title from the first message
session-breakdown.ts /session-breakdown — sessions/day, cost, tokens, model split, calendar heatmap
md-export.ts Export a session's JSONL transcript to readable markdown
local-model.ts /local start|stop|status — manage a local llama-server, inject anti-gaslighting rules
cbmem.ts Wraps codebase-memory-mcp → cbm_* tools: a persistent code knowledge graph (architecture, symbol search, call-path tracing, change blast-radius)
crof.ts Registers the CrofAI budget-OSS provider (only if CROF_API_KEY is set)
import-opencode.ts (+ import-opencode/) Import opencode sessions into pi
kimi-code-token.mjs OAuth token helper for the Kimi Code provider
pi-tool-display/ Config for the pi-tool-display package (thinking labels, native user box)
eko24ive-pi-ask.json Config for the pi-ask structured ask_user tool
lucifer-router.ts Optional intake router — an LLM classifier that injects a routing directive ([LUCIFER ROUTER …]) on substantive prompts. Silent no-op without a classifier key. /route on|off|status
lucifer-conserve.ts Weekly-limit guard — force-shifts solo work to Codex when the Claude budget runs hot. /conserve on|off|auto|status|threshold <n>
lucifer-usage.ts 📊 footer — live Claude + Codex subscription usage meters

The three lucifer-* extensions implement the dual-subscription doctrine. They work as-is with Claude Max + Codex Max; the router additionally needs a classifier key to activate.

2. The 25-tool suite → ~/.pi/agent/extensions/tools/

Hardened replacements for pi built-ins:

  • bash — mutex locking, git-trailer injection, permission rules, ANSI sanitization, cmd/command dual-param
  • read — image support (jpg/png/gif/webp), line numbers, .env blocking, read_range/offset+limit dual-param
  • edit / write — mutex locking, redaction/placeholder guard, change tracking, 3-tier matching
  • grep — per-file limits, 200-char truncation, context lines
  • find (glob) — rg --files, mtime sort
  • ls, format-file, undo-edit, skill — enhanced built-ins

Sub-agents (route through the parent's provider — provider-aware auth):

  • finder (Haiku) — concept-based parallel code search
  • oracle (Sonnet) — architecture review / complex planning
  • code_review (Sonnet) — two-phase structured diff review
  • Task — full sub-agent for parallel independent work
  • librarian (Haiku) — cross-repo GitHub exploration
  • read_web_page, read_session, search_sessions

GitHub tools (via the GitHub API): read_github, search_github, list_directory_github, glob_github, list_repositories, commit_search, diff.

Web: web_search. Note: the tool suite's own web_search is intentionally disabled in tools/index.ts to avoid a fatal conflict with the pi-web-access package, which owns web_search on modern pi. This is why the legacy pi-core "resource-loader" patch is not needed (see §7).

3. Agent prompts → ~/.pi/agent/agents/

agent.amp.finder.md, agent.amp.oracle.md, agent.amp.librarian.md, prompt.amp.code-review-system.md, prompt.amp.code-review-report.md, prompt.amp.handoff-extraction.md, prompt.amp.read-web-page.md, prompt.amp.look-at.md, prompt.amp.system.md, prompt.harness-docs.pi.md.

4. Skills → ~/.config/agents/skills/ (17)

git · review · spawn · tmux · dig · document · write · remember · coordinate · rounds · spar · report · shepherd · nexus-fix · amp-voice · chrome-cdp · codebase-memory. Load one with the skill tool when a task matches its description.

5. Providers & models → pi/settings.json + pi/models.json

Provider Auth Notes
anthropic (Claude Max) /login anthropic (OAuth) primary; Opus 4.6/4.7/4.8 with a 1M-context override
openai-codex (Codex Max) /login openai-codex (OAuth) primary for backend/systems; built-in provider (type: native)
deepseek $DEEPSEEK_API_KEY V4 Pro / Flash, 1M context — optional
nvidia $NVIDIA_API_KEY GLM-5.1 / DeepSeek via NIM — optional
kimi-code OAuth via kimi-code-token.mjs Kimi Code subscription — optional
local-llama http://localhost:8080 Qwen / Gemma via llama-server (/local) — optional

enabledModels lists only providers that resolve out-of-box (Claude + Codex + defined optional providers) so a fresh launch shows no "no models match" warnings. Add more as you get keys.

Defaults: defaultProvider=anthropic, defaultModel=claude-opus-4-8, defaultThinkingLevel=xhigh, theme=gruvbox, compaction=on, steeringMode/followUpMode=all, quietStartup=true.

6. pi packages (installed by install.sh / auto on launch)

pi-web-access (web search + fetch + librarian) · pi-context · pi-token-burden · @benvargas/pi-claude-code-use (Claude Max OAuth) · @marckrenn/pi-sub-bar (usage widget) · pi-autoresearch · pi-tool-display · @tomooshi/condensed-milk-pi (bash-output compression) · pi-gpt-config (Codex-parity personality/verbosity) · pi-ask (structured ask_user) · pi-codex-goal.

7. Optional package patches → packages/ (NOT applied by default)

Local source-level customizations for a few packages. They are version-fragile (they overwrite files inside installed packages) so install.sh skips them unless you pass --with-patches. scripts/apply-patches.sh backs up every target and applies only:

  • condensed-milk-patches/ → @tomooshi/condensed-milk-pi
  • gpt-config-patches/ → pi-gpt-config

Shipped for reference but intentionally never applied:

  • pi-core-patches/ — legacy pi dist/*.js overwrites (session pinning + a web_search conflict fix that modern pi no longer needs). Overwriting a fresh pi's compiled files is pure downside.
  • claude-bridge-patches/ — for pi-claude-bridge, which this stack does not use (it uses @benvargas/pi-claude-code-use for Claude Max instead).
  • pi-ai-patches/, codebase-memory/ — reference material / binary installer helper.

8. Orchestration (advanced tier) → ~/pi-orchestration/

An Overstory + Pi multi-agent swarm framework. Read orchestration/RUNBOOK.md first.

  • bin/codex-run.sh → codex-run "<task>" — one-shot headless Codex Max for solo sessions.
  • bin/lucifer-codex.sh → lucifer-codex — interactive session on Codex Max.
  • bin/ov-env.sh — puts the swarm into isolated-runtime mode (PI_CODING_AGENT_DIR, unsets metered keys so it bills subscriptions).
  • bin/watch.sh → lucifer-watch — the swarm dashboard.
  • bin/ov-dual-provider-init.sh, ov-coordinator.sh, ov-dashboard.sh, overstory-cmux.sh.
  • config.template.yaml, MODEL-STACK.md, CLARITY-DOCTRINE.md, global-extensions/.

The swarm itself needs the Overstory CLI (ov) installed separately — see the RUNBOOK. The model split: builder→Claude (UI), backend-builder→Codex (systems), and every diff reviewed by the opposite family (reviewer→Codex, codex-reviewer→Claude).

9. Global doctrine → ~/.pi/agent/AGENTS.md

Injected into every session. Encodes: the single-workspace law, the dual-subscription law, clarity-first intake protocol, graph-first code discovery (codebase-memory), night-run autonomy (no self-imposed token caps), and the image-MIME safety law. Edit the workspace root and GitHub account to match yourself.

10. Ghostty terminal (optional) → ghostty/

10 dark themes, 11 developer fonts, live-preview switchers (gt/gf/gc/gg). Install with cd ghostty && ./install.sh (macOS + Ghostty only). Independent of the pi setup.