AI coding agent for the terminal

Fork of badlogic/pi-mono by @mariozechner

---

Installation

Via Bun (recommended)

Requires Bun runtime:

bun install -g @oh-my-pi/pi-coding-agent

Via installer script

Linux / macOS:

curl -fsSL https://raw.githubusercontent.com/can1357/oh-my-pi/main/scripts/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/can1357/oh-my-pi/main/scripts/install.ps1 | iex

By default, the installer uses bun if available, otherwise downloads the prebuilt binary.

Options:

• --source / -Source: Install via bun (installs bun first if needed)
• --binary / -Binary: Always use prebuilt binary
• --ref <ref> / -Ref <ref>: Install a tag/commit/branch (defaults to source install)

# Force bun installation
curl -fsSL .../install.sh | sh -s -- --source

# Install a tag via binary
curl -fsSL .../install.sh | sh -s -- --binary --ref v3.20.1

# Install a branch or commit via source
curl -fsSL .../install.sh | sh -s -- --source --ref main

# Install a tag via binary
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/can1357/oh-my-pi/main/scripts/install.ps1))) -Binary -Ref v3.20.1

# Install a branch or commit via source
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/can1357/oh-my-pi/main/scripts/install.ps1))) -Source -Ref main

Manual download

Download binaries directly from GitHub Releases.

---

+ Commit Tool (AI-Powered Git Commits)

AI-powered conventional commit generation with intelligent change analysis:

• Agentic mode: Tool-based git inspection with git-overview, git-file-diff, git-hunk for fine-grained analysis
• Split commits: Automatically separates unrelated changes into atomic commits with dependency ordering
• Hunk-level staging: Stage individual hunks when changes span multiple concerns
• Changelog generation: Proposes and applies changelog entries to CHANGELOG.md files
• Commit validation: Detects filler words, meta phrases, and enforces conventional commit format
• Legacy mode: --legacy flag for deterministic pipeline when preferred
• Run via omp commit with options: --push, --dry-run, --no-changelog, --context

+ Python Tool (IPython Kernel)

Execute Python code with a persistent IPython kernel and 30+ shell-like helpers:

• Streaming output: Real-time stdout/stderr with image and JSON rendering
• Prelude helpers: cat(), sed(), rsed(), find(), grep(), batch(), sh(), run() and more
• Git utilities: git_status(), git_diff(), git_log(), git_show() for repository operations
• Line operations: extract_lines(), delete_lines(), insert_lines(), lines_matching() for text manipulation
• Shared gateway: Resource-efficient kernel reuse across sessions (python.sharedGateway setting)
• Custom modules: Load extensions from .omp/modules/ and .pi/modules/ directories
• Rich output: Supports display() for HTML, Markdown, images, and interactive JSON trees
• Mermaid diagrams: Renders mermaid code blocks as inline graphics in iTerm2/Kitty terminals
• Install dependencies via omp setup python

+ LSP Integration (Language Server Protocol)

Full IDE-like code intelligence with automatic formatting and diagnostics:

• Format-on-write: Auto-format code using the language server's formatter (rustfmt, gofmt, prettier, etc.)
• Diagnostics on write/edit: Immediate feedback on syntax errors and type issues after every file change
• Workspace diagnostics: Check entire project for errors (lsp action=workspace_diagnostics)
• 40+ language configs: Out-of-the-box support for Rust, Go, Python, TypeScript, Java, Kotlin, Scala, Haskell, OCaml, Elixir, Ruby, PHP, C#, Lua, Nix, and many more
• Local binary resolution: Auto-discovers project-local LSP servers in node_modules/.bin/, .venv/bin/, etc.
• Hover docs, symbol references, code actions, workspace-wide symbol search

+ Time Traveling Streamed Rules (TTSR)

Zero context-use rules that inject themselves only when needed:

• Pattern-triggered injection: Rules define regex triggers that watch the model's output stream
• Just-in-time activation: When a pattern matches, the stream aborts, the rule injects as a system reminder, and the request retries
• Zero upfront cost: TTSR rules consume no context until they're actually relevant
• One-shot per session: Each rule only triggers once, preventing loops
• Define via ttsrTrigger field in rule files (regex pattern)

