Split View: Oh My OpenCode 사용법 — OpenCode를 멀티 에이전트 팀으로

How to Use Oh My OpenCode — Turn OpenCode into a Multi-Agent Team

• Overview
  • Why async subagents matter
• 1. Prerequisite — Install and Use OpenCode
  • 1.1 Install
  • 1.2 Run it in a project
  • 1.3 Connecting OpenRouter, for example
  • 1.4 The habit of separating Plan and Build mode
• 2. Installing Oh My OpenCode
  • 2.1 Interactive install
  • 2.2 Non-interactive install (for CI / agents)
  • 2.3 Verifying the install
  • 2.4 Caveats you must know
• 3. Configuration — Per-Agent and Per-Category Model Overrides
  • 3.1 Config file locations
  • 3.2 Model override example
  • 3.3 Precedence of agent vs category overrides
  • 3.4 Sharing config in a team repository
• 4. The Multi-Agent Team — The Agent Roster
  • 4.1 The safety of read-only specialists
• 5. Running Work with ultrawork
  • 5.1 The trigger keyword
  • 5.2 Plan-first flow
  • 5.3 Category routing
  • 5.4 Startup overhead
  • 5.5 A typical work flow
• 6. Cost Safety — Do Not Skip This
  • 6.1 An incident that actually happened
  • 6.2 Defend with concurrency limits
  • 6.3 Other safety habits
  • 6.4 A pre-flight check before big work
• 7. When to Use It vs Vanilla OpenCode
  • 7.1 A decision checklist
  • 7.2 The whole guide at a glance
• References

Overview

As terminal-based AI coding agents multiply, the game is shifting from wrangling a single agent to running a whole team of them. Oh My OpenCode is the tool that builds that team. Its site is ohmyopencode.com, its GitHub repository is opensoft/oh-my-opencode, and its npm package is oh-my-opencode.

Oh My OpenCode is not a standalone agent. It is an opinionated plugin and orchestration layer that sits on top of OpenCode. OpenCode is the open-source terminal AI coding agent shipped at opencode.ai, and it is the prerequisite for everything here. On top of it, Oh My OpenCode adds:

• Async subagents that behave like Claude Code
• A curated roster of specialized agents, each mapped to an appropriate model
• A curated set of MCP servers
• Bundled LSP/AST tooling
• A "Claude Code compatible" layer

In one sentence: it is a virtual AI dev team living in your terminal. A coordinator plans, workers write code, and specialists review architecture and dig through docs. This guide walks from OpenCode basics through installing and configuring Oh My OpenCode, assembling the multi-agent team, running real work, and the cost safety you absolutely need to know.

For the record, there is also a sibling project by a different author called oh-my-openagent (also known as lazycodex). The names are close enough to cause confusion, so this guide notes it exists in one sentence and then stays strictly focused on oh-my-opencode.

Why async subagents matter

Traditional coding agents mostly moved sequentially inside a single conversation: read a file, edit it, move to the next. That is fine for small changes, but it becomes a bottleneck on large work that has to inspect dozens of files at once. Async subagents break that bottleneck. The main agent spins up several subagents at the same time, each handling a different file or a different angle in parallel.

Oh My OpenCode reproduces this pattern, popularized by Claude Code, on top of OpenCode. The coordinator holds the big picture and hands off codebase search to Explore, documentation research to Librarian, and architecture judgment to Oracle. Each subagent finishes only its slice and returns the result to the coordinator, so the tool takes over the juggling a person used to do by hand across many terminal tabs. The rest of this guide is about actually driving that team.

1. Prerequisite — Install and Use OpenCode

Before you touch Oh My OpenCode, install OpenCode and get comfortable with it. Nothing here works without OpenCode underneath.

1.1 Install

The simplest path is the official install script.

curl -fsSL https://opencode.ai/install | bash

If you prefer npm or Homebrew, these work too.

npm i -g opencode-ai

brew install anomalyco/tap/opencode

1.2 Run it in a project

Once installed, move into the project directory you want to work in and launch it.

cd my-project
opencode

That opens the terminal UI (TUI). On your first run, learn these commands first.

