跪拜 Guibai
← Back to the summary

oh-my-pi: An Engineering-Grade AI Coding Tool That Runs 8 Agents in Parallel

Foreword

I had a multi-module project that needed batch refactoring. Using a single agent for this kind of work before had been a disaster: after changing an interface, references in other modules weren't synced, and indentation got messed up. The most infuriating time was when it directly overwrote code I had manually changed locally, and I could only recover it through git.

Someone mentioned oh-my-pi (omp), saying it's not in the same league as ordinary conversational tools. Installation was simple, just a single curl command. I threw my entire refactoring task into it.

After half a month, AI hallucinations were significantly reduced, and accuracy clearly improved.

1. First Task Submission: All Work Enters Through a Single Main Agent Portal

My habit with conversational tools is to name names first: you change this file, you go check that interface. I tried the same approach with omp initially, wanting to directly call on a specific sub-agent to work. After a couple of tries, I found there was no such entry point. In omp's architecture, the Main Agent is the root agent and the sole entry point: you only talk to it. It is responsible for decomposing requirements, dispatching sub-agents, and consolidating results. All sub-agents are spawned by the Main Agent, and tasks are uniformly closed out by it. The user never needs to face any sub-agent directly.

At the time, I felt it added an extra layer. Only after getting used to it did I understand the benefit of a single entry point: how requirements are broken down, who is dispatched, and how results are merged are all decided at the Main Agent level. Responsibility is clear, avoiding a situation where multiple agents work in silos with no one ultimately accountable.

Over half a month, I cared about only four things: AI hallucinations were drastically reduced and accuracy improved significantly; multiple models could be configured, with complex coding and lightweight research automatically routed; task execution was very smooth, with a clear overview of change lists, time spent, and cost; execution results were structurally displayed, built-in tools were powerful, and global search produced results in seconds via the built-in ripgrep.

There are mechanisms backing these four promises: hallucination reduction relies on multi-layered Agent verification overlaid with real debugging data, and accuracy is underpinned by LSP syntax verification. At the time, I thought it was just a different way of phrasing things. Only later did I gradually understand the processes behind these mechanisms.

2. First Parallel Refactoring: Seeing the Division of Labor Among 8 Roles

Before submitting the task, I assumed it would change all the files in one go like a single agent. Instead, it didn't recklessly change everything itself but assigned work by role. I watched the process closely and figured out the division of labor among the 8 built-in sub-agents:

scout: Code Scout

At the start of a task, the scout always goes out first. It traverses the project directory, maps out the file structure, tallies dependencies, and locates the target code scope. After a round of running, it tells me where the change boundaries are. It doesn't write code; it only delineates the scope for subsequent tasks to avoid changing the wrong areas.

researcher: Research Analyst

When dealing with an unfamiliar third-party API, the researcher first searches online for documentation, API usage, open-source solutions, vulnerability information, and technical specifications, bringing back the facts. Research conclusions are returned as structured results, without speculation.

planner: Solution Planner

Once the facts are gathered, the planner decomposes the requirements into a step-by-step refactoring plan, a file modification checklist, and risk points. The plan is specific down to the file level, not just a vague phrase like "optimize the code."

worker: Execution Worker

Only after the plan is confirmed does the worker step in, actually writing code, modifying files, writing unit tests, and executing shell scripts. All modifications are done in an isolated workspace, without directly polluting the main repository.

reviewer: Code Reviewer

After the worker delivers, the reviewer self-checks for code standards, logic flaws, performance issues, and LSP syntax errors, finally outputting a clear review grade.

context-builder: Context Builder

When tasks run long and involve many dialogue turns, the context-builder compresses and cleans project context within long sessions, reducing token waste. Its value is straightforward: preventing long-session AI amnesia, where it forgets earlier parts later on.

oracle: Dual-Verification Reviewer

Passing the reviewer isn't the end. The oracle uses a second, independent perspective to re-audit the changes, equivalent to a dual-person cross-review. An extra layer of independent review reduces AI hallucinations by another notch.

delegate: General Delegate Agent

Occasional scattered, non-standard custom tasks are handed to the delegate, without occupying the slots of specialized roles like scout or reviewer.

