AI coding agent for the terminal
Fork of badlogic/pi-mono by @mariozechner
---
## Installation
### Via Bun (recommended)
Requires [Bun](https://bun.sh) runtime:
```bash
bun install -g @oh-my-pi/pi-coding-agent
```
### Via installer script
**Linux / macOS:**
```bash
curl -fsSL https://raw.githubusercontent.com/can1357/oh-my-pi/main/scripts/install.sh | sh
```
**Windows (PowerShell):**
```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 ][`: Install a tag/commit/branch (defaults to source install)
```bash
# 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
```
```powershell
# 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](https://github.com/can1357/oh-my-pi/releases/latest).
---
## + 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 (`OMP_SMOL_MODEL`, `OMP_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
## + 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)
## ... 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](packages/ai)** | Multi-provider LLM client (Anthropic, OpenAI, Gemini, Bedrock, Cursor, Codex, Copilot) |
| **[@oh-my-pi/pi-agent-core](packages/agent)** | Agent runtime with tool calling and state management |
| **[@oh-my-pi/pi-coding-agent](packages/coding-agent)** | Interactive coding agent CLI |
| **[@oh-my-pi/pi-tui](packages/tui)** | Terminal UI library with differential rendering |
| **[@oh-my-pi/omp-stats](packages/stats)** | Local observability dashboard for AI usage statistics |
---
## License
MIT - Original work copyright Mario Zechner