Oh My OpenCode Installation Guide: Easy Setup for Beginners

If you’ve tried installing OpenCode, you might wonder: “The basic features are great, but how do people build that so-called multi‑agent development environment?”

That’s exactly the gap the Oh My OpenCode extension fills.
However, for beginner developers, this plugin might feel a bit unfamiliar:

• Where should you keep the configuration file?
• Which agents come pre‑installed?
• How do you structure the JSON template?
• How do models, tools, and rules connect with each other?

This guide breaks down the entire process — from installation to agent linking and rule application — with clear practical examples.

1. Installation setup

Oh My OpenCode works as a plugin for OpenCode.
You can install it with a single command:

opencode plugins install oh-my-opencode

To confirm the installation, run:

opencode plugins list

If you see oh-my-opencode listed, everything’s set up correctly.

2. Where to place your configuration file

There are two types of settings:

✔ Project-level configuration

.yourproject/
  └── .opencode/
         └── oh-my-opencode.json

Use this if you want each project to have different rules or agent setups.

✔ User-wide (global) configuration

~/.config/opencode/oh-my-opencode.json

For beginners, the easiest and most maintainable approach is to start with the global config and override it per project when needed.

3. Basic JSON template

Copy the following JSON and place it in
~/.config/opencode/oh-my-opencode.json
to enable essential features immediately:

{
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json",

  "agents": {
    "oracle": {
      "model": "openai/gpt-5.2",
      "instructions": "You act as an architect-level reviewer. Explain your reasoning clearly."
    },
    "explore": {
      "model": "xai/grok-code",
      "instructions": "Fast code search and browsing."
    },
    "frontend": {
      "model": "google/gemini-3-pro-preview",
      "instructions": "Help with UI/UX and frontend code."
    },
    "document": {
      "model": "google/gemini-3-pro-preview",
      "instructions": "Write clear documentation for code and APIs."
    }
  },

  "rules": {
    "enabled": true
  },

  "hooks": {
    "keyword-detector": true,
    "auto-compact": true,
    "todo-enforcer": true
  }
}

This template is designed to be beginner-friendly, with:

• Four clearly defined agent roles.
• Automated rule application enabled.
• Auto‑summary (auto‑compact) and to‑do reminder (todo‑enforcer) turned on.
• Keyword detector responding to natural phrases like “refactor” or “tidy this up.”

4. Customizing agents — modify or create new roles

The real power of Oh My OpenCode lies in job‑specific, customizable agents tailored to your project.

Example: add a “Model Specialist” for a Django project

"agents": {
  "model-specialist": {
    "model": "anthropic/claude-4-5-sonnet",
    "instructions": "You focus on database models, migrations, and schema design. Suggest improvements and ensure consistency."
  }
}

Then, in the TUI, you can call it like:

@model-specialist Please review the model structure.

Tip

Start with just 1–2 agents. As you get comfortable, expand up to 5–6 agents.

5. Using “Rules” — embedding project context into the AI

Unlike ordinary terminal AI IDE , Oh My OpenCode’s rule system lets the AI automatically learn your project’s principles and conventions.

Example: add a rule that applies only inside src/auth
Create this file:

src/auth/AGENTS.md

with content such as:

# Authentication rules
- Always handle tokens with secure patterns.
- Never store raw passwords.
- Follow the existing session management flow.

Whenever the AI interacts with files under auth/, it will automatically refer to these rules.

6. Understanding Hooks (automation features)

Hooks automatically manage how and when your AI coding agents operate.

There are three essentials every beginner should know:

✔ keyword-detector

• Detects phrases like “refactor,” “find it,” or “summarize.”
• Automatically switches to analysis or structured mode.

✔ auto-compact

• Summarizes long conversations while maintaining context — crucial in terminal environments.
• .

✔ todo-enforcer

• When the AI finds TODOs in your code, it reminds you to finish them.

Together, these features prevent beginners from “breaking the workflow.”

7. Integrating MCP (external tools) — optional but powerful

This step is optional, but using it later can be extremely beneficial.

Example: enable web search MCP

"mcp": {
  "websearch_exa": true
}

Then you can ask naturally:

“Find GitHub repos with code patterns similar to this one.”

8. Recommended setup order for beginners

To minimize trial and error, follow this sequence:

1. Create the global config. (~/.config/opencode/oh-my-opencode.json)
2. Register 3–4 base agents (@oracle, @explore, @document, etc.).
3. Enable keyword-detector and auto-compact.
4. Create a single AGENTS.md file at the project root.
5. Add extra AGENTS.md files only for core folders (e.g. auth, billing).
6. Integrate MCP tools only when necessary.

With these six steps, most beginner‑to‑intermediate setups will run stably.

9. Practical examples — sample scenarios

Once configuration is complete, you can ask questions like:

@oracle The src directory feels too heavy. Suggest a refactor plan based on module responsibilities.

or

@document Summarize the new feature for the team docs.

or

@explore Find all references where this function is called.

Even beginners will discover many tasks they can now delegate confidently to AI agents.

Organize

In this guide, we covered how to install and configure Oh My OpenCode in a way that even beginners can follow easily.

Key takeaways:

• Installation takes a single command.
• Use global → project override config pattern for easy maintenance.
• Structure your agents around roles, like an organization.
• AGENTS.md files embed project context into the AI’s reasoning.
• Hooks help automate workflows and protect beginners from missteps.

In the next article, we’ll explore multi‑agent workflow automation (Ultrawork) with real-world examples — the point where your OpenCode development experience seriously levels up.