Eight roles, each with its own duty. This division-of-labor chart is omp's departmental structure: when a task comes in, the Main Agent assigns work by role, with responsibility assigned to the individual.

3. Once It Was Running: Several Worries Were Overturned One by One

1. Fully Isolated Workspaces Prevent Conflicts

With 8 sub-agents working in parallel, my first reaction was that they would step on each other's toes: what if they modify the same file simultaneously? After watching a round, I found my worry was unfounded. Each sub-agent creates an independent, isolated worktree. The underlying implementation varies by platform:

Modifications by each sub-agent are completely non-interfering, and the Main Agent merges them uniformly at the end. The problem of multiple AIs modifying the same file simultaneously causing overwrites and loss is mechanically avoided. The necessary coordination during the merge phase is all there.

2. Schema Structured Output, No Need to Parse Fluff

I also worried about how to verify its work after changes. It turns out sub-agents don't return large blocks of natural language descriptions after finishing. They are forced to output JSON structured verification data, which the main program reads directly by machine. The first time I saw the actual output, it looked like this:

{
  "modified_files": ["src/parser.ts", "src/utils/io.ts"],
  "exported_interfaces": ["parseConfig", "loadProject"],
  "elapsed_ms": 4823,
  "cost": 0.042,
  "summary": "Completed configuration parsing module refactoring, exported 2 interfaces, no breaking changes"
}

Modified file list, exported interfaces, time elapsed, invocation cost, modification summary — all right here. Automated aggregation consumes JSON directly, no need for humans to chew through long natural language texts.

3. Agents Can Communicate Directly with Each Other

There are dependencies between parallel tasks. In my case, after component A's export was complete, routing module B could then adapt. I originally thought this kind of sequencing could only be done via serial queuing. It turns out sub-agents support IRC-like point-to-point private messaging: after A's export is complete, it notifies B's routing module to adapt via IRC, and B starts work upon receiving the message. This is how coordination in complex pipelines is strung together.

4. Two Types of Orchestration Workflows

The Main Agent selects the orchestration method based on dependency relationships:

5. Extensible Cluster Swarm Mode

Later I tried Swarm: via the @oh-my-pi/swarm-extension plugin, you can orchestrate arbitrarily complex DAG multi-agent workflows using YAML. It can run persistently in the background, unattended. Suitable for automated batch engineering processing and can also be embedded into CI pipelines.

4. Value After Half a Month: Several Concrete Outcomes

1. Qualitative Leap in Large-Scale Project Refactoring Capability

That multi-module project I had, with a Monorepo structure and large-scale refactoring across many files, ran without chaos: clear division of labor, traceable, and rollback-able. Every change has an owner, and problems can be pinpointed to a specific sub-agent and commit.

2. Drastic Reduction in AI Hallucinations

Hallucination was the biggest initial worry and the area with the biggest difference before and after. Reducing hallucinations relies on a triple safety net: multi-layered Agent verification (two rounds of independent review by reviewer and oracle), real debugging data (DAP attaches a real debugger to get runtime errors), and code syntax verification (LSP as a backstop). I've actually seen each layer in action.

3. Controllable Costs

The bill after half a month was also clear: automatic model routing. Lightweight tasks like research and search automatically go to cheap models; only core coding uses high-end models. The routing rules are explicit, not just a vague claim of "smart savings."

4. Engineered Results

All changes automatically generate standardized Git atomic commit records, one-click rollback, and are Code Review friendly. During review, what you see are individual atomic commits, not a giant diff.

5. After Getting Proficient: A Few Experiences That Changed My Mind

1. Hash-Anchored Editing, No File Corruption

The biggest crash-and-burn point with a single agent before was indentation chaos, random space changes, context misalignment, and batch replacements corrupting files. omp uses hash anchoring to locate edit points. Since then, I've never encountered these issues again. The most memorable time: I manually changed a file and forgot to tell it. It directly stopped and waited for confirmation, refusing to overwrite my manually changed content. The purpose of this design is to protect valid code, preferring to stop rather than cause collateral damage.

2. LSP+AST Syntax-Level Modification

When renaming a function or variable, all project-wide references are automatically synced and updated, with import paths and cross-file dependencies batch-fixed. This isn't blind text replacement; it's semantic-level modification. Semantic understanding for mainstream languages like TS, Go, Python, and Java is very accurate.

