oh-my-pi: AI coding agent for terminal with hash-anchored edits

Rust Crates:
├── pi-natives           (~27k LoC)
│   ├── shell (3,700 LoC) - Embedded bash with persistent sessions
│   ├── grep (1,900 LoC)  - Regex search with parallel/sequential modes
│   ├── keys (1,490 LoC)  - Kitty keyboard protocol with PHF lookup
│   ├── text (1,450 LoC)  - ANSI-aware width and SGR-preserving wrap
│   ├── summarize (1,040 LoC) - Tree-sitter structural source summaries
│   ├── ast (1,000 LoC)   - ast-grep pattern matching and rewrites
│   ├── fs_cache (840 LoC) - Mtime-keyed file cache
│   ├── highlight (470 LoC) - Syntax highlighting (11 categories, 30+ aliases)
│   ├── pty (455 LoC)     - Native PTY allocation for sudo/ssh
│   ├── glob (410 LoC)    - Discovery with glob/type filters, gitignore
│   ├── workspace (385 LoC) - Workspace walker with AGENTS.md discovery
│   ├── appearance (270 LoC) - Mode 2031 + native macOS dark/light
│   ├── power (270 LoC)   - macOS power-assertion API
│   ├── task (260 LoC)    - libuv thread pool, cancellation, profiling
│   ├── fd (250 LoC)      - Filesystem walker (find-tool replacement)
│   ├── iso (245 LoC)     - Workspace isolation (APFS, btrfs, zfs, overlayfs)
│   ├── prof (240 LoC)    - Circular buffer profiler with SVG flamegraphs
│   ├── ps (195 LoC)      - Cross-platform process-tree kill/listing
│   ├── image (190 LoC)   - PNG/JPEG/WebP/GIF decode/encode/resize
│   ├── clipboard (80 LoC) - System clipboard (no xclip/pbcopy)
│   ├── tokens (65 LoC)   - O200k/Cl100k BPE token counting
│   └── html (50 LoC)     - HTML to Markdown converter
└── pi-shell, pi-ast, pi-iso: Specialized crates split from pi-natives

TypeScript Packages:
├── @oh-my-pi/pi-ai           - Multi-provider LLM client
├── @oh-my-pi/pi-agent-core   - Agent runtime, tool calling
├── @oh-my-pi/pi-coding-agent - CLI + SDK
├── @oh-my-pi/pi-tui          - Terminal UI with differential rendering
├── @oh-my-pi/pi-natives      - N-API bindings
├── @oh-my-pi/pi-utils        - Logging, streams, dirs/env/process helpers
├── @oh-my-pi/omp-stats       - Local observability dashboard
└── @oh-my-pi/swarm-extension - Swarm orchestration

32 Built-in Tools:

Files & Search:
- read: files, dirs, archives, SQLite, PDFs, URLs, internal schemes
- write: create/overwrite files, archive entries, SQLite rows
- edit: hashline patches with content-hash anchors
- ast_edit: structural rewrites previewed before apply (ast-grep)
- ast_grep: structural code queries over 50+ tree-sitter grammars
- search: regex over files, globs, URLs
- find: glob-based path lookup

Runtime:
- bash: workspace shell with optional PTY or background-job dispatch
- eval: persistent Python and JavaScript cells with tool re-entry
- recipe: invoke targets from detected task runners (bun, just, make, cargo)
- ssh: remote commands against configured hosts

Code Intelligence:
- lsp: diagnostics, navigation, symbols, renames, code actions
- debug: drive DAP sessions (breakpoints, stepping, threads, stack, variables)

Coordination:
- task: fan out subagents in parallel, workspace-isolated
- irc: short prose between live agents
- todo_write: ordered mutations over session todo list with phase tracking
- job: wait on or cancel background jobs
- ask: structured follow-up questions

Outside the Box:
- browser: Puppeteer tabs over headless Chromium or CDP-attached apps
- web_search: one query across 14 configured providers with citations
- github: GitHub CLI ops (repo, PR, issues, code search, Actions)
- generate_image: raster images via Gemini image models
- inspect_image: vision-model analysis of local files
- render_mermaid: Mermaid to terminal ASCII or PNG

Memory & State:
- checkpoint: mark conversation state for later collapse-and-report
- rewind: prune exploratory context, keep concise report
- retain: queue durable facts into Hindsight bank
- recall: search Hindsight bank for raw memories
- reflect: ask Hindsight to synthesize answers

Misc:
- calc: deterministic arithmetic (no model in loop)
- resolve: apply or discard queued preview actions
- search_tool_bm25: BM25 over hidden tool index

Model Provider Categories:

