Files
Nathaniel Caldwell 7b9b2f9a31 Keep an OpenCode builder's edits off Craft Anything's records (R2.2) (#1853)
An OpenCode builder runs with `--auto`, so it once wrote its notes into `inbox/build-progress.json` and stopped the build. A build's OpenCode config now carries permission rules that deny its edit tool every record Craft Anything keeps in the project (`craft.json`, `feed.json`, `inbox/`, `investigation.cany/`, `reference/`…, from `workspace::OWN_NAMES`), except `checks/`, in either project layout. Chats and questions are unchanged. Its shell and folders outside the project aren't covered (roadmap R2.2).
2026-11-14 14:55:00 +07:00

9.9 KiB

OpenCode as an AI backend

Craft Anything can run OpenCode V2 locally or on an SSH host. OpenCode owns its provider connections and sign-in. Set these up in OpenCode on the computer where it will run.

Model and thinking choices can be discovered, validated and saved. A run with an explicit selection goes through the native adapter (opencode run --standalone), which hands the run the Craft Anything MCP server in a config file named by OPENCODE_CONFIG; the person's own settings stay unchanged. Over SSH one ssh run checks that craft-anything-cli is on the remote PATH and writes the file on the host itself (~/.cache/craft-anything/, named by its content, kept private), so the remote run gets the same tools. The host needs craft-anything-cli on its PATH — install Craft Anything there (the app keeps the helper next to it). If the check fails, the turn stops before any work with the fix.

Which OpenCode. Runs need OpenCode 2.x, whose run has --standalone. OpenCode's install script and npm's opencode-ai package still give the 1.x line (1.19.5 on 2026-11-08), which doesn't have it. 2.x comes from npm's @opencode/cli package (npm install -g @opencode/cli), with the OpenCode desktop app, whose CLI is opencode-cli in the app's resources folder (/opt/OpenCode/resources/opencode-cli from the Linux package), and from OpenCode's GitHub releases. When the opencode on your PATH is 1.x, install @opencode/cli, or point the backend at a 2.x CLI: step 2 below, or craft-anything-cli ai program OpenCode <path>.

Don't start OpenCode during a build. OpenCode's shared service resumes every session it finds running, including the one a build's private server is driving: started mid-build (opening the desktop app does it), it ran the builder's commands alongside the build, and the turn ended with an error that had no details. Open the desktop app before or after a build, not during one.

Desktop

  1. Open Settings → AI → Detect, then add OpenCode, or OpenCode on <host>. Remote suggestions come from SSH aliases; they do not confirm that OpenCode is installed.
  2. If needed, choose the local program, or enter its full path in Remote program.
  3. Under the backend, click Change… to load the models from that OpenCode installation.
  4. Choose a model and, if available, a Thinking depth, then Apply.

The model picker lists only enabled chat models returned by OpenCode. Provider/model ids distinguish similarly named models and preserve custom aliases. The five thinking depths are Low, Medium, High, Xhigh and Max; only those reported as variants of the selected model are offered. A model can offer fewer depths, or none.

OpenCode default delegates model choice to OpenCode. Model default leaves thinking to the selected model. Changing the draft model resets its draft thinking depth. Reload models refreshes both lists after provider or configuration changes. A missing saved model or variant is marked unavailable; there is no fallback catalogue or silent downgrade.

Discovery runs in the background with deadlines and output limits. Listing models launches the selected OpenCode process, may start its background service, and may update its cache; discovery is not read-only. Local queries explicitly use the current project directory; SSH queries use the remote shell's working directory, as the existing remote runner does. Local model lists are never substituted for a remote one. Changing the program, backend settings or project invalidates an open picker. Saving an explicit choice checks it against the selected installation's live catalogue. If another task holds the session, opening or reloading the picker asks you to retry rather than querying without the project directory. An already open picker keeps its draft and any matching background result until the session can be checked again. If validation fails or is cancelled, the conversation emits its error or stopped status followed by a terminal turn event, so headless chat finishes without waiting for an agent that never started.

CLI

craft-anything-cli ai add OpenCode --kind agent_cli --model opencode
craft-anything-cli ai model OpenCode
craft-anything-cli ai model OpenCode my-provider/my-model --thinking high
craft-anything-cli ai model OpenCode --thinking max
craft-anything-cli ai model OpenCode --default

craft-anything-cli ai add "OpenCode on studio" --kind agent_cli --model opencode --ssh-host studio
craft-anything-cli ai program "OpenCode on studio" /opt/opencode/bin/opencode
craft-anything-cli ai model "OpenCode on studio"

Replace my-provider/my-model with an id from the listing. Listing an OpenCode backend also returns each model's supported thinking values. Naming a new model without --thinking uses that model's default depth. --thinking alone applies to the configured explicit model.

The ai_models_list and ai_model_set tools expose the same discovery and validation to MCP and other headless clients. For example, ai_model_set accepts {"name":"OpenCode","model":"my-provider/my-model","thinking":"high"}. Omit both model and thinking to restore the OpenCode default. ai_models_list returns a total and a page controlled by offset and limit (200 by default, at most 1000); the desktop picker and ai model command load the whole bounded catalogue.

Configuration and execution

The agent identity stays model = "opencode". Its optional choices are saved separately:

[[ai.backends]]
name = "OpenCode"
kind = "agent_cli"
model = "opencode"
cli_model = "my-provider/my-model"
cli_thinking = "high"

These fields extend the existing versioned settings file. Old settings without them retain OpenCode's defaults; a known variant embedded in an existing cli_model reference is read into cli_thinking. A model-only command uses opencode run --model provider/model; adding a thinking depth uses opencode run --model provider/model#variant. The shared Effort type represents all five levels. OpenCode's cli_thinking remains a separate setting from API/Claude effort: an unavailable OpenCode variant is refused, never stepped down. Hub and tool selections use the same save path: reread the settings file strictly, preserve unrelated disk changes, and reject a changed backend or project. Malformed settings are left untouched, and the session is updated only after a successful save. Closing the app also preserves the latest AI selection. If a running tool holds the session, pending non-AI app settings are kept in config.pending.toml instead of waiting for the tool or overwriting its settings. At the next startup they are merged with the latest saved AI table; the sidecar is removed after recovery or a successful full exit save that supersedes it. It uses the existing settings schema and migrations; unreadable or newer files are not overwritten by recovery. The current ACP transport cannot select models or variants. An explicit choice bypasses ACP even if acp = true was previously set and runs natively. OpenCode V2 ignores OPENCODE_CONFIG_CONTENT, and plain opencode run hands the turn to the background service, which never sees the run's environment; so the adapter writes the server to a config file and starts a private server with --standalone (locally in this computer's temporary folder, over SSH on the host itself). V2 names a tool call id (V1: callID); both are read, so tool calls reach the feed while the turn runs.

