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.