Omegon

An opinionated distribution of pi — the coding agent by Mario Zechner. Omegon bundles pi core with extensions for persistent project memory, spec-driven development, local LLM inference, image generation, web search, parallel task decomposition, a live dashboard, and quality-of-life tools.

Relationship to pi: Omegon is not a fork or replacement. It packages pi as a dependency and layers extensions on top. All credit for the pi coding agent goes to Mario Zechner and the pi contributors. The core pi packages are migrating to the styrene-lab-owned npm scope (@styrene-lab/pi-coding-agent and related packages) so package ownership matches the styrene-lab/omegon-pi product boundary. Older @cwilson613/* package names are compatibility debt during the transition, not the long-term release boundary. If you want standalone pi without Omegon's extensions, install @mariozechner/pi-coding-agent directly.

Installation

npm install -g omegon-pi

Node requirement: Omegon requires Node.js 20+. Node 18 will fail because bundled pi-tui uses modern Unicode regex features unsupported by older runtimes.

This installs the omegon-pi command globally. A legacy pi alias remains available for compatibility. If a standalone pi package is already installed, omegon-pi transparently takes ownership of the lifecycle boundary so startup, update, verification, and restart all stay inside Omegon control. To switch back to standalone pi at any time:

npm uninstall -g omegon-pi
npm install -g @mariozechner/pi-coding-agent

First-time setup:

omegon-pi   # start Omegon in any project directory
/bootstrap  # check deps, install missing tools, configure preferences

Keeping up to date

Context	How
Installed Omegon (npm install -g omegon-pi)	Run /update from inside Omegon. Omegon installs the latest package, verifies the active omegon-pi command still resolves to Omegon, clears caches, then asks you to restart Omegon.
Dev checkout / contributor workflow	Run /update or ./scripts/install-pi.sh. Both follow the same lifecycle contract: pull/sync, build, refresh dependencies, npm link --force, verify the active omegon-pi target, then stop at an explicit restart handoff.
Lightweight cache refresh only	Run /refresh. This clears transient caches and reloads extensions, but it is not equivalent to package/runtime replacement.

The patched fork syncs from upstream daily via GitHub Actions. Bug fixes and new AI provider support land automatically. If a sync PR has conflicts, they are surfaced for manual review before merging — upstream changes are never silently dropped.

Note: /update is the authoritative Omegon update path. It intentionally ends at a verified restart boundary rather than hot-swapping the running process after package/runtime mutation.

Architecture

Omegon extends @styrene-lab/pi-coding-agent with 21 extensions, 12 skills, and 4 prompt templates — loaded automatically on session start.

Development Methodology

Omegon enforces spec-first development for non-trivial changes:

The full lifecycle: design → propose → spec → plan → implement → verify → archive. Given/When/Then scenarios are the source of truth for correctness — code implements the specs, not the reverse.

Extensions

📋 OpenSpec

Spec-driven development lifecycle — proposal → specs → design → tasks workflow with delta-spec merge on archive.

• Tool: openspec_manage
• Commands: /opsx:propose, /opsx:spec, /opsx:ff, /opsx:status, /opsx:verify, /opsx:archive, /opsx:sync
• Lifecycle stages: proposed → specified → planned → implementing → verifying → archived
• API contracts: When a change involves a network API, derives an OpenAPI 3.1 spec from Given/When/Then scenarios; /assess spec validates implementation against it
• Integrates with OpenSpec CLI profiles

🪓 Cleave

Parallel task decomposition with dependency-ordered wave dispatch in isolated git worktrees.

• Tools: cleave_assess (complexity evaluation), cleave_run (parallel dispatch)
• Commands: /cleave <directive>, /assess cleave, /assess diff, /assess spec
• OpenSpec integration: Uses tasks.md as the split plan when openspec/ exists, enriches child tasks with design decisions and spec acceptance criteria, reconciles task completion on merge, guides through verify → archive
• Skill-aware dispatch: Auto-matches skill files to children based on file scope patterns (e.g. *.py → python, Containerfile → oci). Annotations (<!-- skills: python, k8s -->) override auto-matching
• Model tier routing: Each child resolves an execution tier — explicit annotation > skill-based hint > default. Provider-neutral tier labels resolve to concrete models through the session routing policy
• Adversarial review loop (opt-in via review: true): After each child completes, an opus-tier reviewer checks for bugs, security issues, and spec compliance. Severity-gated: nits→accept, warnings→1 fix iteration, criticals→2 fixes then escalate, security→immediate escalate. Churn detection bails when >50% of issues reappear between rounds
• Large-run preflight: Asks which provider to favor before expensive dispatches, preventing mid-run subscription exhaustion

🌲 Design Tree

Structured design exploration with persistent markdown documents — the upstream of OpenSpec.

• Tools: design_tree (query), design_tree_update (create/mutate nodes)
• Commands: /design list, /design new, /design update, /design branch, /design decide, /design implement
• Document structure: Frontmatter (status, tags, dependencies, priority, issue_type, open questions) + sections (Overview, Research, Decisions, Open Questions, Implementation Notes)
• Work triage: design_tree(action="ready") returns all decided, dependency-resolved nodes sorted by priority — the session-start "what next?" query
• Blocked audit: design_tree(action="blocked") returns all stalled nodes with each blocking dependency's id, title, and status
• Priority: set_priority (1 = critical → 5 = trivial) on any node; ready auto-sorts by it
• Issue types: set_issue_type classifies nodes as epic | feature | task | bug | chore — bugs and chores are now first-class tracked work
• Auto-transition: Adding research or decisions to a seed node automatically transitions it to exploring and scaffolds the design spec — no manual ceremony
• Substance-over-ceremony gates: set_status(decided) checks for open questions and recorded decisions instead of artifact directory existence. Design specs are auto-extracted from doc content and archived
• OpenSpec bridge: design_tree_update with action: "implement" scaffolds openspec/changes/<node-id>/ from a decided node's content, auto-checkouts the directive branch, forks a scoped memory mind, and sets design focus; /cleave executes it
• Full pipeline: design → decide → implement (auto-checkout + mind fork) → /cleave → /assess spec → archive (mind merge-back + cleanup)

🧠 Project Memory

Persistent, cross-session knowledge stored in SQLite. Accumulates architectural decisions, constraints, patterns, and known issues — retrieved semantically each session.

• 11 tools: memory_store, memory_recall, memory_query, memory_supersede, memory_archive, memory_connect, memory_compact, memory_episodes, memory_focus, memory_release, memory_search_archive
• Semantic retrieval: Embedding-based search via Ollama (qwen3-embedding), falls back to FTS5 keyword search
• Background extraction: Auto-discovers facts from tool output without interrupting work
• Episodic memory: Generates session narratives at shutdown for "what happened last time" context
• Directive minds: implement forks a scoped memory mind from default; all fact reads/writes auto-scope to the directive. archive ingests discoveries back to default and cleans up. Zero-copy fork with parent-chain inheritance — no fact duplication, parent embeddings and edges are reused
• Global knowledge base: Cross-project facts at ~/.pi/memory/global.db
• Git sync: Exports to JSONL for version-controlled knowledge sharing across machines; volatile runtime scoring metadata (confidence, reinforcement counts, decay scores) omitted from exports for stable diffs
• Auto-compact: Context pressure monitoring with automatic compaction (absorbed from auto-compact extension)
• Session log: Append-only structured session tracking (absorbed from session-log extension)

📊 Dashboard

Live status panel showing design tree, OpenSpec changes, cleave dispatch, and git branches at a glance.

• Commands: /dash (toggle compact ↔ raised), /dashboard (open side panel)
• Compact mode: Single footer line — design/openspec/cleave summaries + context gauge
• Raised mode: Full-width expanded view (toggle with /dash)
  • Git branch tree rooted at repo name, annotated with linked design nodes
  • Two-column split at ≥120 terminal columns: design tree + cleave left, OpenSpec right
  • Directive indicator: shows ▸ directive: name ✓ (branch match) or ▸ directive: name ⚠ main (mismatch) when a directive mind is active
  • Context gauge · model · thinking level in shared footer zone
  • No line cap — renders as much content as needed
• Keyboard: Ctrl+Shift+B toggles raised/compact
• Terminal title: Dynamic tab titles showing active cleave runs and git branch (absorbed from terminal-title extension)
• Core renderers: Sci-UI rendering for Omegon's custom tools (absorbed from core-renderers extension)

🌐 Web UI

Localhost-only, read-only HTTP dashboard that exposes live control-plane state as JSON. It binds to 127.0.0.1, is not started automatically, and serves no mutation endpoints in the MVP.

• Command: /web-ui [start|stop|status|open]
• Shell: polling-first HTML dashboard
• Endpoints: GET /api/state, plus slice routes /api/session, /api/dashboard, /api/design-tree, /api/openspec, /api/cleave, /api/models, /api/memory, /api/health
• State contract: versioned ControlPlaneState (schema v1)

🚀 Inference

Unified inference management — local models, effort tiers, model budget control, and offline driver switching.

• Tools: set_model_tier, set_thinking_level, switch_to_offline_driver, ask_local_model, list_local_models, manage_ollama
• Commands: /local-models, /local-status, /effort <name>, /effort cap, /effort uncap
• Effort tiers: Seven named tiers using provider-neutral labels — tier labels resolve to concrete model IDs from whichever provider (Anthropic or OpenAI) the session routing policy prefers:

Tier	Name	Driver	Thinking	Review
1	Servitor	local	off	local
2	Average	local	minimal	local
3	Substantial	victory	low	victory
4	Ruthless	victory	medium	victory
5	Lethal	victory	high	gloriana
6	Absolute	gloriana	high	gloriana
7	Omnissiah	gloriana	high	gloriana

• Local inference: Delegate sub-tasks to locally running LLMs via Ollama — zero API cost
• Model budget: Switch model tiers to match task complexity and conserve API spend
• Offline driver: Switch the driving model from cloud to a local Ollama model when connectivity drops
• Auto-discovery: Available models detected on session start
• Hardware-aware selection: Model registry covers 64GB (70B), 32GB (32B), 24GB (14B/MoE-30B), 16GB (8B), 8GB (4B)

🎭 Ambiance

Atmospheric UI enhancements — themed loading messages and ambient scrolling text.

• Spinner verbs: Warhammer 40K-themed loading messages (consolidated from spinner-verbs extension)
• Sermon: The Crawler's scrawl — ambient organic/computational text that scrolls beneath the spinner (consolidated from sermon extension)
• Sermon widget: Visual component integration for ambient text display (consolidated from sermon-widget extension)

🎨 Render

Generate images and diagrams directly in the terminal.

• FLUX.1 image generation via MLX on Apple Silicon — generate_image_local
• D2 diagrams rendered inline — render_diagram
• Native SVG/PNG diagrams for canonical motifs (pipeline, fanout, panel-split) — render_native_diagram
• Excalidraw JSON-to-PNG rendering — render_excalidraw
• React composition stills via Satori + resvg — render_composition_still
• React composition video (animated GIF/MP4) via Satori + gifenc — render_composition_video

🔍 Web Search

Multi-provider web search with deduplication.

• Tool: web_search
• Providers: Brave, Tavily, Serper (Google)
• Modes: quick (single provider, fastest), deep (more results), compare (all providers, best for research)

🗂️ Tool Profiles

Enable or disable tools and switch named profiles to keep the context window lean.

• Tool: manage_tools
• Command: /profile [name|reset]
• Pre-built profiles for common workflows; per-tool enable/disable for fine-grained control

📖 Vault

Markdown viewport for project documentation — serves docs with wikilink navigation and graph view.

• Command: /vault

🔐 Secrets

Resolve secrets from environment variables, shell commands, or system keychains — without storing values in config.

• Declarative @secret annotations in extension headers
• Sources: env:, cmd:, keychain:

🌐 MCP Bridge

Connect external MCP (Model Context Protocol) servers as native pi tools.

• Bridges MCP tool schemas into pi's tool registry
• Stdio transport for local MCP servers

🔧 Utilities

Extension	Description
00-splash	Animated ASCII logo with glitch-convergence startup animation and loading checklist
bootstrap	First-time setup — check/install dependencies, capture operator preferences, version checking (/bootstrap, /refresh, /update)
chronos	Authoritative date/time from system clock — eliminates AI date math errors
01-auth	Auth status, diagnosis, and refresh across git, GitHub, GitLab, AWS, k8s, OCI (/auth, /whoami)
view	Inline file viewer — images, PDFs, docs, syntax-highlighted code
defaults	Deploys AGENTS.md and theme on first install; content-hash guard prevents overwriting customizations
style	Alpharius design system reference (/style)
web-ui	Localhost-only read-only HTTP dashboard and JSON control-plane endpoints (`/web-ui [start

Note: Several utility extensions have been absorbed into their logical hosts: auto-compact and session-log → project-memory, version-check → bootstrap, terminal-title and core-renderers → dashboard, spinner-verbs, sermon, and sermon-widget → ambiance.

Skills

Skills provide specialized instructions the agent loads on-demand when a task matches.

Skill	Description
openspec	OpenSpec lifecycle — writing specs, deriving API contracts, generating tasks, verifying implementations
cleave	Task decomposition, code assessment, OpenSpec lifecycle integration
git	Conventional commits, semantic versioning, branch naming, changelogs
oci	Container and artifact best practices — Containerfile authoring, multi-arch builds, registry auth
python	Project setup (src/ layout, pyproject.toml), pytest, ruff, mypy, packaging, venv
rust	Cargo, clippy, rustfmt, Zellij WASM plugin development
typescript	Strict typing, async patterns, error handling, node:test conventions for Omegon
pi-extensions	pi extension API — registerCommand, registerTool, event handlers, TUI context, common pitfalls
pi-tui	TUI component patterns — Component interface, overlays, keyboard handling, theming, footer/widget APIs
security	Input escaping, injection prevention, path traversal, process safety, secrets management
style	Alpharius color system, typography, spacing — shared across TUI, D2 diagrams, and generated images
vault	Obsidian-compatible markdown conventions — wikilinks, frontmatter, vault-friendly file organization

Prompt Templates

Pre-built prompts for common workflows:

Template	Description
new-repo	Scaffold a new repository with conventions
init	First-session environment check — orient to a new project directory
status	Session orientation — load project state and show what's active
oci-login	OCI registry authentication

Requirements

Required:

• omegon-pi — install via npm install -g omegon-pi; launch via omegon-pi
• @styrene-lab/pi-coding-agent ≥ 0.57 underpins Omegon's bundled agent core and tracks a patched fork of badlogic/pi-mono. Fork source: cwilson613/pi-mono

Optional (installed by /bootstrap):

• Ollama — local inference, offline mode, semantic memory search
• d2 — diagram rendering
• mflux — FLUX.1 image generation on Apple Silicon
• API keys for web search (Brave, Tavily, or Serper)

Run /bootstrap after install to check dependencies and configure preferences.

Why a Patched Fork?

Upstream badlogic/pi-mono is the canonical pi coding agent. Omegon depends on a fork rather than the upstream package for two reasons:

1. OAuth login reliability — upstream had no fetch timeout on OAuth token exchange calls. A slow or unreachable endpoint would hang the login UI indefinitely with no recovery path. Fixed in packages/ai/src/utils/oauth/.

2. Bracketed-paste stuck state — a missing end-marker (e.g. from a large paste that split across chunks) would leave isInPaste = true permanently, silently swallowing all subsequent keystrokes including Enter. Fixed with a 500ms watchdog timer and Escape-to-clear in packages/tui/src/components/input.ts.

Both fixes were submitted as PRs to upstream (#2060, #2061) but were closed without merge. The fork is maintained independently under the @styrene-lab/* npm scope.

License

ISC.