• /init scans the repository and writes an AGENTS.md file. It becomes the reference document agents use to understand your project structure and conventions.
• /connect adds a model provider. Pick OpenRouter, OpenAI, Anthropic, a local model, or whatever you like, and paste the API key when prompted.
• Tab toggles between Plan and Build mode. Handy for planning first and moving to execution afterward.
• @ fuzzy-finds files. It lets you quickly pull files into context.
• /share, /undo, /redo share the session, undo, and redo. Lifesavers when you slip.

1.3 Connecting OpenRouter, for example

Running /connect shows a list of providers. Select OpenRouter and it asks for an API key; paste the one you generated at openrouter.ai. OpenRouter gives you access to many models through a single key, which is especially convenient when experimenting with the per-agent model mapping covered later. Once connected, you can pick a model right inside the TUI.

1.4 The habit of separating Plan and Build mode

The two modes you toggle with Tab are not a mere UI switch; they are a difference in working posture. Plan mode makes the agent propose what it will do and how, without changing code yet. Build mode actually edits files and executes. Until you are comfortable, prefer confirming the approach in Plan mode and moving to Build mode once the direction looks right. That single habit sharply reduces incidents like "the agent touched the wrong files." The plan-first flow of Oh My OpenCode covered later is, in the end, an expanded version of these two modes.

2. Installing Oh My OpenCode

Once OpenCode feels natural, it is time to assemble the team. Install Oh My OpenCode from your project root; it needs Bun or npx.

2.1 Interactive install

The standard path is running the installer with bunx.

bunx oh-my-opencode install

This launches an interactive TUI. There you choose which agents to use and which tools and MCPs to wire up, step by step, and it handles the wiring for you. If this is your first time, prefer the interactive path.

2.2 Non-interactive install (for CI / agents)

If a CI pipeline or another agent has to run this automatically, you can specify everything with flags and skip the interactive UI.

bunx oh-my-opencode install --no-tui \
  --claude=<yes|no|max20> --openai=<yes|no> \
  --gemini=<yes|no> --copilot=<yes|no>

Each flag decides which provider gets wired in. For example, --claude=max20 means wiring in the Claude family at a higher tier, and you turn off providers you do not need with no.

2.3 Verifying the install

Once installation finishes, check that the project now has a .opencode/ directory and the related config. When you relaunch OpenCode afterward, the TUI comes up with the agents, tools, and MCPs that Oh My OpenCode wired up already loaded. If you do not see the agents, the first things to recheck are whether you accidentally tried a global install and whether you ran from the project root. Most early problems come from getting the run location or the package name wrong.

2.4 Caveats you must know

There are a few common mistakes around installation. Let us state them plainly.

• Global install is not supported. npm i -g and bun add -g are not supported paths. You must run it from the project root with bunx.
• The omo package on npm is a completely different, unrelated package. Running bunx omo runs the wrong thing, so never use it.
• Do not confuse it with the sibling project oh-my-openagent (lazycodex) mentioned above. The name is similar, but it is not the subject of this guide.

3. Configuration — Per-Agent and Per-Category Model Overrides

The real power of Oh My OpenCode lives in its configuration, because you can finely control which agent uses which model.

3.1 Config file locations

The config file can live in one of two places.

• Per-project: .opencode/oh-my-opencode.jsonc
• Per-user: ~/.config/opencode/oh-my-opencode.json

The per-project config applies only to that repository, while the per-user config applies to all projects. For a team repository, committing the per-project file is better for reproducibility.

3.2 Model override example

You can change models per agent and per category. JSONC allows comments, so you can leave your intent right inside the file.

{
  "agents": {
    "explore": { "model": "ollama/qwen2.5-coder:7b" },
    "oracle": { "model": "openai/gpt-5.4" }
  },
  "categories": {
    "quick": { "model": "ollama/qwen2.5-coder:7b" },
    "deep": { "model": "openai/gpt-5.3-codex" }
  }
}

This example shows two axes at once. The agents block hands a cheap local model to a specific agent (for example Explore, which sweeps the codebase quickly) and assigns a stronger model to Oracle, the architecture consultant. The categories block groups work by nature, routing light, frequent quick tasks to a local model and heavy deep tasks to a codex-class model. The category section later expands on this idea.

3.3 Precedence of agent vs category overrides

