Loading article…

Loading 4weird…

DocsOpenCode

Docs · desktop · opencode

OpenCode on desktop, the supported way.

The desktop app drives a user-installed OpenCode binary — never a bundled copy. Pick cli mode (opencode run per fix) or server mode (long-lived opencode serve), then Export, Fix, or Heal from the desktop panel.

cli: opencode run per fix
server: opencode serve :4096
Export: BUGFIX-<game>-<stamp>
Heal: test → fix → re-test

Requirements

What you need installed

The desktop app probes PATH for the binary and degrades gracefully when it is missing — status line, Enable toggle, and Export/Fix/Heal all fall back to an install hint instead of crashing.

Install the OpenCode CLI
Install the opencode binary for your OS (Windows: package manager or npm) and confirm opencode --version prints from a fresh shell.
Put it on PATH
The desktop probes PATH — if the binary is not found you get an install hint, not an error dialog. Re-open the app after changing PATH.
Open the desktop panel
Tick Enable in the desktop OpenCode panel and pick cli or server below. The status dot goes green when the bridge can reach the binary.
Keep secrets out
Paste API keys once per shell session — never into chat, bug exports, or Heal logs. The bridge never logs secrets.

Two modes

opencode run vs opencode serve

Both modes use your installed binary. CLI mode cold-boots per fix; server mode keeps one persistent process so fixes skip the cold boot.

cli (default)

opencode run per fix

Headless opencode run -f BUGFIX-<game>-<stamp>.md per fix. Simplest setup, nothing to keep alive — best when you heal rarely.

server

opencode serve --port 4096

