feat(providers): add opencode CLI provider (#436)

* feat(providers): add opencode CLI provider

* test(providers): add unit tests for opencode CLI provider

* fix(providers): address code review for opencode provider

- Replace --dangerously-skip-permissions with read-only permission profile
  via OPENCODE_CONFIG_CONTENT env var (deny: edit, bash, external_directory,
  doom_loop)
- Add model discovery via 'opencode models' to show available models in UI
- Fix model name format to use provider/model (e.g., deepseek/deepseek-v4-pro)
- Fix install command to use curl instead of npm
- Remove dead rate-limiter entry (opencode uses semaphore serialization)
- Accumulate tokens across multi-step runs instead of overwriting
- Fix redundant except clause
- Update tests to verify security config and model discovery

* fix(providers): tighten read-only permission profile for opencode

Add webfetch, websearch, and task to deny set to prevent:
- task subagent bypassing top-level edit/bash denies
- network egress for data exfiltration from private repos

Author: ramsterr

.github/CONTRIBUTING.md

@@ -90,6 +90,27 @@ repowise/
 - Keep functions small and focused
 - Write docstrings for public APIs
 
+### Adding a new LLM provider
+
+1. **Create `packages/core/src/repowise/core/providers/llm/<name>.py`**
+   - Subclass `BaseProvider` and implement `generate()`, `provider_name`, `model_name`
+   - For local CLI providers, use `asyncio.create_subprocess_exec` (never `shell=True`), validate user-supplied model names against a safe character set, and resolve paths with `Path.resolve()`
+   - See `opencode.py` for a clean reference implementation
+
+2. **Register** in `registry.py` — add to `_BUILTIN_PROVIDERS` and the `_missing` package map
+
+3. **Wire up configuration** in these files:
+   - `rate_limiter.py` — add `RateLimitConfig` to `PROVIDER_DEFAULTS`
+   - `provider_config.py` — add entry to `PROVIDER_CATALOG`
+   - `provider_selection.py` — add to `_PROVIDER_DEFAULTS`, `_PROVIDER_ENV`, `_PROVIDER_SIGNUP`, and detection
+   - `helpers.py` — add validation in `validate_provider_config()`
+
+4. **Update the web UI** — add to `PROVIDERS`, `MODEL_PLACEHOLDERS`, and `PROVIDER_ENV_VARS` in `provider-section.tsx` and `run-config-form.tsx`
+
+5. **Add tests** in `tests/unit/test_providers/` — mock the subprocess, test success/error/timeout paths (see `test_codex_cli_provider.py` for the pattern)
+
+6. **Write docs** — `docs/<NAME>.md` and `website/<name>.md`, following `docs/CODEX.md` and `docs/OPENCODE.md`.
+
 Adding a new language or LLM provider has a dedicated recipe — see
 [docs/LANGUAGE_SUPPORT.md](../docs/LANGUAGE_SUPPORT.md).
 

docs/CHANGELOG.md

@@ -9,6 +9,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [Unreleased]
+
+### Added
+- **OpenCode CLI provider.** A new local OpenCode LLM provider runs documentation generation through the local OpenCode CLI via `opencode run --format json`. Uses `asyncio.create_subprocess_exec` (no shell), parses JSONL output, validates model names against a safe character set, and treats `opencode/*` cost as `$0.00`. No API keys are stored — OpenCode manages its own auth and model selection through its provider system. Interactive selection detects the OpenCode CLI on `PATH` and shows helpful install/setup instructions when it's missing.
+
+---
+
 ## [0.18.0] — 2026-06-08
 
 ### Added

docs/CLI_REFERENCE.md

@@ -50,7 +50,7 @@ In workspace mode, adds: repo scanning, per-repo indexing, cross-repo analysis (
 
 | Flag | Description |
 |------|-------------|
-| `--provider` | LLM provider: `anthropic`, `openai`, `openrouter`, `gemini`, `deepseek`, `ollama`, `litellm`, `codex_cli`, `mock` |
+| `--provider` | LLM provider: `anthropic`, `openai`, `openrouter`, `gemini`, `deepseek`, `ollama`, `litellm`, `codex_cli`, `opencode`, `mock` |
 | `--model` | Model name override (e.g., `claude-sonnet-4-6`) |
 | `--embedder` | Embedder for semantic search: `gemini`, `openai`, `mock` |
 | `--index-only` | Skip LLM generation. Only parse, build graph, and index git. Free. |
@@ -79,6 +79,7 @@ In workspace mode, adds: repo scanning, per-repo indexing, cross-repo analysis (
 repowise init                                         # interactive
 repowise init --provider anthropic --yes              # automated
 repowise init --provider codex_cli --codex --yes       # use authenticated Codex CLI
+repowise init --provider opencode --yes               # use local OpenCode CLI
 repowise init --index-only                            # free, no LLM
 repowise init --dry-run                               # preview cost
 repowise init --test-run                              # quick test (10 files)

docs/OPENCODE.md

@@ -0,0 +1,117 @@
+# OpenCode Integration
+
+Repowise supports OpenCode via the `opencode` LLM provider, which runs
+documentation generation through your local OpenCode CLI installation.
+No API keys are managed by repowise — OpenCode handles all authentication
+and model selection through its own provider system.
+
+## Prerequisites
+
+Install OpenCode:
+
+```bash
+curl -fsSL https://opencode.ai/install | bash
+```
+
+Then run `opencode` once to set up your model provider and authentication:
+
+```bash
+opencode
+```
+
+Verify the CLI is available:
+
+```bash
+opencode --version
+```
+
+Repowise detects OpenCode automatically: when `opencode` is in `PATH`,
+the interactive provider selection shows it as "available" and it can
+be used immediately.
+
+## `opencode` Provider
+
+Use `opencode` when you want Repowise page generation to run through
+your local OpenCode CLI instead of an API key:
+
+```bash
+repowise init --provider opencode --yes
+```
+
+You can also persist it:
+
+```bash
+REPOWISE_PROVIDER=opencode repowise update
+```
+
+The provider runs:
+
+```bash
+opencode run --format json --dangerously-skip-permissions --dir /absolute/path/to/repo
+```
+
+Repowise sends the combined system + user prompt on **stdin**, parses
+OpenCode's **JSONL** output (extracting text from `text` events and
+token usage from `step_finish` events), and treats `opencode/*` cost
+as `$0.00` because billing is handled by OpenCode's own subscription/auth.
+
+### Default model
+
+`opencode/default` uses OpenCode's configured default model — no
+`--model` flag is passed. To use a specific model:
+
+```bash
+repowise init --provider opencode --model opencode/deepseek-v4-pro
+```
+
+Or use a bare model slug (the `opencode/` prefix is optional):
+
+```bash
+repowise init --provider opencode --model deepseek-v4-pro
+```
+
+### Listing available models
+
+```bash
+opencode models           # all available models
+opencode models opencode  # models from the opencode provider
+```
+
+### Reasoning
+
+The opencode provider does not pass reasoning effort flags. OpenCode
+handles reasoning internally through its own model/agent configuration.
+
+## Security
+
+The provider enforces several safety measures:
+
+- Uses `asyncio.create_subprocess_exec` (no shell), so every argument
+  is passed as a distinct list element — shell injection is impossible.
+- Model names are validated against a safe character set
+  (`[a-zA-Z0-9][a-zA-Z0-9._/\-]*`), rejecting shell metacharacters
+  before anything reaches the subprocess.
+- All paths are resolved with `Path.resolve()` before being passed to
+  `--dir`.
+- Subprocess execution is serialized via `asyncio.Semaphore(1)`.
+- A 600-second hard timeout with process kill prevents runaway calls.
+
+## Comparison with Codex CLI
+
+| Aspect | `opencode` | `codex_cli` |
+|--------|-----------|-------------|
+| CLI command | `opencode run` | `codex exec` |
+| Auth | OpenCode providers | `codex login` |
+| Output format | JSONL via `--format json` | JSONL via `--json` |
+| Reasoning modes | Not passed (OpenCode manages it) | `model_reasoning_effort` mapping |
+| Sandbox | OpenCode manages its own | `--sandbox read-only` |
+| Model discovery | `opencode models` | `codex debug models --bundled` |
+| Editor integration | None | `.codex/config.toml`, hooks, plugin |
+| API keys stored | No | No |
+
+## Official OpenCode Docs
+
+- [OpenCode](https://opencode.ai)
+- [OpenCode GitHub](https://github.com/anomalyco/opencode)
+- [OpenCode Docs](https://opencode.ai/docs)
+- [OpenCode Download](https://opencode.ai/download)

docs/architecture/ARCHITECTURE.md

@@ -1618,7 +1618,7 @@ Key files:
 Full configuration with defaults (`.repowise/config.yaml`):
 
 ```yaml
-provider: anthropic          # anthropic | openai | openrouter | gemini | deepseek | ollama | litellm | mock
+provider: anthropic          # anthropic | openai | openrouter | gemini | deepseek | ollama | litellm | codex_cli | opencode | mock
 model: claude-sonnet-4-5    # passed through to the provider
 embedding_provider: anthropic
 embedding_model: voyage-3

packages/cli/src/repowise/cli/commands/init_cmd/command.py

@@ -207,7 +207,7 @@ def _run_generation_phase(
     default=None,
     help=(
         "LLM provider name (anthropic, openai, openrouter, gemini, "
-        "deepseek, ollama, litellm, codex_cli, mock)."
+        "deepseek, ollama, litellm, codex_cli, opencode, mock)."
     ),
 )
 @click.option("--model", default=None, help="Model identifier override.")

packages/cli/src/repowise/cli/cost_estimator/pricing.py

@@ -36,6 +36,7 @@
     "llama": (0.0, 0.0),
     "mock": (0.0, 0.0),
     "codex_cli/": (0.0, 0.0),
+    "opencode/": (0.0, 0.0),
 }
 
 

packages/cli/src/repowise/cli/helpers.py

@@ -706,6 +706,8 @@ def _resolve_base_url(name: str) -> str | None:
             kwargs["base_url"] = base_url
         if provider_name == "codex_cli" and repo_path is not None:
             kwargs["repo_path"] = repo_path
+        if provider_name == "opencode" and repo_path is not None:
+            kwargs["repo_path"] = repo_path
 
         # Pass API key from environment if available
         if provider_name == "anthropic" and os.environ.get("ANTHROPIC_API_KEY"):
@@ -787,7 +789,7 @@ def _resolve_base_url(name: str) -> str | None:
         "or set ANTHROPIC_API_KEY / OPENAI_API_KEY / OPENROUTER_API_KEY / "
         "OLLAMA_BASE_URL / GEMINI_API_KEY / GOOGLE_API_KEY / DEEPSEEK_API_KEY / "
         "LITELLM_API_KEY. Use REPOWISE_PROVIDER=codex_cli to use an authenticated "
-        "Codex CLI subscription."
+        "Codex CLI subscription, or REPOWISE_PROVIDER=opencode to use opencode."
     )
 
 
@@ -837,6 +839,19 @@ def _is_env_var_exists(var_name: str) -> bool:
                 )
             return warnings
 
+        if provider_name == "opencode":
+            import shutil
+            if not shutil.which("opencode"):
+                warnings.append(
+                    "Provider 'opencode' requires the opencode CLI.\n"
+                    "  Install:  curl -fsSL https://opencode.ai/install | bash\n"
+                    "  Setup:    run 'opencode' once to configure your provider\n"
+                    "  Models:   opencode models (list available models)\n"
+                    "  More:     https://opencode.ai\n"
+                    "  Usage:    repowise init --provider opencode --model opencode/openai/gpt-5"
+                )
+            return warnings
+
         # Validate specific provider
         if provider_name not in provider_env_vars:
             warnings.append(f"Unknown provider '{provider_name}' - cannot validate configuration")

packages/cli/src/repowise/cli/ui/provider_selection.py

@@ -26,6 +26,7 @@
     "anthropic": "claude-sonnet-4-6",
     "deepseek": "deepseek-v4-flash",
     "codex_cli": "codex_cli/default",
+    "opencode": "opencode/default",
     "ollama": "llama3.2",
     "openrouter": "anthropic/claude-sonnet-4.6",
     "litellm": "groq/llama-3.1-70b-versatile",
@@ -37,6 +38,7 @@
     "anthropic": "ANTHROPIC_API_KEY",
     "deepseek": "DEEPSEEK_API_KEY",
     "codex_cli": "__CODEX_CLI__",
+    "opencode": "__OPENCODE_CLI__",
     "ollama": "OLLAMA_BASE_URL",
     "openrouter": "OPENROUTER_API_KEY",
 }
@@ -47,6 +49,7 @@
     "anthropic": "https://console.anthropic.com/settings/keys",
     "deepseek": "https://platform.deepseek.com/api_keys",
     "codex_cli": "https://developers.openai.com/codex/cli",
+    "opencode": "https://opencode.ai",
     "ollama": "https://ollama.com/download",
     "openrouter": "https://openrouter.ai/keys",
 }
@@ -69,6 +72,13 @@ def _detect_codex_cli_status() -> tuple[bool, bool]:
     return installed, is_codex_logged_in() if installed else False
 
 
+def _detect_opencode_status() -> bool:
+    """Return ``True`` if the opencode CLI is installed on PATH."""
+    import shutil
+
+    return shutil.which("opencode") is not None
+
+
 def _detect_provider_status() -> dict[str, str]:
     """Return {provider: env_var_name} for providers whose key is set."""
     status: dict[str, str] = {}
@@ -80,6 +90,9 @@ def _detect_provider_status() -> dict[str, str]:
             installed, logged_in = _detect_codex_cli_status()
             if installed and logged_in:
                 status[prov] = "codex CLI"
+        elif prov == "opencode":
+            if _detect_opencode_status():
+                status[prov] = "opencode CLI"
         elif os.environ.get(env_var):
             status[prov] = env_var
     return status
@@ -120,6 +133,11 @@ def _interactive_provider_name(
                 status_text = "[yellow]✗ codex login required[/yellow]"
             else:
                 status_text = "[dim]✗ codex CLI not found[/dim]"
+        elif prov == "opencode":
+            if _detect_opencode_status():
+                status_text = f"[{OK}]✓ opencode CLI available[/]"
+            else:
+                status_text = "[dim]✗ opencode CLI not found[/dim]"
         else:
             status_text = f"[{OK}]✓ API key set[/]" if prov in detected else "[dim]✗ no key[/dim]"
         default_model = _PROVIDER_DEFAULTS.get(prov, "")
@@ -129,6 +147,8 @@ def _interactive_provider_name(
             label = f"{prov} [dim](recommended)[/dim]"
         elif prov == "codex_cli":
             label = f"{prov} [dim](uses Codex CLI auth)[/dim]"
+        elif prov == "opencode":
+            label = f"{prov} [dim](uses opencode CLI auth)[/dim]"
         table.add_row(f"[{idx}]", label, status_text, default_model)
 
     console.print()
@@ -175,6 +195,28 @@ def _interactive_provider_name(
                     "or select another provider.[/]"
                 )
             return _interactive_provider_name(console, model_flag, repo_path=repo_path)
+        if chosen == "opencode":
+            console.print()
+            console.print(
+                "  [bold]opencode[/bold] is a local AI coding CLI that manages its own "
+                "models and authentication."
+            )
+            console.print()
+            console.print(f"  Install:   [{BRAND}]curl -fsSL https://opencode.ai/install | bash[/]")
+            console.print(f"  Setup:     [{BRAND}]opencode[/]  (first run sets up your provider)")
+            console.print(f"  Models:    [{BRAND}]opencode models[/]  (list available models)")
+            console.print(f"  More info: [{BRAND}]https://opencode.ai[/]")
+            console.print()
+            console.print(
+                f"  To use a specific model: [{BRAND}]repowise init --provider opencode "
+                "--model opencode/deepseek/deepseek-v4-pro[/]"
+            )
+            console.print()
+            console.print(
+                f"  [{WARN}]opencode CLI not detected. Install it and retry, "
+                "or select another provider.[/]"
+            )
+            return _interactive_provider_name(console, model_flag, repo_path=repo_path)
         env_var = _PROVIDER_ENV[chosen]
         signup_url = _PROVIDER_SIGNUP.get(chosen, "")
         console.print()

packages/core/src/repowise/core/generation/cost_tracker.py

@@ -65,6 +65,8 @@ def _get_pricing(model: str) -> dict[str, float]:
     """Return pricing for *model*, falling back and warning if unknown."""
     if model.startswith("codex_cli/"):
         return {"input": 0.0, "output": 0.0}
+    if model.startswith("opencode/"):
+        return {"input": 0.0, "output": 0.0}
     if model in _PRICING:
         return _PRICING[model]
     if model not in _warned_models: