opencode-ultra

Disclaimer: This project is not built by or affiliated with the OpenCode team. It is a community-built plugin forked from oh-my-opencode.

A lightweight OpenCode 1.2.x plugin that provides multi-agent orchestration, keyword-driven mode switching, rules injection, session continuity, AST search, and self-improvement (evolve) in a single plugin.

Install

# In your OpenCode plugin directory
bun add opencode-ultra

Register in opencode.jsonc:

{
  "plugins": ["opencode-ultra"]
}

Features

Tools (12)

| Tool | Description | |------|-------------| | spawn_agent | Parallel agent execution (ConcurrencyPool + spawn limit + timeout + sanitizer) | | ralph_loop | Autonomous loop execution (completion detection via <promise>DONE</promise>, per-iteration timeout) | | cancel_ralph | Cancel a running Ralph Loop | | batch_read | Parallel multi-file reading (max 20) | | ledger_save | Save Continuity Ledger (.opencode/ledgers/) | | ledger_load | Load Continuity Ledger (by name or latest) | | ast_search | AST-aware code search (uses ast-grep/sg binary, auto-skips if not installed) | | evolve_apply | Trust score evaluation + auto-apply plugin recommendations to OpenCode config (dry-run/backup) | | evolve_scan | Validate, merge, score improvement proposals from JSONL + generate numbered report | | evolve_score | Score and rank proposals (Priority x Effort weighted) | | evolve_exe | Autonomous execution pipeline (git branch -> implement -> test -> build -> review -> merge/rollback) | | evolve_publish | Version bump + test + build + npm publish (with deploy instructions) |

Hooks (9)

| Hook | Hook Point | Description | |------|-----------|-------------| | keyword-detector | chat.message | Detects ultrawork/search/analyze/think/evolve keywords | | rules-injector | system.transform | Injects .opencode/rules.md into system prompt | | context-injector | system.transform | Auto-injects ARCHITECTURE.md / CODE_STYLE.md | | fragment-injector | system.transform | Per-agent custom prompt fragment injection | | prompt-renderer | system.transform | Model-specific system prompt format optimization (markdown/xml/json) | | comment-checker | tool.execute.after | Detects AI slop comments after Write/Edit | | token-truncation | tool.execute.after | Compresses tool output >30000 chars to first 40% + last 40% | | todo-enforcer | event (session.idle) | Detects unfinished TODOs and forces continuation | | session-compaction | experimental.session.compacting | Generates structured summary during session compaction |

Safety

| Feature | Description | |---------|-------------| | Prompt Injection Sanitizer | Detects and neutralizes injection patterns in agent output (17 patterns, 6 categories) | | Spawn Limit | Max concurrent sessions (default: 15) | | Agent Timeout | Per-agent timeout (default: 180s) | | Trust Score | npm package trust score (0-100) — quality gate for evolve recommendations | | Concurrency Pool | Semaphore-based global/provider/model three-tier concurrency control |

Evolve (Self-Improvement)

Triggered by evolve / self-improve keywords. A 5-phase self-improvement cycle:

| Phase | Description | |-------|-------------| | 1. RESEARCH | Scan npm/GitHub for plugin ecosystem | | 2. COMPARE | Feature matrix diff against opencode-ultra | | 3. PROPOSE | Structured implementation proposals (target files/functions, issues, changes, effects) + JSONL output | | 4. SCORE | Score all proposals via evolve_score (Priority x Effort weighted) | | 5. SAVE | Persist results via ledger_save |

Proposals are output to .opencode/evolve-proposals.jsonl:

{"title":"Feature","priority":"P0","effort":"Medium","inspiration":"reference-plugin","current_state":"Current state","why":"Benefit","how":"target-file:function — change description"}

Score calculation: priority_weight x effort_weight

| Priority | Weight | Effort | Weight | |----------|--------|--------|--------| | P0 | 10 | Low | 3 | | P1 | 5 | Medium | 2 | | P2 | 1 | High | 1 |

P0+Low=30 (highest priority) / P2+High=1 (lowest)

Evolve Execution (Autonomous)

Fully automate proposal implementation with evolve_exe. Each proposal is isolated in a git branch with automatic rollback on failure.

evolve_exe({ proposals: "1,3" })              — Execute proposals #1 and #3
evolve_exe({ proposals: "all" })               — Execute all accepted proposals
evolve_exe({ proposals: "1", dryRun: true })   — Show execution plan only
evolve_exe({ proposals: "1,2", publish: true }) — Auto-publish after execution

| Phase | Description | |-------|-------------| | 1. GIT BRANCH | Create evolve/{slug} branch | | 2. IMPLEMENT | implementAgent (default: hephaestus) autonomously implements | | 3. TEST | Run bun test (failure -> rollback) | | 4. BUILD | Run bun run build (failure -> rollback) | | 5. REVIEW | reviewAgent (default: momus) code review (BLOCK is logged) | | 6. MERGE | --no-ff merge to original branch, delete feature branch |

Post-implementation publish:

evolve_publish({ bump: "patch" })                      — test -> build -> version bump -> npm publish
evolve_publish({ bump: "minor", deploy: "my-server" }) — publish + SSH deploy instructions

Agent Configuration

Sisyphus (orchestrator) handles reading, analysis, and planning, then delegates implementation to sub-agents.