Frontier APIs (direct + gateways):
├── Anthropic [oauth]
├── OpenAI
├── OpenAI Codex [oauth]
├── Google Gemini
├── Google Antigravity [oauth]
├── xAI
├── Mistral
├── Groq
├── Cerebras
├── Fireworks
├── Together
├── Hugging Face
├── NVIDIA
├── OpenRouter
├── Synthetic
├── Vercel AI Gateway
├── Cloudflare AI Gateway
└── Perplexity [oauth]

Coding Plans (subscription-routed):
├── Cursor [oauth]
├── GitHub Copilot [oauth]
├── GitLab Duo
├── Kimi Code (plan)
├── Moonshot
├── MiniMax Coding Plan (plan)
├── MiniMax Coding Plan CN
├── Alibaba Coding Plan (plan)
├── Qwen Portal
├── Z.AI / GLM Coding Plan (plan)
├── Xiaomi MiMo
├── Qianfan
├── NanoGPT
├── Venice
├── Kilo
├── ZenMux
├── OpenCode Go
└── OpenCode Zen

Local/self-hosted:
├── Ollama [local]
├── Ollama Cloud
├── LM Studio [local]
├── llama.cpp [local]
├── vLLM [local]
└── LiteLLM

Web Search Providers (14 backends):
├── auto (chain)
├── exa (EXA_API_KEY or mcp)
├── brave (BRAVE_API_KEY)
├── jina (JINA_API_KEY)
├── kimi (MOONSHOT_API_KEY)
├── zai (ZAI_API_KEY)
├── anthropic (oauth)
├── perplexity (PERPLEXITY_API_KEY)
├── gemini (oauth)
├── codex (oauth)
├── tavily (TAVILY_API_KEY)
├── parallel (PARALLEL_API_KEY)
├── kagi (KAGI_API_KEY)
├── synthetic (SYNTHETIC_API_KEY)
└── searxng (self-hosted)

# Check your system architecture
uname -m

# Verify Bun version (if using Bun install)
bun --version
# Should be >= 1.13

# Verify curl is available (for install script)
curl --version

# Check mise version (if using pinned installations)
mise --version

# Method 1: Install script (macOS · Linux)
# Runs as current user, installs to ~/.local/bin
curl -fsSL https://omp.sh/install | sh

# Method 2: Bun global install (recommended)
# Requires Bun 1.13+, easiest to update
bun install -g @oh-my-pi/pi-coding-agent

# Method 3: Windows PowerShell
# Native Windows support - no WSL needed
# Run in PowerShell:
irm https://omp.sh/install.ps1 | iex

# Method 4: Pinned versions with mise
# For reproducible, version-locked installs
mise use -g github:can1357/oh-my-pi

# Verify installation
omp --version
omp --help

# Start interactive session
omp

# Run one-shot prompt (non-interactive)
omp -p "list all .ts files in current directory"

# Interactive with custom model
omp --slow <your-reasoning-model>
omp --smol <your-fast-model>
omp --plan <your-planning-model>

# Start in RPC mode for programmatic control
omp --mode rpc
omp --mode rpc-ui  # Adds UI elements

# View and edit configuration
cat ~/.omp/agent/config.toml
nano ~/.omp/agent/config.toml

# View available models through slash command
# In TUI: /models

# Switch models mid-session
# In the TUI, press Ctrl+P to cycle through configured models
# Or use slash command: /model <provider>/<model>

# File operations (agent tools)
read src/index.ts          # Read single file
# Read automatically summarizes large files
# read handles archives: read archive.zip::src/file.ts
# read handles URLs: read https://example.com/docs
# read handles internal schemes: read pr://123

# Search and find
search "function.*export"      # Regex search in files
find "*.ts"                    # Glob-based path lookup

# Runtime execution
bash
npm install
npm test

# Persistent eval session
eval python
import pandas as pd
# This kernel remembers variables across calls

eval javascript
# JavaScript kernel with tool access

# LSP Operations

# Diagnostics
lsp diagnostics
lsp diagnostics src/file.ts  # Single file

# Navigation
lsp definition src/file.ts:42:10    # Go to definition
lsp typeDefinition src/file.ts:42:10

# Symbols
lsp workspaceSymbols "AuthService"
lsp documentSymbols src/file.ts

# References
lsp references formatBytes
lsp references src/utils.ts:25:8

# Rename (IDE-aware, updates barrel files)
lsp rename oldName newName
lsp rename src/file.ts:15:5 newName

# Code actions
lsp codeActions src/file.ts:10:0:20:0

# Formatting
lsp format src/file.ts

# Debugging with DAP

# Attach to running process
debug attach lldb /path/to/binary

# Debug Python
debug attach debugpy <pid>

# Debug Go
debug attach dlv <pid>

# In debug session:
debug breakpoint src/file.ts:42
debug step
debug next
debug continue
debug stack
debug variables
debug evaluate "someExpression"

