pigo — Runtime Architecture

CLI AI coding agent · request path, external deps, trust boundaries

pigo — Runtime Architecture CLI AI coding agent · request path, external deps, trust boundaries pigo process · local, trusted External network · untrusted User / Terminal · REPL · -p headless · Architecture component User / Terminal REPL · -p headless Session Store · JSONL · resume · pigo process · local, trusted Session Store JSONL · resume Context Compaction · auto-summary · pigo process · local, trusted Context Compaction auto-summary CLI & Run Assembly · cmd/pigo · pigo process · local, trusted CLI & Run Assembly cmd/pigo Agent Loop · runtime · two-layer · pigo process · local, trusted Agent Loop runtime · two-layer Provider Layer · transport · SSE · pigo process · local, trusted Provider Layer transport · SSE Sub-agent Orchestrator · goroutine · process · pigo process · local, trusted Sub-agent Orchestrator goroutine · process Tool Executor · registry · read/edit/bash · pigo process · local, trusted Tool Executor registry · read/edit/bash Trust Gate · per-dir permission · pigo process · local, trusted Trust Gate per-dir permission LLM Gateway · OpenRouter · Anthropic · Ollama · External network · untrusted LLM Gateway OpenRouter · Anthropic · Ollama Web · webfetch targets · External network · untrusted Web webfetch targets Local FS & Shell · files · commands · Architecture component Local FS & Shell files · commands prompt · flags run config completion req HTTPS · SSE stream persist · resume auto-summary tool calls spawn gate side effects read/write/exec webfetch Legend External Database Cloud Backend Security

Run modes

  • • REPL: interactive session
  • • Headless -p: one-shot for CI
  • • stream-json: line-delimited events
  • • --resume / --continue

Built-in tools

  • • read · write · edit
  • • grep · find · bash
  • • todo · webfetch
  • • JSON-Schema validated args

Providers & protocols

  • • OpenRouter (default), Ollama, NIM
  • • Anthropic, any OpenAI-compatible
  • • OpenAI + Anthropic-Messages wire
  • • dual failure model · retry · SSE

Agent loop internals

  • • Inner: stream → run tools → feed back
  • • Outer: follow-up messages
  • • Per-turn hooks: steer / prepare / stop
  • • Compaction near context limit

Trust & safety

  • • bash/write/edit gated in untrusted dirs
  • • --approve one-shot authorization
  • • Sub-agents: goroutine or process isolation

Extensibility

  • • Skills: /slash commands
  • • Plugins: ~/.pigo/plugins
  • • Package mgr: pigo install npm:<pkg>
  • • Layered system prompt + AGENTS.md

Architecture diagram • Built with Archify • Hover to trace • R route • Click to focus • +/− zoom • M radar • T theme • E export