Example: A "don't use deprecated API" rule only activates when the model starts writing deprecated code, saving context for sessions that never touch that API.

+ Interactive Code Review

Structured code review with priority-based findings:

• /review command: Interactive mode selection (branch comparison, uncommitted changes, commit review)
• Structured findings: report_finding tool with priority levels (P0-P3: critical → nit)
• Verdict rendering: aggregates findings into approve/request-changes/comment
• Combined result tree showing verdict and all findings

+ Task Tool (Subagent System)

Parallel execution framework with specialized agents and real-time streaming:

• 5 bundled agents: explore, plan, browser, task, reviewer
• Parallel exploration: Reviewer agent can spawn explore agents for large codebase analysis
• Real-time artifact streaming: Task outputs stream as they're created, not just at completion
• Output tool: Read full agent outputs by ID when truncated previews aren't sufficient
• Isolated execution: isolated: true runs tasks in git worktrees, generates patches, and applies cleanly
• User-level (~/.omp/agent/agents/) and project-level (.omp/agents/) custom agents
• Concurrency-limited batch execution with progress tracking

+ Model Roles

Configure different models for different purposes with automatic discovery:

• Three roles: default (main model), smol (fast/cheap), slow (comprehensive reasoning)
• Auto-discovery: Smol finds haiku → flash → mini; Slow finds codex → gpt → opus → pro
• Role-based selection: Task tool agents can use model: pi/smol for cost-effective exploration
• CLI args (--smol, --slow) and env vars (PI_SMOL_MODEL, PI_SLOW_MODEL)
• Configure via /model selector with keybindings (Enter=default, S=smol, L=slow)

+ Todo Tool (Task Tracking)

Structured task management with persistent visual tracking:

• todo_write tool: Create and manage task lists during coding sessions
• Persistent panel: Todo list displays above the editor with real-time progress
• Task states: pending, in_progress, completed with automatic status updates
• Completion reminders: Agent warned when stopping with incomplete todos (todoCompletion setting)
• Toggle visibility: Ctrl+T expands/collapses the todo panel

+ Ask Tool (Interactive Questioning)

Structured user interaction with typed options:

• Multiple choice questions: Present options with descriptions for user selection
• Multi-select support: Allow multiple answers when choices aren't mutually exclusive
• Multi-part questions: Ask multiple related questions in sequence via questions array parameter

+ Custom TypeScript Slash Commands

Programmable commands with full API access:

• Create at ~/.omp/agent/commands/[name]/index.ts or .omp/commands/[name]/index.ts
• Export factory returning { name, description, execute(args, ctx) }
• Full access to HookCommandContext for UI dialogs, session control, shell execution
• Return string to send as LLM prompt, or void for fire-and-forget actions
• Also loads from Claude Code directories (~/.claude/commands/, .claude/commands/)

+ Universal Config Discovery

Unified capability-based discovery that loads configuration from 8 AI coding tools:

• Multi-tool support: Claude Code, Cursor, Windsurf, Gemini, Codex, Cline, GitHub Copilot, VS Code
• Discovers everything: MCP servers, rules, skills, hooks, tools, slash commands, prompts, context files
• Native format support: Cursor MDC frontmatter, Windsurf rules, Cline .clinerules, Copilot applyTo globs, Gemini system.md, Codex AGENTS.md
• Provider attribution: See which tool contributed each configuration item
• Discovery settings: Enable/disable individual providers via /config interactive tab
• Priority ordering: Multi-path resolution across .omp, .pi, and .claude directories

+ MCP & Plugin System

Full Model Context Protocol support with external tool integration:

• Stdio and HTTP transports for connecting to MCP servers
• Plugin CLI (omp plugin install/enable/configure/doctor)
• Hot-loadable plugins from ~/.omp/plugins/ with npm/bun integration
• Automatic Exa MCP server filtering with API key extraction

+ Web Search & Fetch

