@serkanalgur/opencode-nexus 1.7.0 → 1.8.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 (4) hide show
  1. package/README.md +234 -331
  2. package/dist/index.js +1165 -50
  3. package/dist/tui.js +174 -13
  4. package/package.json +1 -1
package/README.md CHANGED
@@ -3,13 +3,15 @@
3
3
  <img src="./assets/banner.svg" alt="OpenCode Nexus" width="100%" />
4
4
 
5
5
  [![npm version](https://img.shields.io/npm/v/@serkanalgur/opencode-nexus?style=flat-square&color=6366f1)](https://www.npmjs.com/package/@serkanalgur/opencode-nexus)
6
+ [![npm downloads](https://img.shields.io/npm/dw/@serkanalgur/opencode-nexus?style=flat-square&color=22c55e)](https://www.npmjs.com/package/@serkanalgur/opencode-nexus)
6
7
  [![license](https://img.shields.io/npm/l/@serkanalgur/opencode-nexus?style=flat-square&color=8b5cf6)](https://github.com/serkanalgur/opencode-nexus/blob/main/LICENSE)
7
8
  [![opencode](https://img.shields.io/badge/OpenCode-V2-6366f1?style=flat-square)](https://opencode.ai)
8
9
  [![typescript](https://img.shields.io/badge/TypeScript-5.5+-3178c6?style=flat-square)](https://www.typescriptlang.org/)
10
+ [![sponsor](https://img.shields.io/badge/Sponsor-GitHub-ea4aaa?style=flat-square&logo=github)](https://github.com/sponsors/serkanalgur)
9
11
 
10
12
  **Adaptive Multi-Agent Orchestration with Cost Intelligence**
11
13
 
12
- [Installation](#installation) • [Quick Start](#quick-start) • [Features](#features) • [TUI Commands](#tui-commands) • [Tools](#tools) • [Configuration](#configuration) • [Development](#development) • [Contributing](#contributing)
14
+ [Installation](#installation) • [Quick Start](#quick-start) • [Features](#features) • [Agents](#agents) • [Tools](#tools) • [Configuration](#configuration) • [Development](#development)
13
15
 
14
16
  </div>
15
17
 
@@ -17,7 +19,7 @@
17
19
 
18
20
  ## What is OpenCode Nexus?
19
21
 
20
- OpenCode Nexus is an agent orchestration plugin for [OpenCode V2](https://opencode.ai) that spawns **real sub-agent sessions** with **cost-aware routing**, **DAG-based task execution**, **self-healing**, and a **TUI dashboard**.
22
+ OpenCode Nexus is an agent orchestration plugin for [OpenCode V2](https://opencode.ai) that spawns **real sub-agent sessions** with **cost-aware routing**, **DAG-based task execution**, **self-healing**, and a **TUI/web dashboard**.
21
23
 
22
24
  ### Key Capabilities
23
25
 
@@ -30,10 +32,15 @@ OpenCode Nexus is an agent orchestration plugin for [OpenCode V2](https://openco
30
32
  | **Self-Healing** | Retries with exponential backoff, context transfer, escalation policies |
31
33
  | **Web Dashboard** | Real-time monitoring via HTTP + WebSocket server on port 4747 |
32
34
  | **TUI Dashboard** | Monitor agents, budget, and config from the terminal |
35
+ | **Team Mode** | Lead agent orchestrates specialist agents in parallel |
36
+ | **Todo & Goal Tracking** | Enforce task completion, persist objectives across sessions |
33
37
  | **Persistent Memory** | SQLite-backed memory store with TTL and search |
34
38
  | **Learning Module** | Pattern recognition from failures, confidence scoring |
35
39
  | **JSONC Config** | Read/write project and global config files with comments |
36
- | **Slash Commands** | `/nexus`, `/nexus-dashboard`, `/nexus-model`, and more |
40
+ | **LSP Integration** | Auto-enabled for TypeScript, Python, Go, and 30+ languages |
41
+ | **AST-Grep** | Pattern-aware code search and rewriting |
42
+ | **Security Scanning** | Automated secrets and vulnerability detection |
43
+ | **Slash Commands** | `/nexus`, `/nexus web`, `/nexus review`, and more |
37
44
 
38
45
  ---
39
46
 
@@ -50,157 +57,149 @@ bun add -g @serkanalgur/opencode-nexus
50
57
  opencode plugin @serkanalgur/opencode-nexus --global
51
58
  ```
52
59
 
53
- Or manually add to `~/.config/opencode/opencode.json`:
60
+ Or manually add to `~/.config/opencode/opencode.jsonc`:
54
61
 
55
- ```json
62
+ ```jsonc
56
63
  {
57
64
  "plugins": ["@serkanalgur/opencode-nexus"]
58
65
  }
59
66
  ```
60
67
 
68
+ ### Auto-Setup
69
+
70
+ On first load, Nexus automatically:
71
+ - Creates `nexus-orchestrator` agent in `~/.config/opencode/agents/`
72
+ - Creates subagent files: `nexus-coder`, `nexus-explorer`, `nexus-reviewer`, `nexus-tester`, `nexus-architect`, `nexus-documenter`
73
+ - Enables LSP in OpenCode config
74
+ - Configures agent models from `.opencode/nexus.jsonc`
75
+
61
76
  ---
62
77
 
63
78
  ## Quick Start
64
79
 
65
80
  ### 1. Configure Agent Models
66
81
 
67
- Press **Ctrl+N** or type `/nexus` to open the configuration dialog and select models for each agent role.
82
+ Press **Ctrl+N** or type `/nexus` to open the configuration dialog. Select where to save (project or global).
68
83
 
69
- ### 2. Use Slash Commands
84
+ ### 2. Use the Nexus Orchestrator
85
+
86
+ Select `nexus-orchestrator` as your primary agent, then:
70
87
 
71
88
  ```
72
- /nexus # Open full configuration
73
- /nexus config # Configure models & budget
74
- /nexus status # Show config summary
75
- /nexus dashboard # Show dashboard
76
- /nexus model # Select model for a role
77
- /nexus reset # Reset to defaults
78
- ```
89
+ # Spawn agents for tasks
90
+ Use nexus.spawn with role="coder" and task="Implement JWT auth"
79
91
 
80
- ### 3. Spawn Agents via Tools
92
+ # Wait for completion and get results
93
+ Use nexus.spawn with role="reviewer" and task="Review the implementation" and wait=true
81
94
 
82
- From any agent prompt, use the nexus tools:
95
+ # Delegate (convenience wrapper)
96
+ Use nexus.delegate with role="tester" and task="Write tests for auth module"
83
97
 
84
- ```
85
- Use the nexus.spawn tool to create a coder agent for implementing JWT auth
86
- Use the nexus.status tool to check orchestrator state
87
- Use the nexus.agents tool to list all spawned agents
88
- Use the nexus.costs tool to see cost breakdown
98
+ # Check progress
99
+ Use nexus.sessions
100
+
101
+ # Track goals
102
+ Use nexus.goal.set with description="Build complete auth system"
89
103
  ```
90
104
 
91
- ### 4. Programmatic Usage
105
+ ### 3. Use Slash Commands
92
106
 
93
- ```typescript
94
- import { NexusOrchestrator } from '@serkanalgur/opencode-nexus'
107
+ ```
108
+ /nexus # Open full configuration
109
+ /nexus web # Start web dashboard (open http://localhost:4747)
110
+ /nexus review # Quick code review
111
+ /nexus fix # Quick fix for last error
112
+ /nexus explain # Explain last change
113
+ ```
95
114
 
96
- const orchestrator = new NexusOrchestrator({
97
- budget: { maxTotalCost: 10.00 }
98
- })
115
+ ---
99
116
 
100
- // Initialize with OpenCode context (done automatically by plugin)
101
- orchestrator.initialize(ctx)
117
+ ## Features
102
118
 
103
- // Spawn a real agent session
104
- const agent = await orchestrator.spawnAgent({ role: 'coder' })
119
+ ### Cost-Aware Model Selection
105
120
 
106
- // Execute tasks in DAG
107
- const result = await orchestrator.execute({
108
- tasks: [
109
- {
110
- id: 'task-1',
111
- name: 'Implement auth',
112
- description: 'Add JWT authentication',
113
- requiredRole: 'coder',
114
- complexity: { overall: 60, factors: { fileCount: 3, codeLines: 200, dependencyDepth: 2, domainKnowledge: 40, riskLevel: 'medium' } },
115
- dependencies: [],
116
- files: { include: ['src/auth/**'] },
117
- priority: 'high',
118
- status: 'pending'
119
- }
120
- ]
121
- })
121
+ Models are configured per role in `.opencode/nexus.jsonc`. Nexus scores models by quality, cost, and speed — then picks the optimal one:
122
122
 
123
- console.log(`Completed in ${result.totalDuration}ms, cost: $${result.totalCost}`)
123
+ ```jsonc
124
+ {
125
+ "models": {
126
+ "architect": "opencode/muse-spark-1.3-contributor-free",
127
+ "coder": "opencode/mimo-v2.6-flash-free",
128
+ "reviewer": "opencode/muse-spark-1.2-contributor-free",
129
+ "tester": "opencode-go/mimo-v2.5",
130
+ "explorer": "opencode/big-pickle",
131
+ "documenter": "opencode/big-pickle"
132
+ }
133
+ }
124
134
  ```
125
135
 
126
- ---
136
+ When you call `nexus.spawn(role="coder")`, the coder model from config is used automatically.
127
137
 
128
- ## Features
138
+ ### Self-Healing with Escalation
129
139
 
130
- ### Real OpenCode Sessions
140
+ Failed tasks follow a 4-step escalation chain:
131
141
 
132
- Each agent runs in its own OpenCode session with the correct model and role-specific system prompt:
142
+ 1. **Retry** — Exponential backoff (1s, 2s, 4s...)
143
+ 2. **Respawn** — Collect context, spawn new agent with transferred state
144
+ 3. **Fallback Model** — Try cheaper alternative model
145
+ 4. **Alert** — Emit escalation event, mark as failed
133
146
 
134
- ```typescript
135
- // Creates a real OpenCode session with descriptive title
136
- const session = await ctx.session.create({
137
- title: '💻 Coder — anthropic/claude-sonnet-4-6',
138
- agent: 'build',
139
- model: { providerID: 'anthropic', id: 'claude-sonnet-4-6' }
140
- })
147
+ ### Web Dashboard
148
+
149
+ Real-time monitoring via embedded HTTP + WebSocket server:
141
150
 
142
- // Sends the task prompt
143
- await ctx.session.prompt({ sessionID: session.id, text: 'You are a senior software engineer...' })
151
+ ```
152
+ nexus.dashboard.start(port=4747) # Start server
153
+ # Open http://localhost:4747 in browser
144
154
  ```
145
155
 
146
- ### Role-Specific System Prompts
156
+ Features: Agent grid, cost tracker, DAG visualization, activity log, config editor, auto-refresh.
147
157
 
148
- Each agent role gets a specialized prompt:
158
+ ### Team Mode
149
159
 
150
- | Role | OpenCode Agent | Focus |
151
- |------|----------------|-------|
152
- | **Architect** | `architect` | System design, architecture patterns, high-level decisions |
153
- | **Coder** | `build-orchestrator` | Clean, efficient code following best practices |
154
- | **Reviewer** | `code-reviewer` | Code review for correctness, security, performance |
155
- | **Tester** | `build-orchestrator` | Comprehensive tests, edge cases, quality assurance |
156
- | **Explorer** | `explore` | Codebase navigation, architecture analysis |
157
- | **Documenter** | `doc-writer` | Clear technical documentation |
160
+ Create a team of specialist agents working in parallel:
158
161
 
159
- ### Cost-Aware Model Selection
162
+ ```
163
+ nexus.team.create(name="auth-team", leadRole="architect")
164
+ nexus.team.addMember(teamId="...", role="coder", model="opencode/mimo-v2.6-flash-free")
165
+ nexus.team.addMember(teamId="...", role="reviewer", model="opencode/muse-spark-1.2-contributor-free")
166
+ nexus.team.activate(teamId="...")
167
+ ```
160
168
 
161
- Nexus scores models by quality, cost, and speed — then picks the optimal one per task complexity:
169
+ ### Todo & Goal Tracking
162
170
 
163
- ```typescript
164
- // High-complexity tasks favor quality models
165
- // Low-complexity tasks favor cheap/fast models
166
- // Budget remaining filters out unaffordable models
171
+ Track tasks and persist objectives across sessions:
167
172
 
168
- const result = orchestrator.selectBestModel('coder', complexityScore)
169
- // → { provider: 'anthropic', model: 'claude-sonnet-4-6', overallScore: 0.82 }
170
173
  ```
174
+ nexus.todo.add(description="Implement auth middleware")
175
+ nexus.todo.list()
176
+ nexus.todo.complete(id="...")
171
177
 
172
- ### Self-Healing with Escalation
178
+ nexus.goal.set(description="Build complete auth system")
179
+ nexus.goal.status()
180
+ nexus.goal.complete()
181
+ ```
173
182
 
174
- Failed tasks follow a 4-step escalation chain:
183
+ ### LSP Integration
175
184
 
176
- 1. **Retry** — Exponential backoff (1s, 2s, 4s...)
177
- 2. **Respawn** — Collect context, spawn new agent with transferred state
178
- 3. **Fallback Model** — Try cheaper alternative model
179
- 4. **Alert** — Emit escalation event, mark as failed
185
+ OpenCode's built-in LSP servers are auto-enabled. Supports 30+ languages including TypeScript, Python, Go, Rust, and more.
180
186
 
181
- ```typescript
182
- const orchestrator = new NexusOrchestrator({
183
- selfHealing: {
184
- enabled: true,
185
- maxRetries: 3,
186
- contextTransfer: true
187
- }
188
- })
189
- ```
187
+ ### AST-Grep
190
188
 
191
- ### Web Dashboard
189
+ Pattern-aware code search and rewriting:
192
190
 
193
- Real-time monitoring via embedded HTTP + WebSocket server:
191
+ ```
192
+ nexus.astgrep.search(pattern="console.log($$$)", language="typescript", directory="src/")
193
+ nexus.astgrep.rewrite(pattern="var $X", rewrite="const $X", language="typescript", directory="src/")
194
+ ```
194
195
 
195
- ```bash
196
- # Start dashboard
197
- Use nexus.dashboard.start with port=4747
196
+ ### Security Scanning
198
197
 
199
- # Open in browser
200
- open http://localhost:4747
201
- ```
198
+ Automated secrets and vulnerability detection:
202
199
 
203
- Features: Agent grid, cost tracker, DAG visualization, activity log, config panel.
200
+ ```
201
+ nexus.security.scan(content="const API_KEY = \"sk-123\"", filename="config.ts")
202
+ ```
204
203
 
205
204
  ### Persistent Memory
206
205
 
@@ -215,9 +214,6 @@ orchestrator.memoryStore.set({
215
214
  confidence: 0.9,
216
215
  tags: ['api', 'design']
217
216
  })
218
-
219
- // Search across all memory
220
- const results = orchestrator.memoryStore.search('api pattern')
221
217
  ```
222
218
 
223
219
  ### Learning Module
@@ -225,36 +221,12 @@ const results = orchestrator.memoryStore.search('api pattern')
225
221
  Records failure patterns and solutions, building confidence over time:
226
222
 
227
223
  ```typescript
228
- // Automatically records failures during execution
229
- // Finds similar past failures and suggests solutions
230
- // Confidence increases with successful reuse
231
-
232
224
  const solutions = orchestrator.learning.findSolutions('TypeScript TS2345 error')
233
225
  // → [{ entry: { solution: 'Add type cast', confidence: 0.85 }, similarity: 0.7 }]
234
226
  ```
235
227
 
236
- ### JSONC Configuration
237
-
238
- Read and write config files with comments:
239
-
240
- ```jsonc
241
- // .opencode/nexus.jsonc (project-level)
242
- {
243
- // Agent models for each role
244
- "models": {
245
- "architect": "anthropic/claude-sonnet-4-6",
246
- "coder": "opencode-go/mimo-v2.5"
247
- },
248
- "budget": { "maxTotalCost": 10.00 }
249
- }
250
- ```
251
-
252
- Precedence: project > global > TUI > defaults.
253
-
254
228
  ### Preset Configurations
255
229
 
256
- Quickly apply predefined configs:
257
-
258
230
  | Preset | Models | Budget | Self-Healing |
259
231
  |--------|--------|--------|--------------|
260
232
  | **minimal** | Gemini Flash | $1 | Off |
@@ -262,184 +234,133 @@ Quickly apply predefined configs:
262
234
  | **enterprise** | Top-tier | $50 | On (5 retries) |
263
235
  | **cost-optimized** | Cheapest | $3 | On (2 retries) |
264
236
 
265
- ### Composable Modules
266
-
267
- Extend Nexus with custom modules:
268
-
269
- ```typescript
270
- import { NexusPlugin } from '@serkanalgur/opencode-nexus'
271
-
272
- NexusPlugin.register({
273
- name: 'my-custom-module',
274
- description: 'Custom feature',
275
- version: '1.0.0',
276
- setup: async (ctx) => { /* ... */ },
277
- teardown: async () => { /* ... */ }
278
- })
279
- ```
280
-
281
- ### Custom Agent Roles
282
-
283
- Define your own agent roles with custom prompts:
284
-
285
- ```jsonc
286
- // .opencode/nexus.jsonc
287
- {
288
- "customRoles": [
289
- {
290
- "name": "security-auditor",
291
- "displayName": "Security Auditor",
292
- "emoji": "🔐",
293
- "prompt": "You are a security auditor. Focus on OWASP Top 10, vulnerability scanning, and security best practices.",
294
- "model": "anthropic/claude-sonnet-4-6"
295
- }
296
- ]
297
- }
298
- ```
299
-
300
- Or register dynamically via tools: `nexus.roles.add(name="security-auditor", displayName="Security Auditor", prompt="...")`
301
-
302
- ### Execution History
303
-
304
- Track all task executions with costs, durations, and outcomes:
305
-
306
- ```
307
- nexus.history.list(count=10) — Recent executions
308
- nexus.history.stats() — Success rate, avg cost, breakdown by role
309
- ```
310
-
311
- ### Cost Forecasting
312
-
313
- Predict costs before executing tasks:
237
+ ---
314
238
 
315
- ```typescript
316
- const forecast = orchestrator.forecaster.forecastAll([
317
- { task: myTask, role: 'coder', model: 'claude-sonnet-4-6', complexity: score }
318
- ], budgetRemaining)
319
- // → { totalEstimatedCost: 0.0234, withinBudget: true }
320
- ```
239
+ ## Agents
321
240
 
322
- ### Agent Performance Scoring
241
+ Nexus creates 7 agent files in `~/.config/opencode/agents/`:
323
242
 
324
- Track which model/role combinations work best:
243
+ | Agent | Mode | Purpose |
244
+ |-------|------|---------|
245
+ | `nexus-orchestrator` | primary | Main orchestrator — decompose, dispatch, integrate |
246
+ | `nexus-architect` | subagent | System design and architecture |
247
+ | `nexus-coder` | subagent | Implement code tasks |
248
+ | `nexus-reviewer` | subagent | Code review (read-only) |
249
+ | `nexus-tester` | subagent | Write and run tests |
250
+ | `nexus-explorer` | subagent | Explore codebases (read-only) |
251
+ | `nexus-documenter` | subagent | Write documentation |
325
252
 
326
- ```
327
- nexus.performance.scores() — All model/role scores
328
- nexus.performance.best(role="coder") — Best model for a role
329
- ```
253
+ ### Clarify Skill
330
254
 
331
- Score = 40% success rate + 30% speed + 30% cost efficiency.
332
-
333
- ### Git Worktree Per Agent
334
-
335
- Each agent works in its own isolated git worktree:
255
+ When instructions are ambiguous, use `nexus.clarify`:
336
256
 
337
257
  ```
338
- nexus.worktree.enable() — Enable isolation
339
- nexus.worktree.list() — List active worktrees
340
- nexus.worktree.disable() — Clean up all
258
+ nexus.clarify(question="Should I use JWT or OAuth?", options="JWT, OAuth", assumption="JWT")
341
259
  ```
342
260
 
343
261
  ---
344
262
 
345
- ## TUI Commands
346
-
347
- | Command | Alias | Description |
348
- |---------|-------|-------------|
349
- | `/nexus` | — | Open full configuration dialog |
350
- | `/nexus config` | `/nc` | Configure models & budget |
351
- | `/nexus dashboard` | `/nd` | Show dashboard with models, budget, commands |
352
- | `/nexus model` | `/nm` | Select model for a role |
353
- | `/nexus status` | `/ns` | Show config summary |
354
- | `/nexus reset` | — | Reset all settings to defaults |
355
-
356
- **Keyboard shortcut:** `Ctrl+N` opens the main configuration dialog.
357
-
358
- ---
359
-
360
263
  ## Tools
361
264
 
362
- Register these tools in your agent prompts:
363
-
364
265
  | Tool | Description | Input |
365
266
  |------|-------------|-------|
366
- | `nexus.status` | Orchestrator status | `{ detailed?: boolean }` |
367
- | `nexus.agents` | List spawned agents | `{ filter?: string }` |
267
+ | `nexus.spawn` | Spawn a sub-agent | `{ role, task, model?, wait?, timeout? }` |
268
+ | `nexus.delegate` | Spawn + wait + result | `{ role, task, model?, timeout? }` |
269
+ | `nexus.sessions` | List active sessions | `{}` |
270
+ | `nexus.background` | Move agents to background | `{}` |
271
+ | `nexus.result` | Get agent result | `{ sessionID }` |
272
+ | `nexus.status` | Orchestrator status | `{ detailed? }` |
368
273
  | `nexus.costs` | Cost report & budget | `{}` |
369
- | `nexus.dashboard` | Full state for dashboard | `{}` |
370
- | `nexus.spawn` | Spawn a sub-agent | `{ role: string, task: string, model?: string }` |
371
- | `nexus.queue` | Show task queue with priorities | `{}` |
274
+ | `nexus.forecast` | Predict costs | `{ tasks }` |
275
+ | `nexus.model.costs` | Show/set model pricing | `{ model?, setInput?, setOutput? }` |
276
+ | `nexus.preset` | Apply preset config | `{ name }` |
372
277
  | `nexus.config.save` | Save config to disk | `{ level: 'project' \| 'global' }` |
373
- | `nexus.config.init` | Initialize config files | `{ level: 'project' \| 'global' \| 'both' }` |
374
- | `nexus.dashboard.start` | Start web dashboard | `{ port?: number, host?: string }` |
278
+ | `nexus.config.init` | Initialize config files | `{ level }` |
279
+ | `nexus.dashboard.start` | Start web dashboard | `{ port?, host? }` |
375
280
  | `nexus.dashboard.stop` | Stop web dashboard | `{}` |
376
- | `nexus.preset` | Apply preset config | `{ name: string }` |
377
- | `nexus.template` | List/instantiate templates | `{ name?: string, baseDir?: string }` |
378
- | `nexus.model.costs` | Show/set model pricing | `{ model?: string, setInput?: number, setOutput?: number }` |
379
- | `nexus.security.scan` | Scan code for security issues | `{ content: string, filename?: string }` |
380
- | `nexus.roles.list` | List custom agent roles | `{}` |
381
- | `nexus.roles.add` | Add a custom role | `{ name, displayName, prompt, emoji?, model? }` |
382
- | `nexus.history.list` | List execution history | `{ count?: number }` |
281
+ | `nexus.todo.add` | Add a todo item | `{ description, assignedTo? }` |
282
+ | `nexus.todo.list` | List all todos | `{}` |
283
+ | `nexus.todo.complete` | Complete a todo | `{ id }` |
284
+ | `nexus.todo.stats` | Todo statistics | `{}` |
285
+ | `nexus.goal.set` | Set a goal | `{ description, autoContinue? }` |
286
+ | `nexus.goal.status` | Current goal status | `{}` |
287
+ | `nexus.goal.complete` | Complete goal | `{}` |
288
+ | `nexus.goal.list` | List all goals | `{}` |
289
+ | `nexus.team.create` | Create a team | `{ name, leadRole }` |
290
+ | `nexus.team.addMember` | Add team member | `{ teamId, role, model }` |
291
+ | `nexus.team.status` | Team status | `{ teamId? }` |
292
+ | `nexus.team.activate` | Start team | `{ teamId }` |
293
+ | `nexus.performance.scores` | Performance scores | `{}` |
294
+ | `nexus.performance.best` | Best model for role | `{ role }` |
295
+ | `nexus.history.list` | Execution history | `{ count? }` |
383
296
  | `nexus.history.stats` | Execution statistics | `{}` |
384
- | `nexus.forecast` | Predict costs before execution | `{ tasks: string }` |
385
- | `nexus.performance.scores` | Model/role performance scores | `{}` |
386
- | `nexus.performance.best` | Best model for a role | `{ role: string }` |
387
- | `nexus.worktree.enable` | Enable git worktree isolation | `{ repoRoot?: string }` |
388
- | `nexus.worktree.list` | List active worktrees | `{}` |
389
- | `nexus.worktree.disable` | Disable and clean up | `{}` |
390
-
391
- ### Tool Examples
392
-
393
- ```
394
- # Spawn a coder agent with complexity analysis
395
- Use nexus.spawn with role="coder" and task="Implement JWT auth middleware"
396
- # → 💻 Coder — anthropic/claude-sonnet-4-6
397
- # → 📊 Complexity: 45/100 (low risk)
398
-
399
- # Check status
400
- Use nexus.status with detailed=true
297
+ | `nexus.astgrep.search` | Search AST patterns | `{ pattern, language, directory }` |
298
+ | `nexus.astgrep.status` | Check ast-grep install | `{}` |
299
+ | `nexus.security.scan` | Scan for security issues | `{ content, filename? }` |
300
+ | `nexus.clarify` | Ask clarifying question | `{ question, options?, assumption? }` |
301
+ | `nexus.worktree.enable` | Enable worktree isolation | `{ repoRoot? }` |
302
+ | `nexus.worktree.list` | List worktrees | `{}` |
303
+ | `nexus.worktree.disable` | Disable worktrees | `{}` |
401
304
 
402
- # Apply a preset
403
- Use nexus.preset with name="balanced"
305
+ ---
404
306
 
405
- # Initialize config
406
- Use nexus.config.init with level="project"
307
+ ## TUI Commands
407
308
 
408
- # Start web dashboard
409
- Use nexus.dashboard.start with port=4747
410
- ```
309
+ | Command | Alias | Description |
310
+ |---------|-------|-------------|
311
+ | `/nexus` | `Ctrl+N` | Open full configuration dialog |
312
+ | `/nexus web` | `/nw` | Start web dashboard |
313
+ | `/nexus review` | `/nr` | Quick code review |
314
+ | `/nexus fix` | `/nf` | Quick fix for last error |
315
+ | `/nexus explain` | `/ne` | Explain last change |
316
+ | `/nexus config` | `/nc` | Configure models & budget |
317
+ | `/nexus model` | `/nm` | Select model for a role |
318
+ | `/nexus status` | `/ns` | Show config summary |
319
+ | `/nexus reset` | — | Reset all settings to defaults |
411
320
 
412
321
  ---
413
322
 
414
323
  ## Configuration
415
324
 
416
- ### Agent Models (TUI)
325
+ ### Agent Models
417
326
 
418
327
  Configure via `/nexus` or `Ctrl+N`:
419
328
 
420
329
  ```
421
- 🏗️ Architect: anthropic/claude-sonnet-4-6
422
- 💻 Coder: anthropic/claude-sonnet-4-6
423
- 🔍 Reviewer: openai/gpt-5-mini
424
- 🧪 Tester: anthropic/claude-haiku-4-5
425
- 🔬 Explorer: google/gemini-2.5-flash
426
- 📝 Documenter: anthropic/claude-haiku-4-5
330
+ 🏗️ Architect: opencode/muse-spark-1.3-contributor-free
331
+ 💻 Coder: opencode/mimo-v2.6-flash-free
332
+ 🔍 Reviewer: opencode/muse-spark-1.2-contributor-free
333
+ 🧪 Tester: opencode-go/mimo-v2.5
334
+ 🔬 Explorer: opencode/big-pickle
335
+ 📝 Documenter: opencode/big-pickle
427
336
  ```
428
337
 
429
- ### Budget
338
+ ### Custom Roles
430
339
 
431
- ```
432
- 💰 Max Total: $10.00
433
- Max Per Task: $1.00
434
- Alert Threshold: 20%
340
+ Define your own agent roles:
341
+
342
+ ```jsonc
343
+ {
344
+ "customRoles": [
345
+ {
346
+ "name": "security-auditor",
347
+ "displayName": "Security Auditor",
348
+ "emoji": "🔐",
349
+ "prompt": "You are a security auditor...",
350
+ "model": "anthropic/claude-sonnet-4-6"
351
+ }
352
+ ]
353
+ }
435
354
  ```
436
355
 
437
- ### Self-Healing
356
+ ### Task Templates
438
357
 
439
358
  ```
440
- 🛡️ Enabled: ✅
441
- Max Retries: 3
442
- Context Transfer: ✅
359
+ nexus.template(name="list") — Show available templates
360
+ nexus.template(name="feature") — Full feature pipeline
361
+ nexus.template(name="bugfix") — Bug investigation and fix
362
+ nexus.template(name="refactor") — Code refactoring pipeline
363
+ nexus.template(name="documentation") — Documentation update
443
364
  ```
444
365
 
445
366
  ---
@@ -447,67 +368,49 @@ Configure via `/nexus` or `Ctrl+N`:
447
368
  ## Architecture
448
369
 
449
370
  ```
450
- ┌─────────────────────────────────────────────────────────────────┐
451
- │ NEXUS PLUGIN │
452
- │ │
453
- │ ┌──────────────────────────────────────────────────┐ │
454
- │ │ SERVER PLUGIN (index.ts) │ │
455
- │ │ • 12 tool registrations (spawn, status, costs, │ │
456
- │ │ dashboard, config, preset, template, queue) │ │
457
- │ │ • Session hook for /nexus commands │ │
458
- │ │ • State persistence to storage │ │
459
- │ └──────────────────────────────────────────────────┘ │
460
- │ │
461
- │ ┌──────────────────────────────────────────────────┐ │
462
- │ │ ORCHESTRATOR (orchestrator.ts) │ │
463
- │ │ • Real OpenCode session creation │ │
464
- │ │ • DAG-based task execution with priority │ │
465
- │ │ • Cost-aware model routing (scored selection) │ │
466
- │ │ • Self-healing with escalation policies │ │
467
- │ │ • Context transfer to respawned agents │ │
468
- │ │ • Cycle detection for deadlock prevention │ │
469
- │ │ • Performance: lazy init, debounce, cleanup │ │
470
- │ └──────────────────────────────────────────────────┘ │
471
- │ │
472
- │ ┌──────────────────────────────────────────────────┐ │
473
- │ │ MODULES │ │
474
- │ │ ┌────────────┐ ┌──────────┐ ┌────────────────┐ │ │
475
- │ │ │ Health │ │ Learning │ │ Message Store │ │ │
476
- │ │ │ Monitor │ │ Module │ │ (JSONL+SQLite) │ │ │
477
- │ │ └────────────┘ └──────────┘ └────────────────┘ │ │
478
- │ │ ┌────────────┐ ┌──────────┐ ┌────────────────┐ │ │
479
- │ │ │ Persistent │ │ Fan-Out │ │ Notifications │ │ │
480
- │ │ │ Memory │ │ Router │ │ (OS native) │ │ │
481
- │ │ └────────────┘ └──────────┘ └────────────────┘ │ │
482
- │ │ ┌────────────┐ ┌──────────┐ │ │
483
- │ │ │ State │ │ Module │ │ │
484
- │ │ │ Broadcaster│ │ Registry │ │ │
485
- │ │ └────────────┘ └──────────┘ │ │
486
- │ └──────────────────────────────────────────────────┘ │
487
- │ │
488
- │ ┌──────────────────────────────────────────────────┐ │
489
- │ │ WEB DASHBOARD │ │
490
- │ │ • Bun.serve() HTTP + WebSocket (port 4747) │ │
491
- │ │ • REST: /api/state, /api/config, /api/agents │ │
492
- │ │ • WebSocket: /ws/events (real-time updates) │ │
493
- │ │ • SPA: Agent grid, DAG viz, cost tracker │ │
494
- │ └──────────────────────────────────────────────────┘ │
495
- │ │
496
- │ ┌──────────────────────────────────────────────────┐ │
497
- │ │ CONFIG │ │
498
- │ │ • JSONC file loading (project + global) │ │
499
- │ │ • Config creation and initialization │ │
500
- │ │ • Preset configurations (4 presets) │ │
501
- │ │ • Task templates (feature, bugfix, refactor) │ │
502
- │ └──────────────────────────────────────────────────┘ │
503
- │ │
504
- │ ┌──────────────────────────────────────────────────┐ │
505
- │ │ TUI PLUGIN (tui.tsx) │ │
506
- │ │ • /nexus slash commands │ │
507
- │ │ • Configuration dialogs (model selection) │ │
508
- │ │ • Keyboard shortcut (Ctrl+N) │ │
509
- │ └──────────────────────────────────────────────────┘ │
510
- └─────────────────────────────────────────────────────────────────┘
371
+ ┌─────────────────────────────────────────────────────────────┐
372
+ │ NEXUS PLUGIN │
373
+ │ │
374
+ │ ┌────────────────────────────────────────────────────┐ │
375
+ │ │ SERVER PLUGIN (index.ts) │ │
376
+ │ │ • 40+ tool registrations │ │
377
+ │ │ • Auto-creates agents and enables LSP │ │
378
+ │ │ • Config file loading and creation │ │
379
+ │ └────────────────────────────────────────────────────┘ │
380
+ │ │
381
+ │ ┌────────────────────────────────────────────────────┐ │
382
+ │ │ ORCHESTRATOR (orchestrator.ts) │ │
383
+ │ │ • Real OpenCode session creation │ │
384
+ │ │ • DAG execution with priority queuing │ │
385
+ │ │ • Cost-aware model routing (scored selection) │ │
386
+ │ │ • Self-healing with 4-step escalation │ │
387
+ │ │ • Context transfer to respawned agents │ │
388
+ │ │ • Deadlock detection (cycle finding) │ │
389
+ │ │ • Todo/Goal tracking │ │
390
+ │ │ • Team management │ │
391
+ │ └────────────────────────────────────────────────────┘ │
392
+ │ │
393
+ │ ┌────────────────────────────────────────────────────┐ │
394
+ │ │ MODULES │ │
395
+ │ │ Health Monitor │ Learning │ Message Store (SQLite) │ │
396
+ │ │ Persistent Mem │ Fan-Out │ Notifications (OS) │ │
397
+ │ │ State Broadcaster │ Module Registry │ Security │ │
398
+ │ │ Cost Forecaster │ Performance Tracker │ AST-Grep │ │
399
+ │ └────────────────────────────────────────────────────┘ │
400
+ │ │
401
+ │ ┌────────────────────────────────────────────────────┐ │
402
+ │ │ WEB DASHBOARD │ │
403
+ │ │ • Bun.serve() HTTP + WebSocket (port 4747) │ │
404
+ │ │ • DAG viz, cost chart, config editor, auto-refresh │ │
405
+ │ └────────────────────────────────────────────────────┘ │
406
+ │ │
407
+ │ ┌────────────────────────────────────────────────────┐ │
408
+ │ │ AGENTS (auto-created) │ │
409
+ │ │ nexus-orchestrator (primary) │ │
410
+ │ │ nexus-architect, nexus-coder, nexus-reviewer │ │
411
+ │ │ nexus-tester, nexus-explorer, nexus-documenter │ │
412
+ │ └────────────────────────────────────────────────────┘ │
413
+ └─────────────────────────────────────────────────────────────┘
511
414
  ```
512
415
 
513
416
  ---