Long-lived sidecar (OPENCODE_MODE=server, OPENCODE_SERVER_URL=http://127.0.0.1:4096). Fixes skip the per-run boot — best for tight Heal loops.

Worked example

Your first Fix, end to end

A concrete pass through Export and Fix in cli mode: from a failing playtest to a reviewed diff, with every click and command named.

Reproduce the bug in the game
Play until the failure shows, then note the game slug, the screen, and the input sequence. The Export report is only as good as these three facts.
Export the BUGFIX report
In the desktop panel, press Export. You get BUGFIX-<game>-<stamp>.md plus a JSON twin: repro steps, logs, and workspace paths the agent may touch.
Run the fix headlessly
In a shell rooted at the workspace, run opencode run -f BUGFIX-<game>-<stamp>.md. The agent edits code inside the workspace root and prints the files it changed.
Review the diff before keeping it
Read every hunk in git diff. Keep the hunks that match the repro, revert the rest, then re-run the same playtest. Clean on the second pass means the fix held.
Escalate to Heal when it recurs
If the failure returns on retest, press Heal instead of re-running by hand. The loop in Heal loops repeats test, fix, retest until clean or the budget trips.

Troubleshooting

When the panel stays red

Four common failure shapes, each with the fastest check first. All of them are local PATH or process issues, never account issues.

Binary not found after install

Close and re-open the desktop app so it re-reads PATH, then run opencode --version in a fresh shell. Package-manager shims often land on PATH only for new processes.

Server mode refuses to connect

Confirm opencode serve --port 4096 is still running and OPENCODE_SERVER_URL=http://127.0.0.1:4096 matches the port. A second serve on another port splits the brain: kill extras, keep one.

Fix edits files outside the game

Re-check the working-dir picker: runs must root at the game workspace. Re-export after picking the right folder, since the report snapshots the paths it may touch.

Run hangs with no output

Press stop, shorten the per-run timeout, and re-run with a smaller report. Streaming stdout and stderr should resume line by line; silence past the timeout means the process wedged, not that it is thinking.

Next steps

Where to go from here

🖥️ Web terminal + desktop panel

What /terminal runs locally vs what the desktop panel drives.

Read the slice →

🔁 Bugtest → fix → retest

Heal loops, token budgets, coin quotes, and MCP pay (queued future).

Read the slice →

Loading article…

DocsOpenCode

Docs · desktop · opencode

OpenCode on desktop, the supported way.

cli: opencode run per fix
server: opencode serve :4096
Export: BUGFIX-<game>-<stamp>
Heal: test → fix → re-test

Requirements

What you need installed

The desktop app probes PATH for the binary and degrades gracefully when it is missing — status line, Enable toggle, and Export/Fix/Heal all fall back to an install hint instead of crashing.

Install the OpenCode CLI
Install the opencode binary for your OS (Windows: package manager or npm) and confirm opencode --version prints from a fresh shell.
Put it on PATH
The desktop probes PATH — if the binary is not found you get an install hint, not an error dialog. Re-open the app after changing PATH.
Open the desktop panel
Tick Enable in the desktop OpenCode panel and pick cli or server below. The status dot goes green when the bridge can reach the binary.
Keep secrets out
Paste API keys once per shell session — never into chat, bug exports, or Heal logs. The bridge never logs secrets.

Two modes

opencode run vs opencode serve

Both modes use your installed binary. CLI mode cold-boots per fix; server mode keeps one persistent process so fixes skip the cold boot.

cli (default)

opencode run per fix

Headless opencode run -f BUGFIX-<game>-<stamp>.md per fix. Simplest setup, nothing to keep alive — best when you heal rarely.

server

opencode serve --port 4096

Long-lived sidecar (OPENCODE_MODE=server, OPENCODE_SERVER_URL=http://127.0.0.1:4096). Fixes skip the per-run boot — best for tight Heal loops.

Worked example

Your first Fix, end to end

A concrete pass through Export and Fix in cli mode: from a failing playtest to a reviewed diff, with every click and command named.

Reproduce the bug in the game
Play until the failure shows, then note the game slug, the screen, and the input sequence. The Export report is only as good as these three facts.
Export the BUGFIX report
In the desktop panel, press Export. You get BUGFIX-<game>-<stamp>.md plus a JSON twin: repro steps, logs, and workspace paths the agent may touch.
Run the fix headlessly
In a shell rooted at the workspace, run opencode run -f BUGFIX-<game>-<stamp>.md. The agent edits code inside the workspace root and prints the files it changed.
Review the diff before keeping it
Read every hunk in git diff. Keep the hunks that match the repro, revert the rest, then re-run the same playtest. Clean on the second pass means the fix held.
Escalate to Heal when it recurs
If the failure returns on retest, press Heal instead of re-running by hand. The loop in Heal loops repeats test, fix, retest until clean or the budget trips.

Troubleshooting

When the panel stays red

Four common failure shapes, each with the fastest check first. All of them are local PATH or process issues, never account issues.

Binary not found after install

Close and re-open the desktop app so it re-reads PATH, then run opencode --version in a fresh shell. Package-manager shims often land on PATH only for new processes.

Server mode refuses to connect

Confirm opencode serve --port 4096 is still running and OPENCODE_SERVER_URL=http://127.0.0.1:4096 matches the port. A second serve on another port splits the brain: kill extras, keep one.

Fix edits files outside the game

Re-check the working-dir picker: runs must root at the game workspace. Re-export after picking the right folder, since the report snapshots the paths it may touch.

Run hangs with no output

Next steps

Where to go from here

🖥️ Web terminal + desktop panel

What /terminal runs locally vs what the desktop panel drives.

Read the slice →

🔁 Bugtest → fix → retest

Heal loops, token budgets, coin quotes, and MCP pay (queued future).

Read the slice →

OpenCode on desktop, the supported way.

What you need installed

Install the OpenCode CLI

Put it on PATH

Open the desktop panel

Keep secrets out

opencode run vs opencode serve

Your first Fix, end to end

Reproduce the bug in the game

Export the BUGFIX report

Run the fix headlessly

Review the diff before keeping it

Escalate to Heal when it recurs

When the panel stays red

Where to go from here

OpenCode on desktop, the supported way.

What you need installed

Install the OpenCode CLI

Put it on PATH

Open the desktop panel

Keep secrets out

opencode run vs opencode serve

Your first Fix, end to end

Reproduce the bug in the game

Export the BUGFIX report

Run the fix headlessly

Review the diff before keeping it

Escalate to Heal when it recurs

When the panel stays red

Where to go from here