Multi-provider search and full-page scraping with 80+ specialized scrapers:

• Multi-provider search: Anthropic, Perplexity, and Exa with automatic fallback chain
• 80+ site-specific scrapers: GitHub, GitLab, npm, PyPI, crates.io, arXiv, PubMed, Stack Overflow, Hacker News, Reddit, Wikipedia, YouTube transcripts, and many more
• Package registries: npm, PyPI, crates.io, Hex, Hackage, NuGet, Maven, RubyGems, Packagist, pub.dev, Go packages
• Security databases: NVD, OSV, CISA KEV vulnerability data
• HTML-to-markdown conversion with link preservation

+ SSH Tool

Remote command execution with persistent connections:

• Project discovery: Reads SSH hosts from ssh.json / .ssh.json in your project
• Persistent connections: Reuses SSH connections across commands for faster execution
• OS/shell detection: Automatically detects remote OS and shell type
• SSHFS mounts: Optional automatic mounting of remote directories
• Compat mode: Windows host support with automatic shell probing

+ Browser Tool (Puppeteer with Stealth)

Headless browser automation with 14 stealth scripts to evade bot detection:

• 25+ actions: Navigate, click, type, fill, scroll, drag, screenshot, evaluate JS, extract readable content
• Accessibility snapshots: Observe interactive elements via the accessibility tree with numeric IDs for reliable targeting
• 14 stealth plugins: Custom scripts covering toString tampering, WebGL fingerprinting, audio context, screen dimensions, font enumeration, plugin/mime-type mocking, hardware concurrency, codec availability, iframe detection, locale spoofing, worker detection, and more
• User agent spoofing: Removes HeadlessChrome identifier, generates proper Client Hints brand lists, applies overrides via CDP Network and Emulation domains
• Selector flexibility: CSS, aria/, text/, xpath/, pierce/ query handlers for Shadow DOM piercing
• Reader mode: extract_readable action uses Mozilla Readability for clean article extraction
• Headless/visible toggle: Switch modes at runtime via /browser command or browser.headless setting

+ Cursor Provider

Use your Cursor Pro subscription for AI completions:

• Browser-based OAuth: Authenticate through Cursor's OAuth flow
• Tool execution bridge: Maps Cursor's native tools to omp equivalents (read, write, shell, diagnostics)
• Conversation caching: Persists context across requests in the same session
• Shell streaming: Real-time stdout/stderr during command execution

+ Multi-Credential Support

Distribute load across multiple API keys:

• Round-robin distribution: Automatically cycles through credentials per session
• Usage-aware selection: For OpenAI Codex, checks account limits before credential selection
• Automatic fallback: Switches credentials mid-session when rate limits are hit
• Consistent hashing: FNV-1a hashing ensures stable credential assignment per session

+ Image Generation

Create images directly from the agent:

• Gemini integration: Uses gemini-3-pro-image-preview by default
• OpenRouter fallback: Automatically uses OpenRouter when OPENROUTER_API_KEY is set
• Inline display: Images render in terminals supporting Kitty/iTerm2 graphics
• Saves to temp files and reports paths for further manipulation

+ TUI Overhaul

Modern terminal interface with smart session management:

• Auto session titles: Sessions automatically titled based on first message using smol model
• Welcome screen: Logo, tips, recent sessions with selection
• Powerline footer: Model, cwd, git branch/status, token usage, context %
• LSP status: Shows which language servers are active and ready
• Hotkeys: ? displays shortcuts when editor empty
• Persistent prompt history: SQLite-backed with Ctrl+R search across sessions
• Grouped tool display: Consecutive Read calls shown in compact tree view
• Emergency terminal restore: Crash handlers prevent terminal corruption

+ Edit Fuzzy Matching

Handles whitespace and indentation variance automatically:

• High-confidence fuzzy matching for oldText in edit operations
• Fixes the #1 pain point: edits failing due to invisible whitespace differences
• Configurable via edit.fuzzyMatch setting (enabled by default)

+ Native Engine (Rust N-API)

~7,500 lines of Rust compiled to a platform-tagged N-API addon, providing performance-critical operations without shelling out to external commands:

