Skip to content
Get packs

Guide · Open source

How to use oh-my-pi: install, run and debug with omp

Updated · written with AI from the project's own documentation and checked against our catalogue data

oh-my-pi (command name omp) is an open-source coding agent you run from the command line. It lets an AI model read, search and edit code in your project, and the README says it adds language server, debugger and subagent features on top of a fork of the Pi coding agent. This guide shows you how to install it, enable shell completions and understand what its main features do, so you can decide whether it fits your workflow.

ompcan1357/oh-my-pi · ★ 37.5k · MIT

Quick start

  1. 1Check Bun. Confirm you have bun 1.4.4 or newer installed before the recommended install.
  2. 2Install omp. Run the Bun global install command for @oh-my-pi/pi-coding-agent, or use Homebrew or the install script instead.
  3. 3Enable completions. Add the eval line for your shell, or write the fish script to your completions folder.
  4. 4Open a project. Change into the codebase you want the agent to work on, then start omp from that directory.
  5. 5Try a small task. Ask for a simple read or edit first to see how the agent uses its tools.
  6. 6Explore advanced features. Read the linked LSP and Agent Hub docs when you want language servers, debugging or subagents.

What you need before installing omp

The recommended install method uses Bun. The README lists bun 1.4.4 or newer as the requirement for that route. The README also lists macOS, Linux and Windows as supported platforms for the install scripts.

omp is a developer tool that works in a terminal and on code. It is not a graphical editor, and the README describes it as a terminal agent rather than an IDE replacement.

  • bun 1.4.4 or newer (for the recommended install)
  • A terminal on macOS, Linux or Windows
  • A project codebase you want the agent to work on

Install omp on macOS, Linux or Windows

The README gives several install routes. Pick the one that matches the tools you already have. Bun is the recommended route.

  • Bun (recommended): install the package globally with Bun.
  • Homebrew: use the can1357 tap on macOS or Linux.
  • Install script on macOS or Linux: fetches the install script from omp.sh.
  • Windows (PowerShell): use the PowerShell install script from omp.sh.
  • Nix or mise: the README also documents these routes.
bun install -g @oh-my-pi/pi-coding-agent

Install with Homebrew or the install script

If you do not use Bun, the README lists Homebrew and a shell script. The script installs omp on macOS or Linux. If Bun is not usable, or you pass the --binary flag, the script downloads a prebuilt binary and checks its SHA-256 before installing it.

On Alpine Linux with musl, the README says the prebuilt binary needs libstdc++ and libgcc, which stock Alpine does not include. Install them first.

  • Homebrew route: brew install can1357/tap/omp
  • Script route: curl -fsSL https://omp.sh/install | sh
  • Alpine: install libstdc++ and libgcc before running the binary
brew install can1357/tap/omp curl -fsSL https://omp.sh/install | sh

Turn on shell completions

omp generates its own completion scripts for bash, zsh and fish from its live command and flag metadata. Subcommands, flags and enum values complete statically. Model names for flags such as --model, --smol, --slow and --plan are resolved against the bundled model catalog, and --resume resolves against your saved sessions.

Add the line for your shell to its config file, then open a new shell.

  • zsh: add the eval line to ~/.zshrc
  • bash: add the eval line to ~/.bashrc
  • fish: write the output into ~/.config/fish/completions/omp.fish
eval "$(omp completions zsh)" eval "$(omp completions bash)" omp completions fish > ~/.config/fish/completions/omp.fish

Use the features that set omp apart

The README lists several features beyond basic code editing. Each one is documented in the project's own docs, so check those for setup details.

Language server support: the agent uses LSP operations, and the README says the call goes through workspace/willRenameFiles so imports update before a file moves. Debugger support: the README says the agent can attach lldb, dlv or debugpy to native, Go and Python programs. Subagents: the task tool splits a job across isolated workers and returns schema-validated results. Alt+A opens Agent Hub to watch the fan-out.

  • Language server (LSP): renames and file moves update references.
  • Debugger: drive lldb, dlv or debugpy from the agent.
  • Subagents: task runs parallel workers in isolated worktrees.
  • Stream rules: a matching rule can interrupt the model and inject a reminder mid-output.
  • Code execution: persistent Python and a Bun worker, each able to call the agent's tools.

What people use it for

  • Asking the agent to read, search and edit code in a project from the terminal.
  • Renaming a symbol so that imports and re-exports update across files.
  • Having the agent attach a debugger to a crashing native binary and inspect the stack frame.
  • Splitting a large refactor across parallel subagents and collecting typed results.
  • Using one tool across several model providers, since the README claims 60+ providers.

Frequently asked questions

Is oh-my-pi free?

The README states the project is MIT licensed. The MIT licence allows free use, modification and redistribution of the source. Check the LICENSE file in the repository for the full terms.

How do I install oh-my-pi?

The recommended method is bun install -g @oh-my-pi/pi-coding-agent, which needs bun 1.4.4 or newer. The README also documents Homebrew, a curl install script for macOS and Linux, and a PowerShell script for Windows.

What do I need to run omp?

The README lists bun 1.4.4 or newer for the recommended install. On Alpine Linux, the prebuilt musl binary also needs libstdc++ and libgcc installed first.

Is oh-my-pi an IDE replacement?

No. The README describes it as a terminal agent rather than an IDE replacement, and it is not a graphical editor. It adds language server and debugger features to a terminal workflow.

What is the difference between oh-my-pi and Pi?

oh-my-pi is a fork of the Pi coding agent by Mario Zechner. The README says omp adds features such as LSP support, debugger integration and subagents on top of Pi.

Is oh-my-pi stable enough for a team?

The README shows a v18.x release and says pull request policy is on trial, so it does not promise a long-term support release. Teams that need a stable, long-term-supported tool should look at other options.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

oh-my-pi suits developers who want an AI agent working in a terminal on their own code, especially if they use several model providers or debug native, Go or Python programs. It is not a good fit for non-programmers, people who want a graphical editor, or teams that need a stable, long-term-supported release. For those, consider comparable projects such as Aider, Claude Code or OpenHands.

Install options & downloads