A common question is which wins when the model you set on an agent conflicts with the model you set on a category. Conceptually it lines up like this. A category is the broad rule that decides which model a dynamically spawned agent (for example Sisyphus-Junior) inherits based on the type of work. A per-agent setting is the narrow rule that attaches directly to a specific, named agent (for example Oracle or Explore). So in practice, keeping your clearly named standing agents in agents and your work-type-driven executors in categories splits the roles cleanly and keeps the config readable.

3.4 Sharing config in a team repository

Committing the per-project .opencode/oh-my-opencode.jsonc to the repository means everyone on the team works with the same agent-to-model mapping. That reduces reproducibility problems like "it ran fine on a cheap model locally but jumped to an expensive one in a teammate's environment." Do not, however, put secrets such as API keys in this file. Manage keys through the /connect flow seen earlier or per-provider environment variables, and leave only policy — model choices and concurrency limits — in the config file.

4. The Multi-Agent Team — The Agent Roster

Oh My OpenCode ships a roster of agents with defined roles. Each agent has a name, a responsibility, and a recommended model. The table below groups them by role.

The key to reading this roster is "who does what, and at what cost." Orchestrators and planners control the overall flow, workers actually produce code, and specialists are read-only or tool-restricted subagents that handle one narrow job. For example, there is no reason to attach an expensive model to the Librarian that digs through docs or the Explore that searches the codebase, while the Hephaestus that writes code deeply and autonomously does need a strong model.

When mapping the roster to a real model budget, it helps to think along roughly these principles.

• Orchestrators (Sisyphus, Atlas): they coordinate the whole, so a stronger model with good judgment pays off. Respect the defaults, but if the budget is tight, lower Atlas first.
• Planners (Prometheus, Metis, Momus): plan quality drives the outcome, so avoid overly cheap models here. Remember that Metis runs at a higher temperature to find gaps.
• Workers (Hephaestus, Sisyphus-Junior): directly tied to actual implementation quality. Give Hephaestus a codex-class model, and let Sisyphus-Junior inherit an appropriate model through its category.
• Specialists (Oracle, Librarian, Explore, Multimodal Looker): the roles vary widely. It is cost-efficient to assign strong models to Oracle and Multimodal Looker, and cheap, fast models to Librarian and Explore.

4.1 The safety of read-only specialists

That the specialist group is read-only or tool-restricted is not a mere limitation but a safety mechanism by design. When Oracle diagnoses architecture or Explore sweeps the code, tying them so they cannot edit files directly eliminates, at the root, the accident of code changing unintentionally during consultation. Actual changes go only to workers like Hephaestus or Sisyphus-Junior, while specialists are confined to providing advice and information. Thanks to this structure, even when many agents run in parallel, the set of actors that write files narrows to a small number of workers, which makes the whole thing easier to control.

5. Running Work with ultrawork

You have an agent team, but simply typing a prompt does not automatically put it to work. Multi-agent delegation has to be triggered explicitly.

5.1 The trigger keyword

Multi-agent delegation fires when you include the keyword ultrawork (prefix ulw) in your prompt. It is not automatic. In other words, an ordinary prompt is handled by a single agent, and mobilizing the whole team means deliberately adding ultrawork (or ulw).

5.2 Plan-first flow

The heavier the work, the more it pays to plan before executing. Launch Prometheus with Tab or /start-work, and this planner interviews you to nail down the scope clearly. Running parallel execution while the scope is still fuzzy lets subagents sprint off in different directions, so for large work it is safer to keep the plan then execute order.

5.3 Category routing

Delegated tasks route through categories. Each category maps to a recommended model and a fallback chain. The categories are:

• visual-engineering
• artistry
• ultrabrain
• deep
• unspecified-high
• unspecified-low
• quick
• writing

Which category a task is classified into determines which model gets attached. As shown in section 3, overriding models per category lets you tune cost and performance to the nature of the work.

5.4 Startup overhead

One practical caveat: multi-agent orchestration carries real startup overhead. Roughly 15,000 to 25,000 tokens are consumed before actual work begins. Paying that overhead on a small task is a loss, so judgment about when to mobilize the team matters. The final section sums up that judgment.

5.5 A typical work flow

Stitching the previous pieces together, the standard flow for large work looks like this.