3. Can Actually Debug Bugs, No More Guessing

The vast majority of AIs can only statically look at code and guess at problems. omp can directly call the DAP protocol to attach a real debugger: automatically set breakpoints, single-step execute, view runtime variables and call stacks, and capture crash stack traces. Previously, when troubleshooting a suspected deadlock issue, I first went through the logs twice and saw nothing. It attached the debugger, set a breakpoint, got the real runtime error data, and it was immediately clear which variable was stuck where. The troubleshooting experience for backend, embedded, and low-level Rust/Go bugs is especially noticeable.

4. Sub-Agent Parallelism + Dual-Layer Review

During multi-module refactoring, a single command dispatches scout, planning, coding, review, and re-audit sub-agents to work in parallel and isolation, each in its own independent workspace without conflict. After the Main Agent merges everything, there's a dual-layer code review, marking risks from P0 to P3 levels.

5. Silky Performance, Full Platform Support

A single Rust kernel binary, with built-in ripgrep, persistent shell sessions, and a built-in browser scraper. It doesn't repeatedly fork external commands, and global searches in large projects return results in seconds. Native support for Windows, macOS (M series), and Linux x64/ARM64 (Raspberry Pi) across all platforms. Windows doesn't need to rely on WSL. Installation is extremely simple, deployed with a single curl or PowerShell script.

6. Extreme Model Freedom

Configure 40+ large model service providers in one go: OpenAI, Claude, Gemini, Ollama local models, third-party proxies — all are welcome. Automatic task routing: complex coding uses strong code models, research and search automatically switch to low-cost lightweight models, and automatic failover degradation is supported. Running completely offline with local Ollama is no problem at all, very friendly for privacy-sensitive projects.

7. Deep Integration into Existing Development Flow

Previous Cursor configurations aren't wasted: it directly reads mainstream AI rule files like .cursor/rules and .clinerules, and configurations can be migrated directly. 32 built-in tools: Git batch operations, structured web scraping, PDF parsing, GitHub PR/Issue interaction, sandboxed Python script execution. Terminal slash command system (/plan for planning, /review for review, /branch for session branching), extremely fast once proficient.

6. Deterrents and Thresholds

The following thresholds are all real; weigh them before jumping in.

1. Steep Learning Curve, Deters Beginners

The feature set is too vast: LSP configuration, DAP debugger integration, sub-agent orchestration, model routing rules, workspace isolation, plugin extensions. Mastering the entire system takes 1-2 days. Compared to the out-of-the-box experience of claude-cli, regular Pi, or Cursor's dialog box, omp is an engineering-grade heavy tool. Pure beginners face high onboarding pressure, with many commands; without memorizing the slash commands, you can't unleash its full capabilities.

2. Pure GUI, Light-Coding Users Have Absolutely No Need

People who rely entirely on the VS Code graphical interface, only write simple scripts, or do scattered small features will find it overly complex. It is essentially a terminal-native tool, and its core use case is heavy terminal workflows.

3. Initial Configuration Is Slightly Tedious

First-time use requires configuring API Keys for various major models; some languages require locally installing the corresponding LSP server; debugging features require adapting debuggers like lldb/dlv/debugpy. Once the one-time configuration is complete, it's basically painless afterward, but the initial setup does take time.

4. Higher Resource Overhead Than Lightweight CLI Agents

When running multiple sub-agents in parallel, long session contexts, and persistent debugging sessions, memory usage will be higher; older, low-spec machines will experience slight lag during multi-tasking.

5. Average Support for Niche Languages

Support for mainstream frontend and backend languages like Go/Java/Python/Rust is perfect; LSP adaptation for niche, less common programming languages is weaker, and syntax-level modification capabilities will be discounted.

Summary

My usage pattern is now fixed: for small changes, I still do them casually by hand. For multi-file refactoring or restructuring work, I throw it to omp, but before doing so, I clearly communicate any locally manually changed files to it. Is spending two days thoroughly understanding the configuration and rules worth it? My current answer: it depends on whether you frequently have large-scale changes on your hands.

If you're also tinkering with omp or similar coding agents, how did you configure model routing and LSP adaptation? Let's chat in the comments.