Module	Lines	What it does	Powered by
grep	~1,300	Regex search over files and in-memory content, parallel/sequential modes, glob/type filtering, context lines, fuzzy find for autocomplete	grep-regex, grep-searcher, grep-matcher (ripgrep internals)
shell	~1,025	Embedded bash execution with persistent sessions, streaming output, timeout/abort, custom builtins	brush-shell (vendored)
text	~1,280	ANSI-aware visible width, truncation with ellipsis, column slicing, text wrapping that preserves SGR codes across line breaks — all UTF-16 optimized	unicode-width, unicode-segmentation
keys	~1,300	Kitty keyboard protocol parser with legacy xterm/VT100 fallback, modifier support, PHF perfect-hash lookup	phf
highlight	~475	Syntax highlighting with 11 semantic color categories, 30+ language aliases	syntect
glob	~340	Filesystem discovery with glob patterns, type filtering, mtime sorting, .gitignore respect	ignore, globset (ripgrep internals)
task	~350	Blocking work scheduler on libuv thread pool, cooperative/external cancellation, timeout, profiling hooks	tokio, napi
ps	~290	Cross-platform process tree kill and descendant listing — /proc on Linux, libproc on macOS, CreateToolhelp32Snapshot on Windows	libc
prof	~250	Always-on circular buffer profiler with folded-stack output and optional SVG flamegraph generation	inferno
system_info	~170	Distro, kernel, CPU, disk usage without shelling out	sysinfo
image	~150	Decode/encode PNG/JPEG/WebP/GIF, resize with 5 sampling filters	image
clipboard	~95	Text copy and image read from system clipboard — no xclip/pbcopy needed	arboard
html	~50	HTML-to-Markdown conversion with optional content cleaning	html-to-markdown-rs

Supported platforms: linux-x64, linux-arm64, darwin-x64, darwin-arm64, win32-x64.

... and many more

• omp config subcommand: Manage settings from CLI (list, get, set, reset, path)
• omp setup subcommand: Install optional dependencies (e.g., omp setup python for Jupyter kernel)
• omp stats subcommand: Local observability dashboard for AI usage (requests, cost, cache rate, tokens/s)
• xhigh thinking level: Extended reasoning for Anthropic models with increased token budgets
• Background mode: /background detaches UI and continues agent execution
• Completion notifications: Configurable bell/OSC99/OSC9 when agent finishes
• 65+ built-in themes: Catppuccin, Dracula, Nord, Gruvbox, Tokyo Night, and material variants
• Auto environment detection: OS, distro, kernel, CPU, GPU, shell, terminal, DE in system prompt
• Git context: System prompt includes branch, status, recent commits
• Bun runtime: Native TypeScript execution, faster startup, all packages migrated
• Centralized file logging: Debug logs with daily rotation to ~/.omp/logs/
• Bash interceptor: Optionally block shell commands that have dedicated tools
• @file auto-read: Type @path/to/file in prompts to inject file contents inline
• Additional tools: AST (structural code analysis), Replace (find & replace across files)

---

Packages

Package	Description
@oh-my-pi/pi-ai	Multi-provider LLM client (Anthropic, OpenAI, Gemini, Bedrock, Cursor, Codex, Copilot)
@oh-my-pi/pi-agent-core	Agent runtime with tool calling and state management
@oh-my-pi/pi-coding-agent	Interactive coding agent CLI
@oh-my-pi/pi-tui	Terminal UI library with differential rendering
@oh-my-pi/pi-natives	N-API bindings for grep, shell, image, text, syntax highlighting, and more
@oh-my-pi/omp-stats	Local observability dashboard for AI usage statistics

Rust Crates

Crate	Description
pi-natives	N-API native addon — 13 modules, ~7,500 lines of Rust (see feature section above)
brush-core-vendored	Vendored fork of brush-shell for embedded bash execution
brush-builtins-vendored	Vendored bash builtins (cd, echo, test, printf, read, export, etc.)

---

License

MIT - Original work copyright Mario Zechner