opencode-helper

opencode-helper

A plugin for Claude Code and Codex that delegates a code review, a root-cause diagnosis, or a bounded implementation/fix to another model — DeepSeek, GLM, Kimi, MiniMax, and other models reachable through the OpenCode CLI.

You stay in your CLI; a second model does a scoped piece of work and returns its output verbatim. One package contains both native integrations and the shared backend scripts; no assembly or custom installer is required.

Heads up — your code leaves your machine. Every delegated task ships the relevant files and/or git diff to whatever third-party provider you have configured in OpenCode (DeepSeek, OpenCode Zen/Go, etc.). See SECURITY.md before using it on private code.

What you get

• opencode-helper:oc-sub-rescue — forward a task to an OpenCode subscription model (OpenCode Zen by default, or OpenCode Go with --go). Pick a model with --model: glm, kimi, minimax, ds-pro, ds-flash, or any provider/model id on the active gateway; omit it to use the default model from your OpenCode config. Built-in shortcuts resolve to the newest version OpenCode lists, so they don't go stale; define your own (or pin a version) in ~/.config/opencode-helper/config.json — see scripts/oc-sub.sh --help.
• opencode-helper:oc-api-rescue — forward a task to a direct provider API (bring-your-own-key). DeepSeek today (--model pro, flash, ...), or any direct id such as openai/gpt-5.4; with no --model, your OpenCode default model runs.
• Claude Code commands — /opencode-helper:setup, :rescue, :review, :adversarial-review, :status, :result, :cancel.
• Codex skills — $opencode-helper:oc-setup, $opencode-helper:oc-rescue, $opencode-helper:oc-review, $opencode-helper:oc-adversarial-review, $opencode-helper:oc-status, $opencode-helper:oc-result, $opencode-helper:oc-cancel. Codex calls the shared scripts directly and collects detached jobs with its shell/session tools.
• Background job manager (scripts/oc-job.py) — runs rescue delegations as detached jobs so long tasks outlive the harness's per-call time cap, with status/result/wait/cancel.
• Headless resilience — an idle-output watchdog auto-resumes a stalled opencode run.

Delegations from either CLI default to read-only and only touch the working tree when the task clearly asks (--write).

Requirements

• The opencode CLI installed and on PATH.
• Credentials configured in OpenCode (opencode auth login; verify with opencode auth list):
  • an OpenCode Zen and/or OpenCode Go credential for oc-sub-rescue, and
  • a direct-provider credential (e.g. DeepSeek, OpenAI) for oc-api-rescue.
• Runtime: bash (3.2+), Python 3 (3.8+), and git, plus the usual Unix tools (sed, grep, mktemp) — all standard on macOS and Linux. The bundled scripts avoid bash-4 features and GNU-only tool flags.
• Platforms: macOS and Linux (Windows via WSL — the bundled backends need a Unix shell). CI exercises the scripts on both Linux and macOS against a stub backend.
• Codex needs a CLI version with codex plugin marketplace add and codex plugin add; these commands are available in Codex CLI 0.160.0. The shared scripts need access to OpenCode's local credentials/data, a writable state directory, and the provider network under the host CLI's normal permission policy.

Install

Both marketplaces are named opencode-helper and point to plugins/opencode-helper. Each CLI registers and installs the package independently; installing it in one does not install it in the other. On the same machine/account, both use OpenCode's existing credentials and model configuration.

Claude Code

From Claude Code:

/plugin marketplace add https://github.com/flin2/opencode-helper
/plugin install opencode-helper@opencode-helper
/reload-plugins

After installing, the two subagents appear in /agents as opencode-helper:oc-sub-rescue and opencode-helper:oc-api-rescue. Then run /opencode-helper:setup to check that opencode is installed and authenticated.

Codex

From your terminal:

codex plugin marketplace add flin2/opencode-helper
codex plugin add opencode-helper@opencode-helper

Start a new Codex session and invoke $opencode-helper:oc-setup. Use /skills or the $ selector to choose the plugin's namespaced skills. OpenCode authentication is separate from Codex authentication.

Local development

Before the updated package is published, register this checkout's absolute path instead of the GitHub repository:

claude plugin marketplace add /absolute/path/to/opencode-helper
claude plugin install opencode-helper@opencode-helper
codex plugin marketplace add /absolute/path/to/opencode-helper
codex plugin add opencode-helper@opencode-helper

Use the CLI(s) you want; run the readiness workflow afterward. Claude can reload with /reload-plugins; restart Codex after refreshing its installed plugin. Keep both native catalogs and manifests in the same checkout, and keep referenced files inside the plugin directory so either CLI can cache a complete package.

Usage

Let the main thread delegate, or call a subagent by name:

Ask Kimi via oc-sub-rescue to diagnose why test_foo is flaky; do not edit anything.
Have oc-sub-rescue (ds-pro, --effort high, --write) implement the TODO in src/foo.rs and run the tests.
Have oc-api-rescue review the staged diff for correctness bugs with DeepSeek.