1. Launch Prometheus with Tab or /start-work to plan. Answer the interview seriously to narrow the scope.
2. If needed, Metis finds gaps in the plan, and Momus approves or rejects it.
3. Once the plan passes, add ultrawork (or ulw) to your prompt to fire multi-agent execution.
4. Sisyphus splits the work by category and delegates. Explore handles search, Librarian handles docs, Hephaestus handles deep implementation, and Oracle handles architecture judgment.
5. As each subagent's result flows back to the coordinator, review the final changes and, if needed, roll back with /undo.

Internalizing this flow keeps you away from risky habits like "straight to ultrawork with no plan." Even a short planning step that pins down the scope is the cheapest insurance against parallel execution running off in the wrong direction.

6. Cost Safety — Do Not Skip This

This part deserves honesty. A multi-agent tool is as convenient as it is capable of letting cost run out of control.

6.1 An incident that actually happened

A confirmed early bug caused large, unexpected spend. One user reported being charged about 438 dollars in a single afternoon. The causes were silent model routing and a runaway loop. In other words, work drifted onto an expensive model the user never intended, and it repeated without stopping, snowballing the cost.

6.2 Defend with concurrency limits

The most practical defense is capping provider concurrency in the config. As below, you can tie down how many concurrent runs a given provider is allowed.

{ "background_task": { "providerConcurrency": { "google": 1 } } }

This setting limits the google provider to a single concurrent run in background tasks. Even if a runaway loop happens, parallel calls are suppressed, which limits the damage.

6.3 Other safety habits

Beyond concurrency limits, make these habits.

• Audit your category and model configs. Know explicitly which work routes to which model.
• Assign cheaper models first to subagents that get called in volume. Frequent roles like Librarian or Explore are prime examples.
• Check your provider's spend dashboard regularly. Catching anomalies early is the best defense.

6.4 A pre-flight check before big work

Cost incidents usually blow up on "a big task you kicked off without thinking." So before firing sizable work with ultrawork, it pays to build a habit of eyeballing three things. First, re-read which model each category maps to in your config. Second, confirm a concurrency limit is in place. Third, if the currently attached provider is a paid tier, sketch a rough expected cost in your head. That 30-second check is the most realistic barrier against incidents like the roughly 438 dollars in an afternoon seen earlier.

7. When to Use It vs Vanilla OpenCode

Finally, the most practical question. Using Oh My OpenCode for every task is not the right answer.

Oh My OpenCode shines on work that is large, spans many files, and breaks into multiple phases. Flows like research → plan → implement, where you can capitalize on parallel subagents, are exactly the fit. Here the team is an obvious power multiplier.

Conversely, for small tasks that fit in a single context window, or when running budget models, vanilla OpenCode is the better call. Budget models do better with one clean prompt. Mobilizing multiple agents for such work only makes you pay the startup overhead seen earlier, which is pure waste.

To sum up: Oh My OpenCode is a powerful power multiplier for the right work and mere overhead for the wrong work. Choose based on the size of the work, the number of phases, and the gain from parallelization.

7.1 A decision checklist

When you are on the fence, answer these questions. The more "yes" answers, the more it leans toward Oh My OpenCode.

• Does this work touch three or more files?
• Does it split into phases of different character, like research, plan, and implement?
• Are there sub-tasks independent enough to run in parallel?
• Do you have the budget headroom to attach a strong model?

Conversely, if "this finishes in one prompt," "I only run a budget local model," or "one or two files of context is enough" describes your case, vanilla OpenCode is the right fit. The criterion for choosing a tool is not taste but the shape of the work.

7.2 The whole guide at a glance

Restated in order, the core of this guide is:

• Install OpenCode first and get comfortable with /init, /connect, and Tab.
• Wire up the team from the project root with bunx oh-my-opencode install. No global install and no bunx omo.
• Tune per-agent and per-category models in .opencode/oh-my-opencode.jsonc.
• For large work, plan with Tab or /start-work, then execute with ultrawork.
• Set concurrency limits, audit your category-to-model mapping, and check the spend dashboard regularly.
• Use vanilla OpenCode for small tasks or budget models.

Follow these six lines and you capture most of Oh My OpenCode's upside while avoiding most of its risk.

References

• Oh My OpenCode — https://ohmyopencode.com
• GitHub — https://github.com/opensoft/oh-my-opencode
• npm — https://www.npmjs.com/package/oh-my-opencode
• OpenCode docs — https://opencode.ai/docs