{"id":"a206167c-be7c-44b1-8e57-00c07cb8b4ff","slug":"opencode-helper","kind":"skill","name":"opencode-helper","summary":"Claude Code plugin to delegate tasks (e.g. code review) via the OpenCode CLI.","owner":"flin2","repoUrl":"https://github.com/flin2/opencode-helper","license":"GPL-3.0","licenseTier":"strong-copyleft","trust":"community","stars":0,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-06-25T18:08:49.000Z","addedAt":"2026-10-22T03:10:05.372Z","logoUrl":"https://avatars.githubusercontent.com/u/40869509?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools"],"tags":["claude-code","claude-code-plugin","opencode"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-23T00:57:11.924Z","sample":false,"url":"https://conduits.dev/tools/opencode-helper","language":"Python","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# opencode-helper\n\nA 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](https://opencode.ai) CLI.\n\nYou 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.\n\n> **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](SECURITY.md) before using it on private code.\n\n## What you get\n\n- **`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`.\n- **`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.\n- **Claude Code commands** — `/opencode-helper:setup`, `:rescue`, `:review`, `:adversarial-review`, `:status`, `:result`, `:cancel`.\n- **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.\n- **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.\n- **Headless resilience** — an idle-output watchdog auto-resumes a stalled `opencode run`.\n\nDelegations from either CLI default to **read-only** and only touch the working tree when the task clearly asks (`--write`).\n\n## Requirements\n\n- The [`opencode`](https://opencode.ai) CLI installed and on `PATH`.\n- Credentials configured in OpenCode (`opencode auth login`; verify with `opencode auth list`):\n  - an **OpenCode Zen** and/or **OpenCode Go** credential for `oc-sub-rescue`, and\n  - a direct-provider credential (e.g. **DeepSeek**, **OpenAI**) for `oc-api-rescue`.\n- 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.\n- 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.\n- 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.\n\n## Install\n\nBoth 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.\n\n### Claude Code\n\nFrom Claude Code:\n\n```text\n/plugin marketplace add https://github.com/flin2/opencode-helper\n/plugin install opencode-helper@opencode-helper\n/reload-plugins\n```\n\nAfter 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.\n\n### Codex\n\nFrom your terminal:\n\n```bash\ncodex plugin marketplace add flin2/opencode-helper\ncodex plugin add opencode-helper@opencode-helper\n```\n\nStart 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.\n\n### Local development\n\nBefore the updated package is published, register this checkout's absolute path instead of the GitHub repository:\n\n```bash\nclaude plugin marketplace add /absolute/path/to/opencode-helper\nclaude plugin install opencode-helper@opencode-helper\ncodex plugin marketplace add /absolute/path/to/opencode-helper\ncodex plugin add opencode-helper@opencode-helper\n```\n\nUse 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.\n\n## Usage\n\nLet the main thread delegate, or call a subagent by name:\n\n```text\nAsk Kimi via oc-sub-rescue to diagnose why test_foo is flaky; do not edit anything.\nHave oc-sub-rescue (ds-pro, --effort high, --write) implement the TODO in src/foo.rs and run the tests.\nHave oc-api-rescue review the staged diff for correctness bugs with DeepSeek.\n```\n\nIn Codex, use the corresponding skills:\n\n```text\n$opencode-helper:oc-rescue --model kimi --dir /absolute/path/to/repo Diagnose why test_foo is flaky; do not edit anything.\n$opencode-helper:oc-review --api --model pro Review the staged changes for correctness bugs.\n$opencode-helper:oc-adversarial-review --base main Challenge the approach and its assumptions.\n$opencode-helper:oc-status\n```\n\n`$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.\n\nCommon 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:\n\n```bash\nplugins/opencode-helper/scripts/oc-sub.sh --help\nplugins/opencode-helper/scripts/oc-api.sh --help\n```\n\n## Continuing a thread\n\nThe 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:\n\n- **Claude SendMessage to the same subagent** — it resumes the recorded thread automatically and forwards only your delta instruction.\n- **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.\n- **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.\n\n## Headless resilience\n\nHeadless `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.\n\nFor 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`:\n\n```json\n{\n  \"permission\": {\n    \"external_directory\": { \"/absolute/path/to/dir/**\": \"allow\" }\n  }\n}\n```\n\n## Job state\n\n- 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`.\n- 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.\n- 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.\n\n## Layout\n\n```\n.\n├── .claude-plugin/marketplace.json   # Claude marketplace\n├── .agents/plugins/marketplace.json # Codex marketplace\n├── plugins/opencode-helper/          # the plugin\n│   ├── .claude-plugin/plugin.json    # Claude manifest\n│   ├── .codex-plugin/plugin.json     # Codex manifest; selects codex-skills/\n│   ├── agents/                       # Claude oc-sub-rescue, oc-api-rescue\n│   ├── commands/                     # Claude command entry points\n│   ├── codex-skills/                 # Codex workflow entry points\n│   ├── assets/                       # bundled plugin icon\n│   ├── prompts/                      # shared review templates and Codex runtime guidance\n│   ├── scripts/                      # backends, job manager, session/setup helpers\n│   └── skills/                       # Claude oc-rescue-runtime, oc-prompting\n├── tests/                           # package validation, host tests, and backend smoke tests\n└── .github/workflows/ci.yml          # manifest/shell/python/frontmatter checks\n```\n\nThe 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.\n\n## Acknowledgments\n\nThe design of opencode-helper — the forwarding-subagent pattern, the slash-command surface, and the overall plugin layout — is inspired by [`codex-plugin-cc`](https://github.com/openai/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](https://opencode.ai) CLI; it shares no code with that project.\n\n## License\n\n[GPL-3.0-or-later](LICENSE). Copyright (C) 2026 Feng Lin.\n"}