Skip to main content

Runtime installation

OpenCode Harness is distributed as a public Git repository. This guide installs the runtime in ~/.config/opencode; installing the documentation site is a separate process described in the repository README.

Clone the tree into the OpenCode configuration and restart the process after installation.

Step 1: Back up the current configuration (if any)​

If you already have a ~/.config/opencode with your own plugins and commands, rename the folder before cloning:

Rename-Item -LiteralPath "$env:USERPROFILE\.config\opencode" -NewName "opencode-backup"

The current installation does not automatically merge into an existing configuration. Use the backup as a reference and copy over whatever you want afterward.

Step 2: Clone the repository​

git clone https://github.com/MaiconGambini/opencode-harness-guide.git "$env:USERPROFILE\.config\opencode"

Step 3: Install runtime dependencies​

Set-Location "$env:USERPROFILE\.config\opencode"
npm ci

Step 4: Verify the installation​

npm run typecheck
npm test

If both commands return without errors, close and reopen OpenCode. The runtime loads the configuration only at startup.

Resulting structure​

After installation, ~/.config/opencode contains:

  • opencode.jsonc — global commands and plugins.
  • skills/ — skills that OpenCode loads automatically.
  • plugins/ — runtime plugins.
  • scripts/ — PowerShell and Node utilities.
  • templates/ — reusable templates (feature_list, specs, standards).
  • package.json — dependencies and verification scripts.

None of this is compiled or bundled. They are text files and scripts that OpenCode reads directly.

Troubleshooting​

ProblemAction
npm ci failsCheck that Node.js 20+ is installed (node --version).
npm run typecheck failsTypeScript may be out of date. Run npm ci and try again.
OpenCode does not load the commandsClose and reopen OpenCode. The configuration is loaded only at startup.

Next step​

Go to First Session and use the harness for the first time.