# Spawning subagents

# Parallel subagents (default)
task "Analyze the authentication module and report security concerns"
task "Review the API endpoints for consistency issues"

# Subagents run in isolated worktrees when needed
# Results come back as typed JSON objects
# The parent reads findings directly from the output

# Example findings structure from subagent:
{"findings": [{"path": "src/auth/middleware.ts", "severity": "high", "issue": "Missing rate limiting"}]}

# IRC coordination between agents
irc "To ComponentExporter: I found the exports you need in routes.ts"
irc "To ReviewerWorker: Please check the database migration"

# Access subagent output by path
read agent://SubagentName/findings.0.path
read agent://SubagentName/summary

# Web search (built-in tool)

# Auto-selects best provider
web_search "LLM inference compute scaling laws"

# Pin specific provider
web_search --provider exa "Rust async patterns"
web_search --provider brave "Next.js 15 features"
web_search --provider perplexity "TypeScript 5.8 new features"

# Returns structured results:
# - Ranked URLs with descriptions
# - Site-aware extraction
#   - GitHub: PR/issue content as markdown
#   - arXiv: PDF papers with structured metadata
#   - npm/pip/crates.io: Package registry info
#   - Stack Overflow: Q&A with code highlighted

# Browser tool (headless or CDP-attached)

# Navigate and interact
browser "Go to https://example.com"
browser "Click the login button"
browser "Type 'test@example.com' into email field"

# Extract content
browser "Get all product titles from the page"
browser "Summarize the documentation"

# Stealth is enabled by default
# Can drive Slack, Discord, or any Electron app
browser --app slack "Find messages from @user in #channel"

# Retain facts during session

# Queue a fact for the Hindsight bank
retain "The project uses custom auth middleware located in src/auth/middleware.ts"
retain "API endpoints follow RESTful patterns but use custom pagination with cursor-based navigation"
retain "Database migrations are managed with Prisma, with seed data in prisma/seed.ts"

# Recall raw memories
recall "how does authentication work"
# Returns stored facts matching the query

# Reflect - synthesize answers
reflect "What is the project structure and architecture?"
# Hindsight synthesizes an answer from the bank

# Benefits:
#- Agent remembers your codebase between sessions
#- Project-scoped memory (repo-specific)
#- No context tax on every turn
#- Injected at session start for instant recall
#- Compressed at session end
#- Survives compaction without losing key facts

# ~/.omp/agent/config.toml

[models]
# Default model for regular turns
default = "anthropic/claude-3-5-sonnet"

# Models for specific roles
smol = "groq/llama-3.1-8b"      # Cheap subagent fan-out
slow = "openai/o1-preview"      # Deep reasoning
plan = "anthropic/claude-3-opus" # Plan mode
commit = "groq/llama-3.1-8b"    # Changelogs

[tools]
# Toggle tools on/off (setting-gated tools)
default = ["read", "write", "edit", "bash", "search"]
# Add tools as needed:
github = true           # GitHub CLI ops
calc = true            # Deterministic arithmetic
inspect_image = true    # Vision model analysis
render_mermaid = true   # Mermaid to ASCII/PNG
checkpoint = true       # State marking
rewind = true          # Context pruning
search_tool_bm25 = true # Hidden tool discovery
retain = true          # Hindsight memory write
recall = true          # Hindsight memory read
reflect = true         # Hindsight synthesis

[auth]
# Authentication storage
type = "keyring"       # macOS Keychain, Linux Secret Service, Windows Credential Manager
# Or: type = "env"     # Use environment variables
# Or: type = "file"    # Use file-based storage

[workspace]
# Path-scoped settings
paths.my-repo.modelRoles.default = "anthropic/claude-3-5-sonnet"
paths.my-repo.modelRoles.smol = "groq/llama-3.1-8b"

# Workspace isolation
isoBackend = "auto"    # Auto-detect: APFS, btrfs, zfs, overlayfs, projfs, rcopy

[retry]
# Fallback chains for reliability
fallbackChains = [
  { primary = "anthropic/claude-3-5-sonnet", fallback = ["openai/gpt-4o", "gemini/gemini-1.5-pro"] }
]

# Round-robin credentials for quota management
credentials.anthropic = ["key1", "key2", "key3"]

# Internal URL schemes work transparently

# Read PRs as if they were files
read pr://can1357/oh-my-pi/1063
read pr://myorg/myrepo/42

# Read GitHub issues
read issue://can1357/oh-my-pi/137
read issue://myorg/myrepo/123

# Access subagent outputs by path
read agent://Worker/findings.0.path
read agent://Worker/summary
read agent://Worker/recommendations

# Access skills and rules
read skill://deployment-guide
read rule://security-checks