| Agent | Role | Tier | |-------|------|------| | sisyphus | Orchestrator — read + analyze + plan + delegate | High | | momus | Code review and quality check | High | | oracle | Design, debugging, architecture decisions | Mid | | hephaestus | Autonomous implementation worker | Mid | | metis | Task decomposition and parallel execution planning | Mid | | multimodal-looker | Image and screenshot analysis | Mid | | explore | Fast codebase reconnaissance | Fast | | librarian | Documentation and best practices research | Fast | | scout | Plugin ecosystem research | Fast | | atlas | Task management and progress tracking | Low |

All agent models are configured via opencode-ultra.json. Only providers/models defined in your opencode.jsonc provider section can be specified.

Default Models

| Agent | Default Model | |-------|--------------| | sisyphus | anthropic/claude-opus-4-5 | | oracle | openai/gpt-5.2 | | hephaestus | openai/gpt-5.2 | | momus | anthropic/claude-sonnet-4-5 | | metis | anthropic/claude-sonnet-4-5 | | explore | anthropic/claude-haiku-4-5 | | librarian | anthropic/claude-sonnet-4-5 | | multimodal-looker | anthropic/claude-sonnet-4-5 | | atlas | anthropic/claude-sonnet-4-5 |

You can override these with any model from your configured providers (OpenAI, Anthropic, Google, OpenRouter, etc.).

Keyword Detection

| Keyword | Mode | Effect | |---------|------|--------| | ultrawork / ulw | ultrawork | variant "max", full agent utilization | | search / find / 探して etc. | search | Comprehensive search | | analyze / 調査 / debug etc. | analyze | Context collection | | think hard / じっくり / 熟考 etc. | think | Extended thinking enabled | | evolve / self-improve / 自己改善 etc. | evolve | Self-improvement cycle |

Supports Japanese and Chinese keywords.

Configuration

Two-level merge via opencode-ultra.json (or .jsonc):

1. User config: ~/.config/opencode/opencode-ultra.json[c]
2. Project config: <project>/.opencode/opencode-ultra.json[c]

Project config overrides user config.

Configuration Schema

{
  // Agent model settings (specify models defined in opencode.jsonc provider section)
  "agents": {
    "sisyphus": { "model": "anthropic/claude-opus-4-5" },
    "oracle":   { "model": "openai/gpt-5.2" },
    "hephaestus": { "model": "openai/gpt-5.2" },
    "explore":  { "model": "anthropic/claude-haiku-4-5" },
    "momus":    { "model": "anthropic/claude-sonnet-4-5" }
  },

  // Categories (bulk model switching via spawn_agent category parameter)
  // Note: category takes priority over individual agent models
  "categories": {
    "quick": { "model": "anthropic/claude-haiku-4-5" },
    "deep":  { "model": "anthropic/claude-opus-4-5" }
  },

  // Fragment Injection (per-agent prompt fragments)
  "fragments": {
    "hephaestus": [".opencode/fragments/strict.md"]
  },

  // Per-model Prompt Renderer
  "prompt_renderer": {
    "default": "markdown",
    "model_overrides": {
      "provider/model": "xml"
    }
  },

  // Disable features
  "disabled_agents": [],
  "disabled_hooks": [],   // keyword-detector, rules-injector, context-injector,
                          // fragment-injector, prompt-renderer, comment-checker,
                          // token-truncation, todo-enforcer, session-compaction
  "disabled_tools": [],   // spawn_agent, ralph_loop, cancel_ralph, batch_read,
                          // ledger_save, ledger_load, ast_search, evolve_apply,
                          // evolve_scan, evolve_score, evolve_exe, evolve_publish
  "disabled_mcps": [],    // context7

  // Built-in Agent Demotion (default: true)
  "demote_builtin": true,

  // Concurrency control
  "background_task": {
    "defaultConcurrency": 3,
    "providerConcurrency": { "openai": 8 },
    "modelConcurrency": { "openai/gpt-5.2": 2 }
  },

  // Safety
  "safety": {
    "maxTotalSpawned": 15,
    "agentTimeoutMs": 180000
  },

  // Evolve Execution
  "evolve_exe": {
    "maxIterations": 10,
    "iterationTimeoutMs": 300000,
    "totalTimeoutMs": 900000,
    "skipReview": false,
    "skipTests": false,
    "implementAgent": "hephaestus",
    "reviewAgent": "momus"
  },

  // Token Truncation
  "token_truncation": { "maxChars": 30000 },

  // Comment Checker
  "comment_checker": { "maxRatio": 0.3, "slopThreshold": 3 },

  // Todo Enforcer
  "todo_enforcer": { "maxEnforcements": 5 },

  // MCP API Keys
  "mcp_api_keys": { "context7": "ctx7sk-..." }
}

Continuity Ledger

Markdown documents for session-to-session context continuity. Saved to .opencode/ledgers/.

// Save
ledger_save({ name: "auth-refactor", content: "## Context\n..." })

// Load (by name)
ledger_load({ name: "auth-refactor" })

// Load (latest)
ledger_load({})

Build & Test

bun install
bun run build
bun test

Attribution

This project is a fork of oh-my-opencode by code-yeongyu, built on top of OpenCode by the OpenCode team.

We respect and follow the upstream licenses:

• oh-my-opencode: Sustainable Use License v1.0
• OpenCode: MIT License

License

Sustainable Use License v1.0 — Free for personal and non-commercial use. See LICENSE.md for full terms.