oh-my-opencode 1.0.2 → 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. package/README.ko.md +193 -187
  2. package/README.md +249 -245
  3. package/dist/agents/multimodal-looker.d.ts +2 -0
  4. package/dist/agents/types.d.ts +1 -1
  5. package/dist/index.js +146 -3
  6. package/dist/tools/index.d.ts +1 -0
  7. package/dist/tools/look-at/constants.d.ts +2 -0
  8. package/dist/tools/look-at/index.d.ts +3 -0
  9. package/dist/tools/look-at/tools.d.ts +12 -0
  10. package/dist/tools/look-at/types.d.ts +4 -0
  11. package/package.json +1 -1
package/README.md CHANGED
@@ -1,71 +1,103 @@
1
- English | [한국어](README.ko.md)
1
+ [English](README.md) | [한국어](README.ko.md)
2
2
 
3
3
  ## Contents
4
4
 
5
5
  - [Oh My OpenCode](#oh-my-opencode)
6
- - [TL;DR](#tldr)
6
+ - [Skip Reading This](#skip-reading-this)
7
+ - [It's the Age of Agents](#its-the-age-of-agents)
8
+ - [10 Minutes to Unlock](#10-minutes-to-unlock)
7
9
  - [Installation](#installation)
8
- - [For LLM Agents](#for-llm-agents)
9
- - [Why OpenCode & Why Oh My OpenCode](#why-opencode--why-oh-my-opencode)
10
+ - [For Humans](#for-humans)
11
+ - [For LLM Agents](#for-llm-agents)
12
+ - [Step 1: Verify OpenCode Installation](#step-1-verify-opencode-installation)
13
+ - [Step 2: Configure oh-my-opencode Plugin](#step-2-configure-oh-my-opencode-plugin)
14
+ - [Step 3: Verify Setup](#step-3-verify-setup)
15
+ - [Step 4: Configure Authentication](#step-4-configure-authentication)
16
+ - [4.1 Anthropic (Claude)](#41-anthropic-claude)
17
+ - [4.2 Google Gemini (Antigravity OAuth)](#42-google-gemini-antigravity-oauth)
18
+ - [4.3 OpenAI (ChatGPT Plus/Pro)](#43-openai-chatgpt-pluspro)
19
+ - [4.3.1 Model Configuration](#431-model-configuration)
20
+ - [⚠️ Warning](#️-warning)
10
21
  - [Features](#features)
11
- - [Agents](#agents)
12
- - [Tools](#tools)
13
- - [Built-in LSP Tools](#built-in-lsp-tools)
14
- - [Built-in AST-Grep Tools](#built-in-ast-grep-tools)
15
- - [Grep](#grep)
16
- - [Built-in MCPs](#built-in-mcps)
17
- - [Background Task](#background-task)
18
- - [Hooks](#hooks)
19
- - [Claude Code Compatibility](#claude-code-compatibility)
20
- - [Other Features](#other-features)
22
+ - [Agents: Your Teammates](#agents-your-teammates)
23
+ - [Background Agents: Work Like a Team](#background-agents-work-like-a-team)
24
+ - [The Tools: Your Teammates Deserve Better](#the-tools-your-teammates-deserve-better)
25
+ - [Why Are You the Only One Using an IDE?](#why-are-you-the-only-one-using-an-ide)
26
+ - [Context Is All You Need](#context-is-all-you-need)
27
+ - [Be Multimodal. Save Tokens.](#be-multimodal-save-tokens)
28
+ - [I Removed Their Blockers](#i-removed-their-blockers)
29
+ - [Goodbye Claude Code. Hello Oh My OpenCode.](#goodbye-claude-code-hello-oh-my-opencode)
30
+ - [Hooks Integration](#hooks-integration)
31
+ - [Config Loaders](#config-loaders)
32
+ - [Data Storage](#data-storage)
33
+ - [Compatibility Toggles](#compatibility-toggles)
34
+ - [Not Just for the Agents](#not-just-for-the-agents)
21
35
  - [Configuration](#configuration)
36
+ - [Google Auth](#google-auth)
37
+ - [Agents](#agents)
38
+ - [MCPs](#mcps)
39
+ - [LSP](#lsp)
22
40
  - [Author's Note](#authors-note)
23
41
  - [Warnings](#warnings)
24
42
 
25
43
  # Oh My OpenCode
26
44
 
27
- Oh My OpenCode
28
-
29
45
  oMoMoMoMoMo···
30
46
 
31
- If you work in tech, you likely appreciated [Claude Code](https://www.claude.com/product/claude-code).
32
- If you are a hacker, you will fucking fall in love with [OpenCode](https://github.com/sst/opencode).
33
47
 
34
- Do you remember the first time you switched from Windows to Linux? The excitement of configuring everything just the way you wanted?
35
- In an era where that romance feels lost, OpenCode will be that project for you.
36
- If you love coding and computers, OpenCode will feel exactly like that moment you first touched Linux after years of Windows.
37
- Even if you don't, invest a little time. Boost your skills and productivity by multipliers.
48
+ [Claude Code](https://www.claude.com/product/claude-code) is great.
49
+ But if you're a hacker, you'll fall head over heels for [OpenCode](https://github.com/sst/opencode).
50
+
51
+ - Endlessly extensible. Endlessly customizable.
52
+ - Zero screen flicker.
53
+ - [LSP](https://opencode.ai/docs/lsp/), [linters, formatters](https://opencode.ai/docs/formatters/) activate automatically per file—and you can tweak everything.
54
+ - Mix and match models. **Orchestrate them by purpose.**
55
+ - Feature-rich. Beautiful. The terminal doesn't choke. High performance.
56
+
57
+ Remember the first time you switched from Windows to Linux? That rush of configuring everything exactly how you wanted?
58
+ In an age where that magic seems lost, OpenCode brings it back.
59
+ If you love coding and computers, OpenCode is that Linux-after-Windows moment.
60
+
61
+ **But here's the catch: there's a lot to learn, it's complex, and your time is expensive.**
62
+
63
+ I've fixed that.
64
+ Even if you're not a hacker, invest a few minutes. Multiply your skills and productivity.
65
+ Hand this doc to an agent and let them set it up.
38
66
 
39
- ## TL;DR
67
+ ## Skip Reading This
40
68
 
41
- - **Model Setup Required**
42
- - This plugin utilizes models from [OpenCode Zen](https://opencode.ai/docs/zen/), Google, OpenAI, and Anthropic.
43
- - For Anthropic models, use [OpenCode's built-in Claude Code Max Plan login](https://opencode.ai/docs/providers/#anthropic).
44
- - For OpenAI models (ChatGPT Plus/Pro), install the [OpenCode-OpenAI-Codex-Auth plugin](https://github.com/numman-ali/opencode-openai-codex-auth).
45
- - For Google Gemini models, enable `google_auth: true` in `oh-my-opencode.json` for **built-in Antigravity OAuth**.
46
- - For other providers, [VibeProxy (macOS Only)](https://github.com/automazeio/vibeproxy) or [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) remain available as alternatives.
47
- - **Truth be told, the rest is optional. Just install it. Once set up, no further learning is required. It simply evolves.**
48
- - **Paste this document into Claude Code, OpenCode, or Cursor, instruct it to install, and ask for assistance if needed. It just installs.**
49
- - If you are an LLM Agent, install the required plugins and dependencies, then run `opencode auth login` via tmux to assist the user with configuration.
69
+ ### It's the Age of Agents
70
+ - **Just paste this link into Claude Code / AmpCode / Factory Droid / Cursor and ask it to explain.**
71
+ - Ask why it's good, why it's not just another boilerplate setup, what actually gets better.
72
+ - If you're an LLM agent, explain to the user what becomes possible right now with this project.
73
+
74
+ ### 10 Minutes to Unlock
75
+
76
+ 1. **While Gemini 3 Pro writes the frontend as a background task, Claude Opus 4.5 handles the backend. Stuck debugging? Call GPT 5.2 for help. When the frontend reports done, verify and ship.**
77
+ 2. Need to look something up? It scours official docs, your entire codebase history, and public GitHub implementations—using not just grep but built-in LSP tools and AST-Grep.
78
+ 3. Stop worrying about context management when delegating to LLMs. I've got it covered.
79
+ - OhMyOpenCode aggressively leverages multiple agents to lighten the context load.
80
+ - **Your agent is now the dev team lead. You're the AI Manager.**
81
+ 4. It doesn't stop until the job is done.
82
+
83
+
84
+ - Throw complex, massive tasks at it.
85
+ - Drop the "ultrawork" keyword in your prompt and it handles everything automatically.
50
86
 
51
87
  ## Installation
52
88
 
53
- Add to `~/.config/opencode/opencode.json`:
54
89
 
55
- ```json
56
- {
57
- "plugin": [
58
- "oh-my-opencode"
59
- ]
60
- }
61
- ```
90
+ ### For Humans
62
91
 
63
- ## For LLM Agents
92
+ Let the LLM Agent handle the grunt work. Paste this link and ask it to install and configure.
93
+
94
+ ### For LLM Agents
64
95
 
65
96
  <details>
66
- <summary>For LLM Agents (Click to expand)</summary>
97
+ <summary>Instructions for LLM Agents (click to expand)</summary>
98
+
99
+ If you're an LLM Agent helping set up oh-my-opencode, follow these steps:
67
100
 
68
- If you are an LLM Agent helping a user set up oh-my-opencode, follow these steps:
69
101
 
70
102
  ### Step 1: Verify OpenCode Installation
71
103
 
@@ -74,11 +106,11 @@ if command -v opencode &> /dev/null; then
74
106
  echo "OpenCode $(opencode --version) is installed"
75
107
  else
76
108
  echo "OpenCode is not installed. Please install it first."
77
- echo "See: https://opencode.ai/docs"
109
+ echo "Ref: https://opencode.ai/docs"
78
110
  fi
79
111
  ```
80
112
 
81
- If OpenCode is not installed, guide the user to [OpenCode Installation Guide](https://opencode.ai/docs).
113
+ If OpenCode isn't installed, check the [OpenCode Installation Guide](https://opencode.ai/docs). To save context, spawn a subagent to handle installation and report back.
82
114
 
83
115
  ### Step 2: Configure oh-my-opencode Plugin
84
116
 
@@ -92,10 +124,10 @@ if [ -f ~/.config/opencode/opencode.json ]; then
92
124
  ~/.config/opencode/opencode.json > /tmp/oc.json && \
93
125
  mv /tmp/oc.json ~/.config/opencode/opencode.json
94
126
  else
95
- echo "Add \"oh-my-opencode\" to plugin array in ~/.config/opencode/opencode.json"
127
+ echo "Please add \"oh-my-opencode\" to the plugin array in ~/.config/opencode/opencode.json"
96
128
  fi
97
129
  else
98
- # New config
130
+ # Create new config
99
131
  echo '{"plugin":["oh-my-opencode"]}' > ~/.config/opencode/opencode.json
100
132
  fi
101
133
  ```
@@ -103,28 +135,28 @@ fi
103
135
  ### Step 3: Verify Setup
104
136
 
105
137
  ```bash
106
- opencode --version # Should be >= 1.0.132
138
+ opencode --version # Should be 1.0.132 or higher
107
139
  cat ~/.config/opencode/opencode.json # Should contain "oh-my-opencode" in plugin array
108
140
  ```
109
141
 
110
142
  ### Step 4: Configure Authentication
111
143
 
112
- Once `oh-my-opencode` is added to the plugin list, use `tmux` to assist the user with authentication setup. **It is RECOMMENDED to set up Google Auth (Step 4.2) by default.**
144
+ Once oh-my-opencode is in the plugin list, use tmux to walk the user through authentication. Complete all steps below.
113
145
 
114
146
  #### 4.1 Anthropic (Claude)
115
147
 
116
148
  ```bash
117
149
  opencode auth login
118
- # Select Provider: Anthropic
119
- # Select Login method: Claude Pro/Max
120
- # Complete OAuth flow in browser
150
+ # Provider: Select Anthropic
151
+ # Login method: Select Claude Pro/Max
152
+ # Guide user through OAuth flow in browser
153
+ # Wait for completion
154
+ # Verify success and confirm with user
121
155
  ```
122
156
 
123
- #### 4.2 Google Gemini (Built-in Antigravity OAuth)
124
-
125
- **This is the RECOMMENDED default configuration.**
157
+ #### 4.2 Google Gemini (Antigravity OAuth)
126
158
 
127
- First, proactively enable Google auth in `~/.config/opencode/oh-my-opencode.json` (or `.opencode/oh-my-opencode.json` for project-level):
159
+ First, enable Google auth in `~/.config/opencode/oh-my-opencode.json`:
128
160
 
129
161
  ```json
130
162
  {
@@ -136,9 +168,11 @@ Then authenticate:
136
168
 
137
169
  ```bash
138
170
  opencode auth login
139
- # Select Provider: Google
140
- # Select Login method: OAuth with Google (Antigravity)
141
- # Complete OAuth flow in browser
171
+ # Provider: Select Google
172
+ # Login method: Select OAuth with Google (Antigravity)
173
+ # Guide user through OAuth flow in browser
174
+ # Wait for completion
175
+ # Verify success and confirm with user
142
176
  ```
143
177
 
144
178
  #### 4.3 OpenAI (ChatGPT Plus/Pro)
@@ -154,156 +188,108 @@ First, add the opencode-openai-codex-auth plugin:
154
188
  }
155
189
  ```
156
190
 
157
- **Important**: You must also configure the full model settings in your `opencode.json`. Copy the provider/models configuration from [`config/full-opencode.json`](https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/config/full-opencode.json). See the [opencode-openai-codex-auth documentation](https://github.com/numman-ali/opencode-openai-codex-auth) for detailed setup instructions.
191
+ **Important**: The official npm package currently has a bug causing 400 errors (`"No tool call found for function call output with call_id"`). **Use the hotfix branch** until fixed. Edit `~/.config/opencode/package.json`:
192
+
193
+ ```json
194
+ {
195
+ "dependencies": {
196
+ "opencode-openai-codex-auth": "code-yeongyu/opencode-openai-codex-auth#fix/orphaned-function-call-output-with-tools"
197
+ }
198
+ }
199
+ ```
200
+
201
+ Then run `cd ~/.config/opencode && bun i`. In `opencode.json`, use `"opencode-openai-codex-auth"` without the version suffix.
202
+
203
+ #### 4.3.1 Model Configuration
204
+ You'll also need full model settings in `opencode.json`.
205
+ Read the [opencode-openai-codex-auth documentation](https://github.com/numman-ali/opencode-openai-codex-auth), copy provider/models config from [`config/full-opencode.json`](https://github.com/numman-ali/opencode-openai-codex-auth/blob/main/config/full-opencode.json), and merge carefully to avoid breaking the user's existing setup.
158
206
 
159
207
  Then authenticate:
160
208
 
161
209
  ```bash
162
210
  opencode auth login
163
- # Select Provider: OpenAI
164
- # Select Login method: ChatGPT Plus/Pro (Codex Subscription)
165
- # Complete OAuth flow in browser
211
+ # Provider: Select OpenAI
212
+ # Login method: Select ChatGPT Plus/Pro (Codex Subscription)
213
+ # Guide user through OAuth flow in browser
214
+ # Wait for completion
215
+ # Verify success and confirm with user
166
216
  ```
167
217
 
168
- #### 4.4 Alternative: Proxy-based Authentication
169
-
170
- For users who prefer proxy-based authentication, [VibeProxy](https://github.com/automazeio/vibeproxy) (macOS) or [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) remain available as alternatives.
171
218
 
172
219
  ### ⚠️ Warning
173
220
 
174
- **Do NOT modify model settings or disable features (agents, hooks, MCPs) unless the user explicitly requests it.**
221
+ **Don't change model settings or disable features (agents, hooks, MCPs) unless explicitly requested.**
175
222
 
176
- The plugin works perfectly with default settings. While you SHOULD enable `google_auth: true` as recommended, do not alter other configurations or disable features without a specific request.
223
+ The plugin works perfectly with defaults. Aside from the recommended `google_auth: true`, don't touch other settings without a specific ask.
177
224
 
178
225
  </details>
179
226
 
180
- ## Why OpenCode & Why Oh My OpenCode
181
227
 
182
- OpenCode is limitlessly extensible and customizable. Zero screen flicker.
183
- [LSP](https://opencode.ai/docs/lsp/), [linters, formatters](https://opencode.ai/docs/formatters/)? Automatic and fully configurable.
184
- You can mix and orchestrate models to your exact specifications.
185
- It is feature-rich. It is elegant. It handles the terminal without hesitation. It is high-performance.
228
+ ## Features
186
229
 
187
- But here is the catch: the learning curve is steep. There is a lot to master. And your time is expensive.
230
+ ### Agents: Your Teammates
188
231
 
189
- Inspired by [AmpCode](https://ampcode.com) and [Claude Code](https://code.claude.com/docs/en/overview), I have implemented their features here—often with superior execution.
190
- Because this is OpenCode.
232
+ - **oracle** (`openai/gpt-5.2`): Architecture, code review, strategy. Uses GPT-5.2 for its stellar logical reasoning and deep analysis. Inspired by AmpCode.
233
+ - **librarian** (`anthropic/claude-haiku-4-5`): Multi-repo analysis, doc lookup, implementation examples. Haiku is fast, smart enough, great at tool calls, and cheap. Inspired by AmpCode.
234
+ - **explore** (`opencode/grok-code`): Fast codebase exploration and pattern matching. Claude Code uses Haiku; we use Grok—it's free, blazing fast, and plenty smart for file traversal. Inspired by Claude Code.
235
+ - **frontend-ui-ux-engineer** (`google/gemini-3-pro-preview`): A designer turned developer. Builds gorgeous UIs. Gemini excels at creative, beautiful UI code.
236
+ - **document-writer** (`google/gemini-3-pro-preview`): Technical writing expert. Gemini is a wordsmith—writes prose that flows.
237
+ - **multimodal-looker** (`google/gemini-2.5-flash`): Visual content specialist. Analyzes PDFs, images, diagrams to extract information.
191
238
 
192
- Consider this a superior AmpCode, a superior Claude Code, or simply a specialized distribution.
239
+ The main agent invokes these automatically, but you can call them explicitly:
193
240
 
194
- I believe in the right tool for the job. For your wallet's sake, use CLIProxyAPI or VibeProxy. Employ the best LLMs from frontier labs. You are in command.
241
+ ```
242
+ Ask @oracle to review this design and propose an architecture
243
+ Ask @librarian how this is implemented—why does the behavior keep changing?
244
+ Ask @explore for the policy on this feature
245
+ ```
195
246
 
196
- **Note**: This setup is highly opinionated. It represents the generic component of my personal configuration, so it evolves constantly. I have spent tokens worth $20,000 just for my personal programming usages, and this plugin represents the apex of that experience. You simply inherit the best. If you have superior ideas, PRs are welcome.
247
+ Customize agent models, prompts, and permissions in `oh-my-opencode.json`. See [Configuration](#configuration).
197
248
 
198
- ## Features
249
+ ### Background Agents: Work Like a Team
199
250
 
200
- ### Agents
201
- - **oracle** (`openai/gpt-5.2`): The architect. Expert in code reviews and strategy. Uses GPT-5.2 for its unmatched logic and reasoning capabilities. Inspired by AmpCode.
202
- - **librarian** (`anthropic/claude-haiku-4-5`): Multi-repo analysis, documentation lookup, and implementation examples. Haiku is chosen for its speed, competence, excellent tool usage, and cost-efficiency. Inspired by AmpCode.
203
- - **explore** (`opencode/grok-code`): Fast exploration and pattern matching. Claude Code uses Haiku; we use Grok. It is currently free, blazing fast, and intelligent enough for file traversal. Inspired by Claude Code.
204
- - **frontend-ui-ux-engineer** (`google/gemini-3-pro-preview`): A designer turned developer. Creates stunning UIs. Uses Gemini because its creativity and UI code generation are superior.
205
- - **document-writer** (`google/gemini-3-pro-preview`): A technical writing expert. Gemini is a wordsmith; it writes prose that flows naturally.
251
+ What if you could run these agents relentlessly, never letting them idle?
206
252
 
207
- Each agent is automatically invoked by the main agent, but you can also explicitly request them:
253
+ - Have GPT debug while Claude tries different approaches to find the root cause
254
+ - Gemini writes the frontend while Claude handles the backend
255
+ - Kick off massive parallel searches, continue implementation on other parts, then finish using the search results
208
256
 
209
- ```
210
- @oracle Please think through the design of this part and suggest an architecture.
211
- @librarian Tell me how this is implemented — why does the behavior keep changing internally?
212
- @explore Tell me about the policy for this feature.
213
- ```
257
+ These workflows are possible with OhMyOpenCode.
214
258
 
215
- Agent models, prompts, and permissions can be customized via `oh-my-opencode.json`. See [Configuration](#configuration) for details.
259
+ Run subagents in the background. The main agent gets notified on completion. Wait for results if needed.
216
260
 
217
- #### Subagent Orchestration (omo_task)
261
+ **Make your agents work like your team works.**
218
262
 
219
- The `omo_task` tool allows agents (like `oracle`, `frontend-ui-ux-engineer`) to spawn `explore` or `librarian` as subagents to delegate specific tasks. This enables powerful workflows where an agent can "ask" another specialized agent to gather information before proceeding.
263
+ ### The Tools: Your Teammates Deserve Better
220
264
 
221
- > **Note**: To prevent infinite recursion, `explore` and `librarian` agents cannot use the `omo_task` tool themselves.
265
+ #### Why Are You the Only One Using an IDE?
222
266
 
223
- ### Tools
267
+ Syntax highlighting, autocomplete, refactoring, navigation, analysis—and now agents writing code...
224
268
 
225
- #### Built-in LSP Tools
269
+ **Why are you the only one with these tools?**
270
+ **Give them to your agents and watch them level up.**
226
271
 
227
- The features you use in your editor—other agents cannot access them. Oh My OpenCode hands those very tools to your LLM Agent. Refactoring, navigation, and analysis are all supported using the same OpenCode configuration.
272
+ [OpenCode provides LSP](https://opencode.ai/docs/lsp/), but only for analysis.
228
273
 
229
- [OpenCode provides LSP](https://opencode.ai/docs/lsp/), but only for analysis. Oh My OpenCode equips you with navigation and refactoring tools matching the same specification.
274
+ The features in your editor? Other agents can't touch them.
275
+ Hand your best tools to your best colleagues. Now they can properly refactor, navigate, and analyze.
230
276
 
231
- - **lsp_hover**: Get type info, docs, signatures at position
277
+ - **lsp_hover**: Type info, docs, signatures at position
232
278
  - **lsp_goto_definition**: Jump to symbol definition
233
279
  - **lsp_find_references**: Find all usages across workspace
234
- - **lsp_document_symbols**: Get file's symbol outline
280
+ - **lsp_document_symbols**: Get file symbol outline
235
281
  - **lsp_workspace_symbols**: Search symbols by name across project
236
282
  - **lsp_diagnostics**: Get errors/warnings before build
237
283
  - **lsp_servers**: List available LSP servers
238
284
  - **lsp_prepare_rename**: Validate rename operation
239
285
  - **lsp_rename**: Rename symbol across workspace
240
286
  - **lsp_code_actions**: Get available quick fixes/refactorings
241
- - **lsp_code_action_resolve**: Apply a code action
242
-
243
- #### Built-in AST-Grep Tools
244
-
287
+ - **lsp_code_action_resolve**: Apply code action
245
288
  - **ast_grep_search**: AST-aware code pattern search (25 languages)
246
289
  - **ast_grep_replace**: AST-aware code replacement
247
290
 
248
- #### Grep
249
-
250
- - **grep**: Content search with safety limits (5min timeout, 10MB output). Overrides OpenCode's built-in `grep` tool.
251
- - The default `grep` lacks safeguards. On a large codebase, a broad pattern can cause CPU overload and indefinite hanging.
252
- - This tool enforces strict limits and completely replaces the built-in `grep`.
253
-
254
- #### Glob
255
-
256
- - **glob**: File pattern matching with timeout protection (60s). Overrides OpenCode's built-in `glob` tool.
257
- - The default `glob` lacks timeout. If ripgrep hangs, it waits indefinitely.
258
- - This tool enforces timeouts and kills the process on expiration.
259
-
260
- #### Built-in MCPs
261
-
262
- - **websearch_exa**: Exa AI web search. Performs real-time web searches and can scrape content from specific URLs. Returns LLM-optimized context from relevant websites.
263
- - **context7**: Library documentation lookup. Fetches up-to-date documentation for any library to assist with accurate coding.
264
-
265
- Don't need these? Disable them via `oh-my-opencode.json`:
266
-
267
- ```json
268
- {
269
- "disabled_mcps": ["websearch_exa"]
270
- }
271
- ```
272
-
273
- #### Background Task
274
-
275
- Run long-running or complex tasks in the background without blocking your main session. The system automatically notifies you when tasks complete.
276
-
277
- - **background_task**: Launch a background agent task. Specify description, prompt, and agent type. Returns immediately with a task ID.
278
- - **background_output**: Check task progress (`block=false`) or wait for results (`block=true`). Supports custom timeout up to 10 minutes.
279
- - **background_cancel**: Cancel a running background task by task ID.
280
-
281
- Key capabilities:
282
- - **Async Execution**: Offload complex analysis or research while you continue working
283
- - **Auto Notification**: System notifies the main session when background tasks complete
284
- - **Status Tracking**: Real-time progress with tool call counts and last tool used
285
- - **Session Isolation**: Each task runs in an independent session
286
-
287
- Example workflow:
288
- ```
289
- 1. Launch: background_task → returns task_id="bg_abc123"
290
- 2. Continue working on other tasks
291
- 3. System notification: "Task bg_abc123 completed"
292
- 4. Retrieve: background_output(task_id="bg_abc123") → get full results
293
- ```
294
-
295
- ### Hooks
296
-
297
- - **Todo Continuation Enforcer**: Forces the agent to complete all tasks before exiting. Eliminates the common LLM issue of "giving up halfway".
298
- - **Context Window Monitor**: Implements [Context Window Anxiety Management](https://agentic-patterns.com/patterns/context-window-anxiety-management/). When context usage exceeds 70%, it reminds the agent that resources are sufficient, preventing rushed or low-quality output.
299
- - **Session Notification**: Sends a native OS notification when the job is done (macOS, Linux, Windows).
300
- - **Session Recovery**: Automatically recovers from API errors, ensuring session stability. Handles four scenarios:
301
- - **Tool Result Missing**: When `tool_use` block exists without `tool_result` (ESC interrupt) → injects "cancelled" tool results
302
- - **Thinking Block Order**: When thinking block must be first but isn't → prepends empty thinking block
303
- - **Thinking Disabled Violation**: When thinking blocks exist but thinking is disabled → strips thinking blocks
304
- - **Empty Content Message**: When message has only thinking/meta blocks without actual content → injects "(interrupted)" text via filesystem
305
- - **Comment Checker**: Detects and reports unnecessary comments after code modifications. Smartly ignores valid patterns (BDD, directives, docstrings, shebangs) to keep the codebase clean from AI-generated artifacts.
306
- - **Directory AGENTS.md Injector**: Automatically injects `AGENTS.md` contents when reading files. Searches upward from the file's directory to project root, collecting **all** `AGENTS.md` files along the path hierarchy. This enables nested, directory-specific instructions:
291
+ #### Context Is All You Need
292
+ - **Directory AGENTS.md / README.md Injector**: Auto-injects `AGENTS.md` and `README.md` when reading files. Walks from file directory to project root, collecting **all** `AGENTS.md` files along the path. Supports nested directory-specific instructions:
307
293
  ```
308
294
  project/
309
295
  ├── AGENTS.md # Project-wide context
@@ -311,16 +297,15 @@ Example workflow:
311
297
  │ ├── AGENTS.md # src-specific context
312
298
  │ └── components/
313
299
  │ ├── AGENTS.md # Component-specific context
314
- │ └── Button.tsx # Reading this injects ALL 3 AGENTS.md files
300
+ │ └── Button.tsx # Reading this injects all 3 AGENTS.md files
315
301
  ```
316
- When reading `Button.tsx`, the hook injects contexts in order: `project/AGENTS.md` → `src/AGENTS.md` → `components/AGENTS.md`. Each directory's context is injected only once per session. Inspired by Claude Code's CLAUDE.md feature.
317
- - **Directory README.md Injector**: Automatically injects `README.md` contents when reading files. Works identically to the AGENTS.md Injector, searching upward from the file's directory to project root. Provides project documentation context to the LLM agent. Each directory's README is injected only once per session.
318
- - **Rules Injector**: Automatically injects rules from `.claude/rules/` directory when reading files.
319
- - Searches upward from the file's directory to project root, plus `~/.claude/rules/` (user).
302
+ Reading `Button.tsx` injects in order: `project/AGENTS.md` → `src/AGENTS.md` → `components/AGENTS.md`. Each directory's context is injected once per session.
303
+ - **Conditional Rules Injector**: Not all rules apply all the time. Injects rules from `.claude/rules/` when conditions match.
304
+ - Walks upward from file directory to project root, plus `~/.claude/rules/` (user).
320
305
  - Supports `.md` and `.mdc` files.
321
- - Frontmatter-based matching with `globs` field (glob patterns).
322
- - `alwaysApply: true` option for rules that should always apply.
323
- - Example rule file structure:
306
+ - Matches via `globs` field in frontmatter.
307
+ - `alwaysApply: true` for rules that should always fire.
308
+ - Example rule file:
324
309
  ```markdown
325
310
  ---
326
311
  globs: ["*.ts", "src/**/*.js"]
@@ -329,57 +314,26 @@ Example workflow:
329
314
  - Use PascalCase for interface names
330
315
  - Use camelCase for function names
331
316
  ```
332
- - **Think Mode**: Automatic extended thinking detection and mode switching. Detects when user requests deep thinking (e.g., "think deeply", "ultrathink") and dynamically adjusts model settings for enhanced reasoning.
333
- - **Ultrawork Mode**: When user triggers "ultrawork" or "ulw" keywords, automatically injects agent orchestration guidance. Forces the main agent to leverage all available specialized agents (exploration, librarian, planning, UI) via background tasks in parallel, with strict TODO tracking and verification protocols.
334
- - **Anthropic Auto Compact**: Automatically compacts conversation history when approaching context limits for Anthropic models.
335
- - **Empty Task Response Detector**: Detects when subagent tasks return empty or meaningless responses and handles gracefully.
336
- - **Grep Output Truncator**: Prevents grep output from overwhelming the context by truncating excessively long results.
337
-
338
- You can disable specific built-in hooks using `disabled_hooks` in `~/.config/opencode/oh-my-opencode.json` or `.opencode/oh-my-opencode.json`:
339
-
340
- ```json
341
- {
342
- "disabled_hooks": ["session-notification", "comment-checker"]
343
- }
344
- ```
345
-
346
- Available hooks: `todo-continuation-enforcer`, `context-window-monitor`, `session-recovery`, `session-notification`, `comment-checker`, `grep-output-truncator`, `directory-agents-injector`, `directory-readme-injector`, `empty-task-response-detector`, `think-mode`, `ultrawork-mode`, `anthropic-auto-compact`, `rules-injector`, `background-notification`, `auto-update-checker`
347
-
348
- > **Note**: `disabled_hooks` controls Oh My OpenCode's built-in hooks. To disable Claude Code's `settings.json` hooks, use `claude_code.hooks: false` instead (see [Compatibility Toggles](#compatibility-toggles)).
317
+ - **Online**: Project rules aren't everything. Built-in exa and context7 MCP for web search.
349
318
 
350
- ### Claude Code Compatibility
319
+ #### Be Multimodal. Save Tokens.
351
320
 
352
- Oh My OpenCode provides seamless Claude Code configuration compatibility. If you've been using Claude Code, your existing setup works out of the box.
321
+ The look_at tool from AmpCode, now in OhMyOpenCode.
322
+ Instead of the agent reading massive files and bloating context, it internally leverages another agent to extract just what it needs.
353
323
 
354
- #### Compatibility Toggles
355
-
356
- If you want to disable specific Claude Code compatibility features, use the `claude_code` configuration object:
324
+ #### I Removed Their Blockers
325
+ - Replaces built-in grep and glob tools. Default implementation has no timeout—can hang forever.
357
326
 
358
- ```json
359
- {
360
- "claude_code": {
361
- "mcp": false,
362
- "commands": false,
363
- "skills": false,
364
- "agents": false,
365
- "hooks": false
366
- }
367
- }
368
- ```
369
327
 
370
- | Toggle | When `false`, disables loading from... | NOT affected |
371
- |--------|----------------------------------------|--------------|
372
- | `mcp` | `~/.claude/.mcp.json`, `./.mcp.json`, `./.claude/.mcp.json` | Built-in MCPs (context7, websearch_exa) |
373
- | `commands` | `~/.claude/commands/*.md`, `./.claude/commands/*.md` | `~/.config/opencode/command/`, `./.opencode/command/` |
374
- | `skills` | `~/.claude/skills/*/SKILL.md`, `./.claude/skills/*/SKILL.md` | - |
375
- | `agents` | `~/.claude/agents/*.md`, `./.claude/agents/*.md` | Built-in agents (oracle, librarian, etc.) |
376
- | `hooks` | `~/.claude/settings.json`, `./.claude/settings.json`, `./.claude/settings.local.json` | - |
328
+ ### Goodbye Claude Code. Hello Oh My OpenCode.
377
329
 
378
- All toggles default to `true` (enabled). Omit the entire `claude_code` object for full Claude Code compatibility.
330
+ Oh My OpenCode has a Claude Code compatibility layer.
331
+ If you were using Claude Code, your existing config just works.
379
332
 
380
333
  #### Hooks Integration
381
334
 
382
- Execute custom scripts via Claude Code's `settings.json` hook system. Oh My OpenCode reads and executes hooks defined in:
335
+ Run custom scripts via Claude Code's `settings.json` hook system.
336
+ Oh My OpenCode reads and executes hooks from:
383
337
 
384
338
  - `~/.claude/settings.json` (user)
385
339
  - `./.claude/settings.json` (project)
@@ -388,7 +342,7 @@ Execute custom scripts via Claude Code's `settings.json` hook system. Oh My Open
388
342
  Supported hook events:
389
343
  - **PreToolUse**: Runs before tool execution. Can block or modify tool input.
390
344
  - **PostToolUse**: Runs after tool execution. Can add warnings or context.
391
- - **UserPromptSubmit**: Runs when user submits a prompt. Can block or inject messages.
345
+ - **UserPromptSubmit**: Runs when user submits prompt. Can block or inject messages.
392
346
  - **Stop**: Runs when session goes idle. Can inject follow-up prompts.
393
347
 
394
348
  Example `settings.json`:
@@ -405,7 +359,7 @@ Example `settings.json`:
405
359
  }
406
360
  ```
407
361
 
408
- #### Configuration Loaders
362
+ #### Config Loaders
409
363
 
410
364
  **Command Loader**: Loads markdown-based slash commands from 4 directories:
411
365
  - `~/.claude/commands/` (user)
@@ -421,7 +375,7 @@ Example `settings.json`:
421
375
  - `~/.claude/agents/*.md` (user)
422
376
  - `./.claude/agents/*.md` (project)
423
377
 
424
- **MCP Loader**: Loads MCP server configurations from `.mcp.json` files:
378
+ **MCP Loader**: Loads MCP server configs from `.mcp.json` files:
425
379
  - `~/.claude/.mcp.json` (user)
426
380
  - `./.mcp.json` (project)
427
381
  - `./.claude/.mcp.json` (local)
@@ -429,24 +383,57 @@ Example `settings.json`:
429
383
 
430
384
  #### Data Storage
431
385
 
432
- **Todo Management**: Session todos are stored in Claude Code compatible format at `~/.claude/todos/`.
386
+ **Todo Management**: Session todos stored in `~/.claude/todos/` in Claude Code compatible format.
433
387
 
434
- **Transcript**: Session activity is logged to `~/.claude/transcripts/` in JSONL format, enabling replay and analysis.
388
+ **Transcript**: Session activity logged to `~/.claude/transcripts/` in JSONL format for replay and analysis.
435
389
 
436
- > **Note on `claude-code-*` naming**: Features under `src/features/claude-code-*/` are migrated from Claude Code's configuration system. This naming convention clearly identifies which features originated from Claude Code.
390
+ #### Compatibility Toggles
391
+
392
+ Disable specific Claude Code compatibility features with the `claude_code` config object:
437
393
 
438
- ### Other Features
394
+ ```json
395
+ {
396
+ "claude_code": {
397
+ "mcp": false,
398
+ "commands": false,
399
+ "skills": false,
400
+ "agents": false,
401
+ "hooks": false
402
+ }
403
+ }
404
+ ```
439
405
 
440
- - **Terminal Title**: Auto-updates terminal title with session status (idle ○, processing ◐, tool ⚡, error ✖). Supports tmux.
441
- - **Session State**: Centralized session tracking module used by event hooks and terminal title updates.
406
+ | Toggle | When `false`, stops loading from... | Unaffected |
407
+ | ---------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------- |
408
+ | `mcp` | `~/.claude/.mcp.json`, `./.mcp.json`, `./.claude/.mcp.json` | Built-in MCP (context7, websearch_exa) |
409
+ | `commands` | `~/.claude/commands/*.md`, `./.claude/commands/*.md` | `~/.config/opencode/command/`, `./.opencode/command/` |
410
+ | `skills` | `~/.claude/skills/*/SKILL.md`, `./.claude/skills/*/SKILL.md` | - |
411
+ | `agents` | `~/.claude/agents/*.md`, `./.claude/agents/*.md` | Built-in agents (oracle, librarian, etc.) |
412
+ | `hooks` | `~/.claude/settings.json`, `./.claude/settings.json`, `./.claude/settings.local.json` | - |
413
+
414
+ All toggles default to `true` (enabled). Omit the `claude_code` object for full Claude Code compatibility.
415
+
416
+ ### Not Just for the Agents
417
+
418
+ When agents thrive, you thrive. But I want to help you directly too.
419
+
420
+ - **Ultrawork Mode**: Type "ultrawork" or "ulw" and agent orchestration kicks in. Forces the main agent to max out all available specialists (explore, librarian, plan, UI) via background tasks in parallel, with strict TODO tracking and verification. Just ultrawork. Everything fires at full capacity.
421
+ - **Todo Continuation Enforcer**: Makes agents finish all TODOs before stopping. Kills the chronic LLM habit of quitting halfway.
422
+ - **Comment Checker**: LLMs love comments. Too many comments. This reminds them to cut the noise. Smartly ignores valid patterns (BDD, directives, docstrings) and demands justification for the rest. Clean code wins.
423
+ - **Think Mode**: Auto-detects when extended thinking is needed and switches modes. Catches phrases like "think deeply" or "ultrathink" and dynamically adjusts model settings for maximum reasoning.
424
+ - **Context Window Monitor**: Implements [Context Window Anxiety Management](https://agentic-patterns.com/patterns/context-window-anxiety-management/).
425
+ - At 70%+ usage, reminds agents there's still headroom—prevents rushed, sloppy work.
426
+ - Stability features that felt missing in OpenCode are built in. The Claude Code experience, transplanted. Sessions don't crash mid-run. Even if they do, they recover.
442
427
 
443
428
  ## Configuration
444
429
 
445
- Configuration file locations (in priority order):
430
+ Highly opinionated, but adjustable to taste.
431
+
432
+ Config file locations (priority order):
446
433
  1. `.opencode/oh-my-opencode.json` (project)
447
434
  2. `~/.config/opencode/oh-my-opencode.json` (user)
448
435
 
449
- Schema autocomplete is supported:
436
+ Schema autocomplete supported:
450
437
 
451
438
  ```json
452
439
  {
@@ -464,7 +451,7 @@ Enable built-in Antigravity OAuth for Google Gemini models:
464
451
  }
465
452
  ```
466
453
 
467
- When enabled, `opencode auth login` will show "OAuth with Google (Antigravity)" as a login option for the Google provider.
454
+ When enabled, `opencode auth login` shows "OAuth with Google (Antigravity)" for the Google provider.
468
455
 
469
456
  ### Agents
470
457
 
@@ -486,7 +473,7 @@ Override built-in agent settings:
486
473
 
487
474
  Each agent supports: `model`, `temperature`, `top_p`, `prompt`, `tools`, `disable`, `description`, `mode`, `color`, `permission`.
488
475
 
489
- Or you can disable them using `disabled_agents` in `~/.config/opencode/oh-my-opencode.json` or `.opencode/oh-my-opencode.json`:
476
+ Or disable via `disabled_agents` in `~/.config/opencode/oh-my-opencode.json` or `.opencode/oh-my-opencode.json`:
490
477
 
491
478
  ```json
492
479
  {
@@ -498,9 +485,9 @@ Available agents: `oracle`, `librarian`, `explore`, `frontend-ui-ux-engineer`, `
498
485
 
499
486
  ### MCPs
500
487
 
501
- By default, Context7 and Exa MCP are supported.
488
+ Context7 and Exa MCP enabled by default.
502
489
 
503
- If you don't want these, you can disable them using `disabled_mcps` in `~/.config/opencode/oh-my-opencode.json` or `.opencode/oh-my-opencode.json`:
490
+ Don't want them? Disable via `disabled_mcps` in `~/.config/opencode/oh-my-opencode.json` or `.opencode/oh-my-opencode.json`:
504
491
 
505
492
  ```json
506
493
  {
@@ -511,10 +498,10 @@ If you don't want these, you can disable them using `disabled_mcps` in `~/.confi
511
498
  ### LSP
512
499
 
513
500
  OpenCode provides LSP tools for analysis.
514
- Oh My OpenCode provides LSP tools for refactoring (rename, code actions).
515
- It supports all LSP configurations and custom settings supported by OpenCode (those configured in opencode.json), and you can also configure additional settings specifically for Oh My OpenCode as shown below.
501
+ Oh My OpenCode adds refactoring tools (rename, code actions).
502
+ All OpenCode LSP configs and custom settings (from opencode.json) are supported, plus additional Oh My OpenCode-specific settings.
516
503
 
517
- You can configure additional LSP servers via the `lsp` option in `~/.config/opencode/oh-my-opencode.json` or `.opencode/oh-my-opencode.json`:
504
+ Add LSP servers via the `lsp` option in `~/.config/opencode/oh-my-opencode.json` or `.opencode/oh-my-opencode.json`:
518
505
 
519
506
  ```json
520
507
  {
@@ -533,29 +520,46 @@ You can configure additional LSP servers via the `lsp` option in `~/.config/open
533
520
 
534
521
  Each server supports: `command`, `extensions`, `priority`, `env`, `initialization`, `disabled`.
535
522
 
523
+
536
524
  ## Author's Note
537
525
 
538
- Install Oh My OpenCode. Do not waste time configuring OpenCode from scratch.
539
- I have resolved the friction so you don't have to. The answers are in this plugin. If OpenCode is Arch Linux, Oh My OpenCode is [Omarchy](https://omarchy.org/).
526
+ Install Oh My OpenCode.
540
527
 
541
- Enjoy the multi-model stability and rich feature set that other harnesses promise but fail to deliver.
542
- I will continue testing and updating here. I am the primary user of this project.
528
+ I've used LLMs worth $24,000 tokens purely for personal development.
529
+ Tried every tool out there, configured them to death. OpenCode won.
543
530
 
544
- - Who possesses the best raw logic?
545
- - Who is the debugging god?
531
+ The answers to every problem I hit are baked into this plugin. Just install and go.
532
+ If OpenCode is Debian/Arch, Oh My OpenCode is Ubuntu/[Omarchy](https://omarchy.org/).
533
+
534
+
535
+ Heavily influenced by [AmpCode](https://ampcode.com) and [Claude Code](https://code.claude.com/docs/overview)—I've ported their features here, often improved. And I'm still building.
536
+ It's **Open**Code, after all.
537
+
538
+ Enjoy multi-model orchestration, stability, and rich features that other harnesses promise but can't deliver.
539
+ I'll keep testing and updating. I'm this project's most obsessive user.
540
+ - Which model has the sharpest logic?
541
+ - Who's the debugging god?
546
542
  - Who writes the best prose?
547
543
  - Who dominates frontend?
548
544
  - Who owns backend?
549
545
  - Which model is fastest for daily driving?
550
546
  - What new features are other harnesses shipping?
551
547
 
552
- Do not overthink it. I have done the thinking. I will integrate the best practices. I will update this.
553
- If this sounds arrogant and you have a superior solution, send a PR. You are welcome.
548
+ This plugin is the distillation of that experience. Just take the best. Got a better idea? PRs are welcome.
549
+
550
+ **Stop agonizing over agent harness choices.**
551
+ **I'll do the research, borrow from the best, and ship updates here.**
552
+
553
+ If this sounds arrogant and you have a better answer, please contribute. You're welcome.
554
+
555
+ I have no affiliation with any project or model mentioned here. This is purely personal experimentation and preference.
554
556
 
555
- As of now, I have no affiliation with any of the projects or models mentioned here. This plugin is purely based on personal experimentation and preference.
557
+ 99% of this project was built using OpenCode. I tested for functionality—I don't really know how to write proper TypeScript. **But I personally reviewed and largely rewrote this doc, so read with confidence.**
556
558
 
557
- I constructed 99% of this project using OpenCode. I focused on functional verification, and honestly, I don't know how to write proper TypeScript. **But I personally reviewed and comprehensively rewritten this documentation, so you can rely on it with confidence.**
558
559
  ## Warnings
559
560
 
560
- - If you are on [1.0.132](https://github.com/sst/opencode/releases/tag/v1.0.132) or lower, OpenCode has a bug that might break config.
561
- - [The fix](https://github.com/sst/opencode/pull/5040) was merged after 1.0.132, so use a newer version.
561
+ - Productivity might spike too hard. Don't let your coworker notice.
562
+ - Actually, I'll spread the word. Let's see who wins.
563
+ - If you're on [1.0.132](https://github.com/sst/opencode/releases/tag/v1.0.132) or older, an OpenCode bug may break config.
564
+ - [The fix](https://github.com/sst/opencode/pull/5040) was merged after 1.0.132—use a newer version.
565
+ - Fun fact: That PR was discovered and fixed thanks to OhMyOpenCode's Librarian, Explore, and Oracle setup.