# Conflict resolution (each conflict is one URL)
read conflict://1       # View conflict N
# Write to resolve:
write conflict://1 "@theirs"  # Accept their version
write conflict://1 "@ours"    # Keep our version  
write conflict://1 "@base"    # Use base version

# Bulk form for multiple conflicts
write conflict://* "@ours"    # Accept ours for all

# PR-specific operations
read pr://myrepo/123:src/file.ts  # Specific file in PR
diff pr://myrepo/123              # Full PR diff

# The same interface works for:
#- Local files: read src/file.ts
#- PR files:    read pr://123:src/file.ts
#- Issue files: read issue://123:docs/readme.md

// Node.js SDK embedding

import { 
  ModelRegistry, 
  SessionManager, 
  createAgentSession, 
  discoverAuthStorage 
} from "@oh-my-pi/pi-coding-agent";

// Discover authentication storage
const auth = await discoverAuthStorage();

// Create model registry with providers
const models = new ModelRegistry(auth);
await models.refresh();

// Create agent session
const { session } = await createAgentSession({
  sessionManager: SessionManager.inMemory(),
  authStorage: auth,
  modelRegistry: models,
});

// Subscribe to events
session.on("message", (msg) => console.log(msg));
session.on("tool_call", (call) => console.log("Tool:", call.name));
session.on("complete", () => console.log("Done"));

// Send prompt
await session.prompt("list all .ts files in the current directory");

// RPC mode for non-Node embedders

// Launch in RPC mode
$ omp --mode rpc --no-session

// Send NDJSON commands
{
  "id": "r1",
  "type": "prompt",
  "message": "list .ts files"
}

// Receive response frames
{
  "id": "r1",
  "type": "response",
  "result": "..."
}

// Events stream concurrently
{
  "type": "event",
  "name": "tool_call",
  "data": "{...}"
}

// More RPC commands:  
{"id": "r2", "type": "set_model", "provider": "anthropic", "modelId": "sonnet-4.5"}
{"id": "r3", "type": "abort"}

# Clone the repository
git clone https://github.com/can1357/oh-my-pi.git
cd oh-my-pi

# Install dependencies
bun install
# or: npm install / pnpm install

# Build Rust crates (requires Rust 1.80+)
cd crates
# Each crate has its own tests and build commands

# Build the project
bun run build

# Run tests
bun run test

# Development server
cd packages/coding-agent
bun run dev

# Debug command in TUI
omp /debug
# Opens debugging tools, profiling, and reporting

# Profiling tools:
#- Circular buffer profiler
#- SVG flamegraph output
#- Folded-stack analysis

# Contribute:
# See packages/coding-agent/DEVELOPMENT.md for guidelines
# All code is MIT licensed
# TypeScript packages in packages/
# Rust crates in crates/

Performance Metrics:

Grok Code Fast 1:
- Before: 6.7% success rate
- After: 68.3% success rate
- Improvement: Tenfold lift from hashline format

Gemini 3 Flash:
- +5 percentage points over str_replace
- Beats Google's own optimization

Grok 4 Fast:
- 61% fewer output tokens
- Output collapses without retry loops

MiniMax:
- 2.1x pass rate improvement
- Same weights, same prompt - just better harness

Rust Implementation (~27k lines):
- Shell execution (no fork/exec)
- Grep search (parallel threads)
- PTY allocation (sudo, ssh interactive)
- Syntax highlighting (11 categories, 30+ aliases)
- Image decode/encode (PNG, JPEG, WebP, GIF)
- BPE token counting (O200k, Cl100k embedded)
- HTML to Markdown conversion
- All running on libuv thread pool

Optimization Strategies:
- All tools in-process (no subprocess overhead)
- Hashline anchoring (no whitespace battles)
- Stream interruption (course-correct mid-token)
- Hindsight compaction (no context bloat)
- Fallback chains (no dead waits on rate limits)
- Round-robin credentials (quota distribution)

Official Resources:

Website: https://omp.sh
Docs: https://omp.sh/docs/tools         # All 32 tools
     https://omp.sh/docs/providers     # 40+ providers
     https://omp.sh/docs/sdk          # Embedding guide

GitHub: https://github.com/can1357/oh-my-pi
npm: https://www.npmjs.com/package/@oh-my-pi/pi-coding-agent
Changelog: https://github.com/can1357/oh-my-pi/blob/main/packages/coding-agent/CHANGELOG.md

Community:
Discord: https://discord.gg/4NMW9cdXZa

Original Project:
Pi by Mario Zechner: https://github.com/badlogic/pi-mono

License:
MIT - Open source all the way down

Contributors:
© 2025 Mario Zechner
© 2025-2026 Can Bölük

Tags:
#AI #Agent #Terminal #Coding #Rust #TypeScript #Bun