A builder runs with --auto, so it never asks us before it edits. For a build, the same config file carries OpenCode permissions rules that deny its edit tool Craft Anything's records: each name in the project folder that Craft Anything keeps (craft.json, feed.json, inbox/, investigation.cany/, reference/…, from workspace::OWN_NAMES) and everything under it. checks/ is left out, since the builder keeps its notes there. OpenCode enforces a configured deny under --auto, and the rules hold whether the app is in app/ or in the project folder itself. Every other edit goes on as before. The shell isn't covered: a command can still write anywhere, and a builder isn't kept out of folders outside the project (both wait on R2.2's approval decision). Chats and questions get the server alone.

A --standalone turn still keeps its session in OpenCode's shared storage. If the turn is stopped part-way, the session stays running, and the background service picks it up the next time it starts and carries on with the builder's commands (#1115, seen with 2.2.5 on Windows). So a local turn that doesn't finish (stopped, failed or timed out) deletes its session with opencode session delete --standalone <id>, which removes it without resuming it (over SSH, on the host). A turn that finishes keeps its session. While a turn runs, its session is recorded in logs/unfinished-sessions/ in the config folder, under a lock the system drops when Craft Anything ends; if Craft Anything is killed mid-turn, the desktop app sweeps the records when it starts, and the next agent turn or craft-anything-cli uninstall does too. A delete that keeps failing is given up after three tries, with the command to run by hand.

Model discovery uses opencode api model.list --param location[directory]=... (the V2 GET /api/model operation). This keeps credentials and configuration resolution inside OpenCode. Global --server and --standalone arguments are shared with discovery. Without a --server, discovery adds --standalone itself, as runs do: plain api starts OpenCode's shared service, which resumes every unfinished session on the computer, in any project, and carries on with its commands (#1115). The model check before each turn is a discovery, so without it every build could wake an old session somewhere else. Extra model arguments remain available when no model or thinking selection is saved. With an explicit selection, conflicting extra model arguments are refused; choose the model through its settings instead.