In Codex, use the corresponding skills:

$opencode-helper:oc-rescue --model kimi --dir /absolute/path/to/repo Diagnose why test_foo is flaky; do not edit anything.
$opencode-helper:oc-review --api --model pro Review the staged changes for correctness bugs.
$opencode-helper:oc-adversarial-review --base main Challenge the approach and its assumptions.
$opencode-helper:oc-status

$opencode-helper:oc-rescue starts a detached job and waits for the result unless you explicitly request a background handoff. $opencode-helper:oc-status, $opencode-helper:oc-result <job-id>, and $opencode-helper:oc-cancel <job-id> let you manage a handed-off job. Cancellation leaves any backend edits in place.

Common flags map straight through to the backend: read-only by default, --write to allow edits, --model / --effort to pick model and reasoning variant (oc-sub also takes --go for the OpenCode Go gateway), --dir <repo root> to scope reads/edits, --session / --resume-latest to continue a prior OpenCode thread. See the backend help:

plugins/opencode-helper/scripts/oc-sub.sh --help
plugins/opencode-helper/scripts/oc-api.sh --help

Continuing a thread

The model's real context lives in the OpenCode session (persisted on disk, recorded per repo), not in the launcher subagent. A follow-up continues that same on-disk thread:

• Claude SendMessage to the same subagent — it resumes the recorded thread automatically and forwards only your delta instruction.
• Codex follow-up — $opencode-helper:oc-rescue --session <id> <delta instruction> continues the thread named in the previous [oc-session] trailer. Prefer an explicit ID when multiple jobs use the same repository.
• From a fresh call — pass --resume-latest (this repo's most-recent thread) or --session <id> (one specific thread). Every run ends with an [oc-session] id=<id> … trailer naming the thread it ran, so you can target it exactly.

Headless resilience

Headless opencode run occasionally hangs mid-task. The bundled scripts/oc-run.sh runs OpenCode under an idle-output watchdog: if output goes silent for OC_IDLE_TIMEOUT seconds (default 600) it restarts and auto-resumes the session, up to OC_MAX_RESUMES times (default 3). Set OC_IDLE_TIMEOUT above your longest single build/tool step.

For permission prompts that no one can answer headlessly (e.g. reading a path outside --dir), prefer allow-listing the specific path in OpenCode's own config rather than the blunt OC_SKIP_PERMISSIONS=1:

{
  "permission": {
    "external_directory": { "/absolute/path/to/dir/**": "allow" }
  }
}

Job state

• Both oc-job.py and oc-session.py use CLAUDE_PLUGIN_DATA/state when provided, then PLUGIN_DATA/state, then ${OC_JOB_STATE_DIR:-${XDG_STATE_HOME:-$HOME/.local/state}/opencode-helper}/state.
• In Codex shell calls, plugin-data variables may be absent. If the default directory is outside the permitted writable roots, choose an authorized persistent directory and set OC_JOB_STATE_DIR consistently for launch and collection. OpenCode's own data and credentials must also remain accessible; the state override changes only the helper's storage.
• Job listings use OC_JOB_SESSION_ID if supplied, otherwise Claude's session ID or a namespaced Codex thread/session ID. --all lists jobs across conversations for that repository; --session refers to the OpenCode thread, not the host conversation.

Layout

.
├── .claude-plugin/marketplace.json   # Claude marketplace
├── .agents/plugins/marketplace.json # Codex marketplace
├── plugins/opencode-helper/          # the plugin
│   ├── .claude-plugin/plugin.json    # Claude manifest
│   ├── .codex-plugin/plugin.json     # Codex manifest; selects codex-skills/
│   ├── agents/                       # Claude oc-sub-rescue, oc-api-rescue
│   ├── commands/                     # Claude command entry points
│   ├── codex-skills/                 # Codex workflow entry points
│   ├── assets/                       # bundled plugin icon
│   ├── prompts/                      # shared review templates and Codex runtime guidance
│   ├── scripts/                      # backends, job manager, session/setup helpers
│   └── skills/                       # Claude oc-rescue-runtime, oc-prompting
├── tests/                           # package validation, host tests, and backend smoke tests
└── .github/workflows/ci.yml          # manifest/shell/python/frontmatter checks

The Codex compatibility manifest explicitly selects codex-skills/; there is no portable root plugin.json that would make Codex automatically discover the Claude-only skills/ directory. CI checks both native package surfaces and keeps their versions synchronized. The private release script updates both manifests and catalogs together.

Acknowledgments

The design of opencode-helper — the forwarding-subagent pattern, the slash-command surface, and the overall plugin layout — is inspired by codex-plugin-cc, OpenAI's Claude Code plugin for delegating to Codex/GPT. opencode-helper is an independent, clean-room implementation targeting models reachable through the OpenCode CLI; it shares no code with that project.

License

GPL-3.0-or-later. Copyright (C) 2026 Feng Lin.