mcp-subagents-opencode 1.0.0

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 (219) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +602 -0
  3. package/build/config/timeouts.d.ts +9 -0
  4. package/build/config/timeouts.d.ts.map +1 -0
  5. package/build/config/timeouts.js +18 -0
  6. package/build/config/timeouts.js.map +1 -0
  7. package/build/helpers.d.ts +6 -0
  8. package/build/helpers.d.ts.map +1 -0
  9. package/build/helpers.js +47 -0
  10. package/build/helpers.js.map +1 -0
  11. package/build/index.d.ts +3 -0
  12. package/build/index.d.ts.map +1 -0
  13. package/build/index.js +245 -0
  14. package/build/index.js.map +1 -0
  15. package/build/models.d.ts +32 -0
  16. package/build/models.d.ts.map +1 -0
  17. package/build/models.js +58 -0
  18. package/build/models.js.map +1 -0
  19. package/build/server/register-notifications.d.ts +3 -0
  20. package/build/server/register-notifications.d.ts.map +1 -0
  21. package/build/server/register-notifications.js +77 -0
  22. package/build/server/register-notifications.js.map +1 -0
  23. package/build/server/register-resources.d.ts +3 -0
  24. package/build/server/register-resources.d.ts.map +1 -0
  25. package/build/server/register-resources.js +210 -0
  26. package/build/server/register-resources.js.map +1 -0
  27. package/build/server/register-retry-execution.d.ts +2 -0
  28. package/build/server/register-retry-execution.d.ts.map +1 -0
  29. package/build/server/register-retry-execution.js +28 -0
  30. package/build/server/register-retry-execution.js.map +1 -0
  31. package/build/server/register-tasks.d.ts +3 -0
  32. package/build/server/register-tasks.d.ts.map +1 -0
  33. package/build/server/register-tasks.js +52 -0
  34. package/build/server/register-tasks.js.map +1 -0
  35. package/build/server/register-tools.d.ts +3 -0
  36. package/build/server/register-tools.d.ts.map +1 -0
  37. package/build/server/register-tools.js +32 -0
  38. package/build/server/register-tools.js.map +1 -0
  39. package/build/server/resource-helpers.d.ts +21 -0
  40. package/build/server/resource-helpers.d.ts.map +1 -0
  41. package/build/server/resource-helpers.js +84 -0
  42. package/build/server/resource-helpers.js.map +1 -0
  43. package/build/services/account-manager.d.ts +88 -0
  44. package/build/services/account-manager.d.ts.map +1 -0
  45. package/build/services/account-manager.js +239 -0
  46. package/build/services/account-manager.js.map +1 -0
  47. package/build/services/claude-code-runner.d.ts +15 -0
  48. package/build/services/claude-code-runner.d.ts.map +1 -0
  49. package/build/services/claude-code-runner.js +475 -0
  50. package/build/services/claude-code-runner.js.map +1 -0
  51. package/build/services/client-context.d.ts +31 -0
  52. package/build/services/client-context.d.ts.map +1 -0
  53. package/build/services/client-context.js +44 -0
  54. package/build/services/client-context.js.map +1 -0
  55. package/build/services/exhaustion-fallback.d.ts +27 -0
  56. package/build/services/exhaustion-fallback.d.ts.map +1 -0
  57. package/build/services/exhaustion-fallback.js +30 -0
  58. package/build/services/exhaustion-fallback.js.map +1 -0
  59. package/build/services/fallback-orchestrator.d.ts +16 -0
  60. package/build/services/fallback-orchestrator.d.ts.map +1 -0
  61. package/build/services/fallback-orchestrator.js +48 -0
  62. package/build/services/fallback-orchestrator.js.map +1 -0
  63. package/build/services/opencode-client.d.ts +40 -0
  64. package/build/services/opencode-client.d.ts.map +1 -0
  65. package/build/services/opencode-client.js +147 -0
  66. package/build/services/opencode-client.js.map +1 -0
  67. package/build/services/opencode-spawner.d.ts +56 -0
  68. package/build/services/opencode-spawner.d.ts.map +1 -0
  69. package/build/services/opencode-spawner.js +426 -0
  70. package/build/services/opencode-spawner.js.map +1 -0
  71. package/build/services/output-file.d.ts +24 -0
  72. package/build/services/output-file.d.ts.map +1 -0
  73. package/build/services/output-file.js +90 -0
  74. package/build/services/output-file.js.map +1 -0
  75. package/build/services/progress-registry.d.ts +12 -0
  76. package/build/services/progress-registry.d.ts.map +1 -0
  77. package/build/services/progress-registry.js +97 -0
  78. package/build/services/progress-registry.js.map +1 -0
  79. package/build/services/question-registry.d.ts +79 -0
  80. package/build/services/question-registry.d.ts.map +1 -0
  81. package/build/services/question-registry.js +249 -0
  82. package/build/services/question-registry.js.map +1 -0
  83. package/build/services/retry-queue.d.ts +41 -0
  84. package/build/services/retry-queue.d.ts.map +1 -0
  85. package/build/services/retry-queue.js +195 -0
  86. package/build/services/retry-queue.js.map +1 -0
  87. package/build/services/sdk-client-manager.d.ts +149 -0
  88. package/build/services/sdk-client-manager.d.ts.map +1 -0
  89. package/build/services/sdk-client-manager.js +632 -0
  90. package/build/services/sdk-client-manager.js.map +1 -0
  91. package/build/services/sdk-session-adapter.d.ts +203 -0
  92. package/build/services/sdk-session-adapter.d.ts.map +1 -0
  93. package/build/services/sdk-session-adapter.js +1088 -0
  94. package/build/services/sdk-session-adapter.js.map +1 -0
  95. package/build/services/sdk-spawner.d.ts +42 -0
  96. package/build/services/sdk-spawner.d.ts.map +1 -0
  97. package/build/services/sdk-spawner.js +488 -0
  98. package/build/services/sdk-spawner.js.map +1 -0
  99. package/build/services/session-hooks.d.ts +24 -0
  100. package/build/services/session-hooks.d.ts.map +1 -0
  101. package/build/services/session-hooks.js +130 -0
  102. package/build/services/session-hooks.js.map +1 -0
  103. package/build/services/session-snapshot.d.ts +19 -0
  104. package/build/services/session-snapshot.d.ts.map +1 -0
  105. package/build/services/session-snapshot.js +203 -0
  106. package/build/services/session-snapshot.js.map +1 -0
  107. package/build/services/subscription-registry.d.ts +12 -0
  108. package/build/services/subscription-registry.d.ts.map +1 -0
  109. package/build/services/subscription-registry.js +27 -0
  110. package/build/services/subscription-registry.js.map +1 -0
  111. package/build/services/task-manager.d.ts +150 -0
  112. package/build/services/task-manager.d.ts.map +1 -0
  113. package/build/services/task-manager.js +765 -0
  114. package/build/services/task-manager.js.map +1 -0
  115. package/build/services/task-persistence.d.ts +29 -0
  116. package/build/services/task-persistence.d.ts.map +1 -0
  117. package/build/services/task-persistence.js +159 -0
  118. package/build/services/task-persistence.js.map +1 -0
  119. package/build/services/task-status-mapper.d.ts +21 -0
  120. package/build/services/task-status-mapper.d.ts.map +1 -0
  121. package/build/services/task-status-mapper.js +171 -0
  122. package/build/services/task-status-mapper.js.map +1 -0
  123. package/build/templates/index.d.ts +22 -0
  124. package/build/templates/index.d.ts.map +1 -0
  125. package/build/templates/index.js +147 -0
  126. package/build/templates/index.js.map +1 -0
  127. package/build/templates/overlays/coder-csharp.mdx +58 -0
  128. package/build/templates/overlays/coder-go.mdx +53 -0
  129. package/build/templates/overlays/coder-java.mdx +54 -0
  130. package/build/templates/overlays/coder-kotlin.mdx +56 -0
  131. package/build/templates/overlays/coder-nextjs.mdx +65 -0
  132. package/build/templates/overlays/coder-python.mdx +53 -0
  133. package/build/templates/overlays/coder-react.mdx +55 -0
  134. package/build/templates/overlays/coder-ruby.mdx +59 -0
  135. package/build/templates/overlays/coder-rust.mdx +48 -0
  136. package/build/templates/overlays/coder-supabase.mdx +268 -0
  137. package/build/templates/overlays/coder-supastarter.mdx +313 -0
  138. package/build/templates/overlays/coder-swift.mdx +56 -0
  139. package/build/templates/overlays/coder-tauri.mdx +566 -0
  140. package/build/templates/overlays/coder-triggerdev.mdx +296 -0
  141. package/build/templates/overlays/coder-typescript.mdx +45 -0
  142. package/build/templates/overlays/coder-vue.mdx +62 -0
  143. package/build/templates/overlays/planner-architecture.mdx +78 -0
  144. package/build/templates/overlays/planner-bugfix.mdx +36 -0
  145. package/build/templates/overlays/planner-feature.mdx +38 -0
  146. package/build/templates/overlays/planner-migration.mdx +50 -0
  147. package/build/templates/overlays/planner-refactor.mdx +57 -0
  148. package/build/templates/overlays/researcher-library.mdx +59 -0
  149. package/build/templates/overlays/researcher-performance.mdx +68 -0
  150. package/build/templates/overlays/researcher-security.mdx +86 -0
  151. package/build/templates/overlays/tester-graphql.mdx +191 -0
  152. package/build/templates/overlays/tester-playwright.mdx +621 -0
  153. package/build/templates/overlays/tester-rest.mdx +101 -0
  154. package/build/templates/overlays/tester-suite.mdx +177 -0
  155. package/build/templates/super-coder.mdx +529 -0
  156. package/build/templates/super-planner.mdx +568 -0
  157. package/build/templates/super-researcher.mdx +406 -0
  158. package/build/templates/super-tester.mdx +243 -0
  159. package/build/tools/answer-question.d.ts +30 -0
  160. package/build/tools/answer-question.d.ts.map +1 -0
  161. package/build/tools/answer-question.js +108 -0
  162. package/build/tools/answer-question.js.map +1 -0
  163. package/build/tools/cancel-task.d.ts +44 -0
  164. package/build/tools/cancel-task.d.ts.map +1 -0
  165. package/build/tools/cancel-task.js +144 -0
  166. package/build/tools/cancel-task.js.map +1 -0
  167. package/build/tools/send-message.d.ts +39 -0
  168. package/build/tools/send-message.d.ts.map +1 -0
  169. package/build/tools/send-message.js +124 -0
  170. package/build/tools/send-message.js.map +1 -0
  171. package/build/tools/shared-spawn.d.ts +56 -0
  172. package/build/tools/shared-spawn.d.ts.map +1 -0
  173. package/build/tools/shared-spawn.js +114 -0
  174. package/build/tools/shared-spawn.js.map +1 -0
  175. package/build/tools/spawn-agent.d.ts +85 -0
  176. package/build/tools/spawn-agent.d.ts.map +1 -0
  177. package/build/tools/spawn-agent.js +133 -0
  178. package/build/tools/spawn-agent.js.map +1 -0
  179. package/build/tools/spawn-coder.d.ts +70 -0
  180. package/build/tools/spawn-coder.d.ts.map +1 -0
  181. package/build/tools/spawn-coder.js +71 -0
  182. package/build/tools/spawn-coder.js.map +1 -0
  183. package/build/tools/spawn-planner.d.ts +70 -0
  184. package/build/tools/spawn-planner.d.ts.map +1 -0
  185. package/build/tools/spawn-planner.js +71 -0
  186. package/build/tools/spawn-planner.js.map +1 -0
  187. package/build/tools/spawn-researcher.d.ts +70 -0
  188. package/build/tools/spawn-researcher.d.ts.map +1 -0
  189. package/build/tools/spawn-researcher.js +70 -0
  190. package/build/tools/spawn-researcher.js.map +1 -0
  191. package/build/tools/spawn-task.d.ts +74 -0
  192. package/build/tools/spawn-task.d.ts.map +1 -0
  193. package/build/tools/spawn-task.js +107 -0
  194. package/build/tools/spawn-task.js.map +1 -0
  195. package/build/tools/spawn-tester.d.ts +70 -0
  196. package/build/tools/spawn-tester.d.ts.map +1 -0
  197. package/build/tools/spawn-tester.js +69 -0
  198. package/build/tools/spawn-tester.js.map +1 -0
  199. package/build/types.d.ts +101 -0
  200. package/build/types.d.ts.map +1 -0
  201. package/build/types.js +28 -0
  202. package/build/types.js.map +1 -0
  203. package/build/utils/brief-validator.d.ts +30 -0
  204. package/build/utils/brief-validator.d.ts.map +1 -0
  205. package/build/utils/brief-validator.js +254 -0
  206. package/build/utils/brief-validator.js.map +1 -0
  207. package/build/utils/format.d.ts +34 -0
  208. package/build/utils/format.d.ts.map +1 -0
  209. package/build/utils/format.js +55 -0
  210. package/build/utils/format.js.map +1 -0
  211. package/build/utils/sanitize.d.ts +240 -0
  212. package/build/utils/sanitize.d.ts.map +1 -0
  213. package/build/utils/sanitize.js +89 -0
  214. package/build/utils/sanitize.js.map +1 -0
  215. package/build/utils/task-id-generator.d.ts +10 -0
  216. package/build/utils/task-id-generator.d.ts.map +1 -0
  217. package/build/utils/task-id-generator.js +22 -0
  218. package/build/utils/task-id-generator.js.map +1 -0
  219. package/package.json +62 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Yigit Konur
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,602 @@
1
+ <h1 align="center">Super Subagents for OpenCode</h1>
2
+
3
+ <h3 align="center">Spawn parallel autonomous AI agents from any MCP client.</h3>
4
+
5
+ <p align="center">
6
+ Each agent gets its own isolated OpenCode session with full tool access (file read/write, terminal, search). Your main session stays unblocked while agents code, plan, research, and test simultaneously.
7
+ </p>
8
+
9
+ <p align="center">
10
+ <a href="https://www.npmjs.com/package/mcp-subagents-opencode"><img src="https://img.shields.io/npm/v/mcp-subagents-opencode?style=flat-square&color=cb3837&label=npm" alt="npm"></a>
11
+ <img src="https://img.shields.io/node/v/mcp-subagents-opencode?style=flat-square&color=339933&label=node" alt="node 18+">
12
+ <a href="https://github.com/yigitkonur/mcp-subagents-opencode/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="license MIT"></a>
13
+ <img src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey?style=flat-square" alt="platform">
14
+ <img src="https://img.shields.io/badge/backend-OpenCode-purple?style=flat-square" alt="OpenCode backend">
15
+ </p>
16
+
17
+ <p align="center">
18
+ <img src="https://img.shields.io/badge/4_tools-spawn%20%C2%B7%20message%20%C2%B7%20cancel%20%C2%B7%20answer-brightgreen?style=flat-square" alt="4 tools">
19
+ <img src="https://img.shields.io/badge/4_roles-coder%20%C2%B7%20planner%20%C2%B7%20researcher%20%C2%B7%20tester-orange?style=flat-square" alt="4 roles">
20
+ <img src="https://img.shields.io/badge/32_templates-16%20lang%20%2B%2016%20specialty-blue?style=flat-square" alt="32 templates">
21
+ </p>
22
+
23
+ ---
24
+
25
+ ## Quick Navigation
26
+
27
+ [Prerequisites](#prerequisites) &#8226; [Quick Install](#quick-install) &#8226; [How It Works](#how-it-works) &#8226; [Tools](#tool-reference) &#8226; [Templates](#agent-templates) &#8226; [Configuration](#environment-variables) &#8226; [Transport Modes](#transport-modes) &#8226; [Troubleshooting](#troubleshooting)
28
+
29
+ ---
30
+
31
+ ## Prerequisites
32
+
33
+ This MCP server delegates work to an [OpenCode](https://opencode.ai) headless server. Start it before spawning agents:
34
+
35
+ ```bash
36
+ # Install OpenCode (if not already installed)
37
+ curl -fsSL https://opencode.ai/install | bash
38
+
39
+ # Start the headless server
40
+ opencode serve
41
+ ```
42
+
43
+ Verify it's running:
44
+
45
+ ```bash
46
+ curl -s -H 'Accept: application/json' http://127.0.0.1:19747/session | head -c 100
47
+ ```
48
+
49
+ > OpenCode must have at least one AI provider configured (Anthropic, OpenAI, etc). The MCP server lets OpenCode pick the model internally.
50
+
51
+ ---
52
+
53
+ ## Quick Install
54
+
55
+ No cloning needed. Install directly from npm with a single command for your client.
56
+
57
+ ### Claude Code (CLI)
58
+
59
+ ```bash
60
+ claude mcp add supersubagents -- npx -y mcp-subagents-opencode
61
+ ```
62
+
63
+ With a custom OpenCode URL:
64
+
65
+ ```bash
66
+ claude mcp add supersubagents \
67
+ -e OPENCODE_BASE_URL=http://127.0.0.1:19747 \
68
+ -- npx -y mcp-subagents-opencode
69
+ ```
70
+
71
+ Scoped installs:
72
+
73
+ ```bash
74
+ # Project scope -- shared via .mcp.json (checked into git)
75
+ claude mcp add supersubagents --scope project -- npx -y mcp-subagents-opencode
76
+
77
+ # User scope -- available in all your projects
78
+ claude mcp add supersubagents --scope user -- npx -y mcp-subagents-opencode
79
+ ```
80
+
81
+ Or point to the HTTP transport:
82
+
83
+ ```bash
84
+ claude mcp add supersubagents --transport http http://127.0.0.1:51997/mcp
85
+ ```
86
+
87
+ <details>
88
+ <summary>Verify / remove</summary>
89
+
90
+ ```bash
91
+ claude mcp list
92
+ claude mcp get supersubagents
93
+ claude mcp remove supersubagents
94
+ ```
95
+
96
+ </details>
97
+
98
+ ---
99
+
100
+ ### Claude Desktop
101
+
102
+ Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
103
+
104
+ ```json
105
+ {
106
+ "mcpServers": {
107
+ "supersubagents": {
108
+ "command": "npx",
109
+ "args": ["-y", "mcp-subagents-opencode"],
110
+ "env": {
111
+ "OPENCODE_BASE_URL": "http://127.0.0.1:19747"
112
+ }
113
+ }
114
+ }
115
+ }
116
+ ```
117
+
118
+ Restart Claude Desktop after saving.
119
+
120
+ ---
121
+
122
+ ### Cursor
123
+
124
+ Create `.cursor/mcp.json` in your project root (or `~/.cursor/mcp.json` for global):
125
+
126
+ ```json
127
+ {
128
+ "mcpServers": {
129
+ "supersubagents": {
130
+ "command": "npx",
131
+ "args": ["-y", "mcp-subagents-opencode"],
132
+ "env": {
133
+ "OPENCODE_BASE_URL": "http://127.0.0.1:19747"
134
+ }
135
+ }
136
+ }
137
+ }
138
+ ```
139
+
140
+ Or via HTTP transport:
141
+
142
+ ```json
143
+ {
144
+ "mcpServers": {
145
+ "supersubagents": {
146
+ "type": "streamable-http",
147
+ "url": "http://127.0.0.1:51997/mcp"
148
+ }
149
+ }
150
+ }
151
+ ```
152
+
153
+ ---
154
+
155
+ ### VS Code + GitHub Copilot
156
+
157
+ Create `.vscode/mcp.json` in your workspace:
158
+
159
+ ```json
160
+ {
161
+ "mcpServers": {
162
+ "supersubagents": {
163
+ "command": "npx",
164
+ "args": ["-y", "mcp-subagents-opencode"],
165
+ "env": {
166
+ "OPENCODE_BASE_URL": "http://127.0.0.1:19747"
167
+ }
168
+ }
169
+ }
170
+ }
171
+ ```
172
+
173
+ > Requires VS Code 1.101+ with Copilot extension.
174
+
175
+ ---
176
+
177
+ ### Windsurf
178
+
179
+ Edit `~/.codeium/windsurf/mcp_config.json`:
180
+
181
+ ```json
182
+ {
183
+ "mcpServers": {
184
+ "supersubagents": {
185
+ "command": "npx",
186
+ "args": ["-y", "mcp-subagents-opencode"],
187
+ "env": {
188
+ "OPENCODE_BASE_URL": "http://127.0.0.1:19747"
189
+ }
190
+ }
191
+ }
192
+ }
193
+ ```
194
+
195
+ Or via Settings UI: `Cmd+Shift+P` > "Open Windsurf Settings" > Advanced Settings > Cascade > MCP.
196
+
197
+ ---
198
+
199
+ ### OpenAI Codex CLI
200
+
201
+ Edit `~/.codex/config.toml`:
202
+
203
+ ```toml
204
+ [[mcp.servers]]
205
+ name = "supersubagents"
206
+ command = "npx"
207
+ args = ["-y", "mcp-subagents-opencode"]
208
+
209
+ [mcp.servers.env]
210
+ OPENCODE_BASE_URL = "http://127.0.0.1:19747"
211
+ ```
212
+
213
+ Or via command:
214
+
215
+ ```bash
216
+ codex mcp add --transport stdio supersubagents -- npx -y mcp-subagents-opencode
217
+ ```
218
+
219
+ ---
220
+
221
+ ### Any MCP Client (HTTP mode)
222
+
223
+ Start the server in HTTP mode, then point your client to the URL:
224
+
225
+ ```bash
226
+ npx -y mcp-subagents-opencode
227
+ # Set MCP_TRANSPORT=http to use HTTP instead of stdio:
228
+ MCP_TRANSPORT=http npx -y mcp-subagents-opencode
229
+ # → Listening on http://127.0.0.1:51997/mcp
230
+ ```
231
+
232
+ Then configure your client to connect to `http://127.0.0.1:51997/mcp`.
233
+
234
+ ---
235
+
236
+ ## How It Works
237
+
238
+ ```
239
+ You (main session): "Spawn three agents: refactor auth, write tests, research pagination"
240
+
241
+ brave-tiger-42: Refactoring auth module... [running]
242
+ calm-falcon-17: Writing API integration tests... [running]
243
+ swift-panda-88: Researching pagination patterns... [running]
244
+
245
+ You: Continue working on other things -- or spawn more agents.
246
+ ```
247
+
248
+ Each agent runs as an isolated OpenCode headless session. When it finishes, results appear in MCP resources and output files. Task IDs are human-readable (`brave-tiger-42`, `calm-falcon-17`) for easy tracking.
249
+
250
+ ### Architecture
251
+
252
+ ```
253
+ MCP Client (Claude Code, Cursor, VS Code, Windsurf, Codex, etc.)
254
+ |
255
+ v
256
+ mcp-subagents-opencode (this server -- via npx or self-hosted)
257
+ |
258
+ v
259
+ OpenCode Headless Server (HTTP API on :19747)
260
+ |
261
+ v
262
+ AI Provider (Anthropic, OpenAI, etc. -- configured in OpenCode)
263
+ ```
264
+
265
+ ---
266
+
267
+ ## Tool Reference
268
+
269
+ 4 MCP tools for agent orchestration:
270
+
271
+ | Tool | Purpose |
272
+ |---|---|
273
+ | **`spawn_agent`** | Create a new autonomous agent with role, prompt, and context files |
274
+ | **`send_message`** | Follow up on an existing task ("now add tests", or just "continue") |
275
+ | **`cancel_task`** | Cancel one task, multiple tasks, or clear all |
276
+ | **`answer_question`** | Respond when an agent asks a clarifying question |
277
+
278
+ ### `spawn_agent`
279
+
280
+ | Parameter | Type | Required | Description |
281
+ |---|---|---|---|
282
+ | `role` | `coder` `planner` `tester` `researcher` | Yes | Agent specialization |
283
+ | `prompt` | string | Yes | Complete self-contained instructions |
284
+ | `context_files` | `[{path, description}]` | Coder/tester: yes | Files to inject into context (max 20) |
285
+ | `specialization` | string | No | Language/framework overlay (e.g. `typescript`, `react`, `playwright`) |
286
+ | `model` | string | No | `claude-sonnet-4.5` (default), `claude-haiku-4.5`, or `claude-opus-4.6` |
287
+ | `cwd` | string | No | Working directory (absolute path) |
288
+ | `timeout` | number | No | Max duration in ms (default: 1,800,000 = 30 min) |
289
+ | `depends_on` | string[] | No | Task IDs that must complete first |
290
+ | `labels` | string[] | No | Labels for grouping/filtering (max 10) |
291
+
292
+ ```json
293
+ {
294
+ "role": "coder",
295
+ "prompt": "Refactor /src/auth.ts to use JWT refresh tokens. Read the file first, then implement...",
296
+ "context_files": [{"path": "/src/auth.ts", "description": "Current auth implementation"}],
297
+ "specialization": "typescript",
298
+ "labels": ["backend", "auth"]
299
+ }
300
+ ```
301
+
302
+ ### `send_message`
303
+
304
+ | Parameter | Type | Required | Description |
305
+ |---|---|---|---|
306
+ | `task_id` | string | Yes | Task ID to continue |
307
+ | `message` | string | No | Follow-up instruction (default: `"continue"`) |
308
+
309
+ ```json
310
+ {"task_id": "brave-tiger-42", "message": "Now add unit tests for the changes you made"}
311
+ ```
312
+
313
+ ### `cancel_task`
314
+
315
+ ```json
316
+ {"task_id": "brave-tiger-42"}
317
+ {"task_id": ["brave-tiger-42", "calm-falcon-17"]}
318
+ {"task_id": "all", "clear": true, "confirm": true}
319
+ ```
320
+
321
+ ### `answer_question`
322
+
323
+ ```json
324
+ {"task_id": "brave-tiger-42", "answer": "2"}
325
+ {"task_id": "brave-tiger-42", "answer": "CUSTOM: Use TypeScript instead"}
326
+ ```
327
+
328
+ ---
329
+
330
+ ## MCP Resources
331
+
332
+ Live status monitoring without polling:
333
+
334
+ | Resource URI | Content |
335
+ |---|---|
336
+ | `system:///status` | OpenCode connection, task counts by status, pending questions |
337
+ | `task:///all` | All tasks with IDs, statuses, labels, session IDs, timestamps |
338
+ | `task:///{id}` | Single task detail: progress, output tail, error info, model, CWD |
339
+
340
+ Resources support subscriptions (`resources/subscribe`) for real-time change notifications.
341
+
342
+ ### Output Files
343
+
344
+ Every task streams its execution log to `{cwd}/.super-agents/{task-id}.output`:
345
+
346
+ ```bash
347
+ tail -f .super-agents/brave-tiger-42.output # Follow live
348
+ tail -20 .super-agents/brave-tiger-42.output # Last 20 lines
349
+ ```
350
+
351
+ ---
352
+
353
+ ## Agent Templates
354
+
355
+ Templates provide specialized system prompts. Your prompt is wrapped with role-specific instructions.
356
+
357
+ | Role | Template | Behavior |
358
+ |---|---|---|
359
+ | `coder` | `super-coder` | "Think 10 times, write once." Searches codebase before changes. Verifies after. |
360
+ | `planner` | `super-planner` | "Plan with evidence." Explores first, designs atomic tasks. Always uses opus. |
361
+ | `researcher` | `super-researcher` | "Find truth, not confirmation." Multi-angle investigation. |
362
+ | `tester` | `super-tester` | "Test like a user." E2E first, then integration, then unit. |
363
+
364
+ ### Specialization Overlays
365
+
366
+ Add a `specialization` to get language/framework-specific instructions layered on top:
367
+
368
+ **Coder:** `typescript` `python` `react` `nextjs` `vue` `go` `rust` `java` `kotlin` `swift` `ruby` `csharp` `tauri` `supabase` `supastarter` `triggerdev`
369
+
370
+ **Planner:** `feature` `bugfix` `migration` `refactor` `architecture`
371
+
372
+ **Tester:** `playwright` `rest` `graphql` `suite`
373
+
374
+ **Researcher:** `security` `library` `performance`
375
+
376
+ ```json
377
+ {"role": "coder", "specialization": "react", "prompt": "Build a dashboard component..."}
378
+ ```
379
+
380
+ ---
381
+
382
+ ## Models
383
+
384
+ | Model | Usage |
385
+ |---|---|
386
+ | `claude-sonnet-4.5` | **Default.** Best balance of speed and capability. |
387
+ | `claude-haiku-4.5` | Fast, simple tasks. Quick iterations. |
388
+ | `claude-opus-4.6` | Complex reasoning. Set `ENABLE_OPUS=true` to show in tool descriptions. Always available via alias. |
389
+
390
+ > `planner` role always uses `claude-opus-4.6` regardless of the `model` parameter.
391
+
392
+ ---
393
+
394
+ ## Task Dependencies
395
+
396
+ Chain tasks with `depends_on`. Dependent tasks wait in `waiting` status until all dependencies complete.
397
+
398
+ ```
399
+ spawn_agent(role: "planner") --> plan-tiger-42 [running]
400
+ spawn_agent(role: "coder",
401
+ depends_on: ["plan-tiger-42"]) --> code-falcon-17 [waiting]
402
+ spawn_agent(role: "tester",
403
+ depends_on: ["code-falcon-17"]) --> test-panda-88 [waiting]
404
+
405
+ plan-tiger-42 completes --> code-falcon-17 auto-starts
406
+ code-falcon-17 completes --> test-panda-88 auto-starts
407
+ ```
408
+
409
+ Circular dependencies are detected and rejected at spawn time.
410
+
411
+ ---
412
+
413
+ ## Task Lifecycle
414
+
415
+ ```
416
+ pending --> running --> completed
417
+ --> failed
418
+ --> cancelled
419
+ --> timed_out
420
+ --> rate_limited --> (auto-retry) --> pending --> running
421
+
422
+ pending --> waiting (dependencies) --> pending --> running
423
+ ```
424
+
425
+ ---
426
+
427
+ ## Environment Variables
428
+
429
+ | Variable | Default | Description |
430
+ |---|---|---|
431
+ | `OPENCODE_BASE_URL` | `http://127.0.0.1:19747` | OpenCode headless server URL |
432
+ | `OPENCODE_SERVER_USERNAME` | -- | Basic auth username (if OpenCode requires it) |
433
+ | `OPENCODE_SERVER_PASSWORD` | -- | Basic auth password |
434
+ | `ENABLE_OPUS` | `false` | Show `claude-opus-4.6` in tool descriptions |
435
+ | `MCP_TRANSPORT` | `stdio` | Transport mode: `stdio` or `http` |
436
+ | `MCP_PORT` | `51997` | HTTP transport port (when `MCP_TRANSPORT=http`) |
437
+ | `MCP_TASK_TIMEOUT_MS` | `1800000` (30 min) | Default task timeout |
438
+ | `MCP_TASK_TIMEOUT_MAX_MS` | `3600000` (1 hr) | Maximum allowed timeout |
439
+ | `MCP_TASK_STALL_WARN_MS` | `300000` (5 min) | No-output warning threshold |
440
+ | `DEBUG_NOTIFICATIONS` | `false` | Log MCP notification errors to stderr |
441
+
442
+ ---
443
+
444
+ ## Transport Modes
445
+
446
+ | Mode | Best For | How to Start |
447
+ |---|---|---|
448
+ | **STDIO** (default) | Claude Code, Claude Desktop, Cursor, VS Code | `npx -y mcp-subagents-opencode` |
449
+ | **HTTP Streamable** | Self-hosted, Docker, multi-client, LAN sharing | `MCP_TRANSPORT=http npx -y mcp-subagents-opencode` |
450
+
451
+ > **STDIO caveat:** STDIO transport closes when the MCP client disconnects. Tasks that are still running continue in the OpenCode server, but MCP notifications can't be delivered until the client reconnects. Output files are always written regardless of transport.
452
+
453
+ ### HTTP Transport
454
+
455
+ ```bash
456
+ MCP_TRANSPORT=http npx -y mcp-subagents-opencode
457
+ # Listening on http://127.0.0.1:51997/mcp
458
+ ```
459
+
460
+ Custom port:
461
+
462
+ ```bash
463
+ MCP_TRANSPORT=http MCP_PORT=8080 npx -y mcp-subagents-opencode
464
+ ```
465
+
466
+ Endpoints:
467
+ - `POST /mcp` -- MCP Streamable HTTP (session management)
468
+ - `GET /health` -- Health check (JSON)
469
+
470
+ ---
471
+
472
+ ## Development
473
+
474
+ ```bash
475
+ git clone https://github.com/yigitkonur/mcp-subagents-opencode.git
476
+ cd mcp-subagents-opencode
477
+
478
+ npm install
479
+ npm run build # TypeScript compile + copy MDX templates
480
+
481
+ # Watch mode
482
+ npm run dev
483
+
484
+ # Run
485
+ npm start
486
+ ```
487
+
488
+ ### Project Structure
489
+
490
+ ```
491
+ src/
492
+ index.ts # Bootstrap, transport setup
493
+ models.ts # Model definitions and resolution
494
+ types.ts # Core type definitions
495
+ tools/
496
+ spawn-agent.ts # spawn_agent tool
497
+ send-message.ts # send_message tool
498
+ cancel-task.ts # cancel_task tool
499
+ answer-question.ts # answer_question tool
500
+ shared-spawn.ts # Shared spawn logic
501
+ services/
502
+ opencode-client.ts # OpenCode HTTP API client
503
+ opencode-spawner.ts # Session creation and message dispatch
504
+ task-manager.ts # Task lifecycle, persistence, output files
505
+ retry-queue.ts # Exponential backoff retry (5m->2h, 6 retries)
506
+ question-registry.ts # Pending question tracking
507
+ client-context.ts # MCP client roots and CWD
508
+ task-persistence.ts # JSON persistence to ~/.super-agents/
509
+ output-file.ts # Output file writer
510
+ server/
511
+ register-tools.ts # MCP tool handler registration
512
+ register-tasks.ts # MCP task primitive handlers
513
+ register-resources.ts # MCP resource handlers
514
+ register-notifications.ts # Change notification wiring
515
+ register-retry-execution.ts # Retry and execution callbacks
516
+ templates/
517
+ index.ts # Template loader
518
+ super-coder.mdx # 4 base role templates
519
+ overlays/ # 28 specialization overlays
520
+ coder-typescript.mdx
521
+ planner-feature.mdx
522
+ tester-playwright.mdx
523
+ researcher-security.mdx
524
+ ...
525
+ config/
526
+ timeouts.ts # Timeout constants
527
+ utils/
528
+ format.ts # Output formatting
529
+ sanitize.ts # Input validation
530
+ task-id.ts # Human-readable ID generator
531
+ ```
532
+
533
+ ---
534
+
535
+ ## Troubleshooting
536
+
537
+ <details>
538
+ <summary><strong>Tasks fail with "OpenCode server not available"</strong></summary>
539
+
540
+ The OpenCode headless server must be running before spawning agents.
541
+
542
+ ```bash
543
+ # Start OpenCode
544
+ opencode serve
545
+
546
+ # Verify
547
+ curl -s -H 'Accept: application/json' http://127.0.0.1:19747/session | head -c 100
548
+ ```
549
+
550
+ Make sure `OPENCODE_BASE_URL` matches the port OpenCode is running on.
551
+
552
+ </details>
553
+
554
+ <details>
555
+ <summary><strong>Tasks spawn but results never appear (STDIO mode)</strong></summary>
556
+
557
+ STDIO transport closes when the MCP client disconnects. The task continues running in OpenCode, but MCP can't deliver notifications.
558
+
559
+ **Solutions:**
560
+ 1. Check the output file directly: `tail -f .super-agents/{task-id}.output`
561
+ 2. Use HTTP transport for persistent sessions: `MCP_TRANSPORT=http`
562
+ 3. Reconnect and read the resource: `task:///{task-id}`
563
+
564
+ </details>
565
+
566
+ <details>
567
+ <summary><strong>Empty or no response from agents</strong></summary>
568
+
569
+ - Verify OpenCode has a configured AI provider (Anthropic API key, etc.)
570
+ - Check the OpenCode server logs for errors
571
+ - Try a simple test: `curl -X POST http://127.0.0.1:19747/session` to verify session creation works
572
+
573
+ </details>
574
+
575
+ <details>
576
+ <summary><strong>Agent produces poor results</strong></summary>
577
+
578
+ - Agents run in isolation -- your prompt is their **ONLY** context. Include all file paths, background, and success criteria.
579
+ - For coders: provide at least 1000 characters with OBJECTIVE, FILES, CRITERIA, CONSTRAINTS, PATTERNS.
580
+ - Attach `context_files` with `.md` plans or specifications.
581
+ - Use `specialization` to activate language-specific templates (e.g., `typescript`, `react`).
582
+
583
+ </details>
584
+
585
+ <details>
586
+ <summary><strong>How to check running tasks</strong></summary>
587
+
588
+ ```bash
589
+ # Via output files
590
+ ls -la .super-agents/*.output
591
+ tail -f .super-agents/brave-tiger-42.output
592
+ ```
593
+
594
+ Or read MCP resources: `system:///status`, `task:///all`, `task:///{id}`
595
+
596
+ </details>
597
+
598
+ ---
599
+
600
+ <p align="center">
601
+ <strong>MIT License</strong> &mdash; <a href="https://github.com/yigitkonur">Yigit Konur</a>
602
+ </p>
@@ -0,0 +1,9 @@
1
+ /**
2
+ * Centralized timeout configuration with optional environment overrides.
3
+ */
4
+ export declare const TASK_TIMEOUT_MIN_MS: number;
5
+ export declare const TASK_TIMEOUT_MAX_MS: number;
6
+ export declare const TASK_TIMEOUT_DEFAULT_MS: number;
7
+ export declare const TASK_STALL_WARN_MS: number;
8
+ export declare const TASK_TTL_MS: number;
9
+ //# sourceMappingURL=timeouts.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"timeouts.d.ts","sourceRoot":"","sources":["../../src/config/timeouts.ts"],"names":[],"mappings":"AAAA;;GAEG;AAUH,eAAO,MAAM,mBAAmB,QAA+C,CAAC;AAChF,eAAO,MAAM,mBAAmB,QAAmD,CAAC;AACpF,eAAO,MAAM,uBAAuB,QAA+C,CAAC;AACpF,eAAO,MAAM,kBAAkB,QAAmD,CAAC;AAGnF,eAAO,MAAM,WAAW,QAA2C,CAAC"}
@@ -0,0 +1,18 @@
1
+ /**
2
+ * Centralized timeout configuration with optional environment overrides.
3
+ */
4
+ function readIntEnv(name, fallback) {
5
+ const raw = process.env[name];
6
+ if (!raw)
7
+ return fallback;
8
+ const value = Number(raw);
9
+ return Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback;
10
+ }
11
+ // Task execution timeout bounds
12
+ export const TASK_TIMEOUT_MIN_MS = readIntEnv('MCP_TASK_TIMEOUT_MIN_MS', 1_000);
13
+ export const TASK_TIMEOUT_MAX_MS = readIntEnv('MCP_TASK_TIMEOUT_MAX_MS', 3_600_000);
14
+ export const TASK_TIMEOUT_DEFAULT_MS = readIntEnv('MCP_TASK_TIMEOUT_MS', 1_800_000);
15
+ export const TASK_STALL_WARN_MS = readIntEnv('MCP_TASK_STALL_WARN_MS', 5 * 60_000);
16
+ // Task retention: how long completed/failed tasks stay in memory before cleanup
17
+ export const TASK_TTL_MS = readIntEnv('MCP_TASK_TTL_MS', 3_600_000); // 1 hour
18
+ //# sourceMappingURL=timeouts.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"timeouts.js","sourceRoot":"","sources":["../../src/config/timeouts.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,SAAS,UAAU,CAAC,IAAY,EAAE,QAAgB;IAChD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,CAAC,GAAG;QAAE,OAAO,QAAQ,CAAC;IAC1B,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC1B,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;AAC5E,CAAC;AAED,gCAAgC;AAChC,MAAM,CAAC,MAAM,mBAAmB,GAAG,UAAU,CAAC,yBAAyB,EAAE,KAAK,CAAC,CAAC;AAChF,MAAM,CAAC,MAAM,mBAAmB,GAAG,UAAU,CAAC,yBAAyB,EAAE,SAAS,CAAC,CAAC;AACpF,MAAM,CAAC,MAAM,uBAAuB,GAAG,UAAU,CAAC,qBAAqB,EAAE,SAAS,CAAC,CAAC;AACpF,MAAM,CAAC,MAAM,kBAAkB,GAAG,UAAU,CAAC,wBAAwB,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC;AAEnF,gFAAgF;AAChF,MAAM,CAAC,MAAM,WAAW,GAAG,UAAU,CAAC,iBAAiB,EAAE,SAAS,CAAC,CAAC,CAAC,SAAS"}
@@ -0,0 +1,6 @@
1
+ /**
2
+ * Helpers for OpenCode API response processing.
3
+ */
4
+ export declare function resolveSessionStatus(raw: unknown): string;
5
+ export declare function formatMessageResponse(response: unknown): string;
6
+ //# sourceMappingURL=helpers.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAazD;AAED,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,CA0B/D"}