OpenCode 2 GitHub Automation

A scheduler and GitHub dispatcher in one package, built for OpenCode 2.

@opencodebot in an issue → acknowledgement → questions if needed → implementation → tests → PR.

The bot waits for answers in the issue, handles follow-up comments, chooses PR titles, and can merge after an authorized approval. The TUI is optional.

Requirements

• OpenCode 2 with a working model; tested with 0.0.0-beta-19398.
• Node.js 22+, npm, and Git on macOS/Linux.
• GitHub authentication (gh auth login and gh auth setup-git, or a token in the service environment) and permission to comment, push, and create PRs.
• When configuring a project: a primary Git checkout with a GitHub origin, a pushed commit, and issues enabled.

Choose one installation method below. No target repository is needed yet. Nothing needs to be published to npm. $HOME expands to your home directory.

Install from a .tgz package

Run this command on the machine running OpenCode 2:

Latest stable release: v0.6.3.

Download the .tgz package · SHA-256 checksum

npm install --global --prefix "$HOME/.local" "https://github.com/d3cker/opencode2-github-automation/releases/download/v0.6.3/opencode2-automation-0.6.3.tgz"

postinstall registers both the plugin and TUI automatically. No sudo, source checkout, or manual config editing is needed. Do not add --ignore-scripts; npm needs network access to install dependencies. You can also download the archive and pass its local path to the same command.

Restart the service when its sessions are idle:

opencode2 service restart

The CLI is now at $HOME/.local/bin/opencode2-automation. If $HOME/.local/bin is on your PATH, you can use the shorter opencode2-automation command. Configure a project below when ready.

Install from source

1. Clone and build:

   git clone https://github.com/d3cker/opencode2-github-automation.git "$HOME/opencode2-github-automation"
   cd "$HOME/opencode2-github-automation"
   npm ci && npm run build

2. Register the plugin and TUI:

   node "$HOME/opencode2-github-automation/dist/setup.js" install

3. Restart the idle service:

   opencode2 service restart

Keep the source directory: OpenCode loads its compiled code. npm ci in a source checkout does not register a global plugin automatically. Both installers reuse recognized older loaders and refuse to overwrite custom code. Registration defaults to ~/.config/opencode/plugins/opencode-automation/ and respects XDG_CONFIG_HOME and OPENCODE_CONFIG_DIR.

Configure a project

1. Enter your target repository and run the wizard:

   cd /absolute/path/to/your-project
   "$HOME/.local/bin/opencode2-automation" init

   Source installation: use node "$HOME/opencode2-github-automation/dist/setup.js" init instead.

2. Answer the prompts. Enter accepts the value in brackets. The wizard asks about the model and capabilities, a vision helper if needed, base branch, trigger, signature, allowed authors, polling, auto-merge, and tests. Use provider/model for model IDs and skip to skip automated tests.

3. Load the project with the headless command below, or open it with opencode2 /absolute/path/to/your-project.

Settings are saved to /absolute/path/to/your-project/.opencode/automation.json. If it already exists, edit it directly and skip init. Repeat setup for each repository; the plugin is installed only once. After editing settings, restart the idle service and reload the project.

Create an issue containing @opencodebot (or your configured trigger). The bot checks every 60 seconds by default and may also pick up existing matching issues. Only the authenticated GitHub user is allowed by default; add colleagues to authors in the JSON to let them request work.

Run without the TUI

Run once for each configured primary checkout, with its absolute path:

opencode2 api v2.plugin.awaitActivation --param 'location[directory]=/absolute/path/to/your-project'

This starts the shared service if needed and loads the project's plugins. The command exits; the bot keeps running without a TUI or extra monitoring process. Repeat it after every service restart.

For automatic startup after a machine reboot, put one invocation per project in your operating system's startup mechanism, under the same user, after networking is available. Use absolute executable/repository paths (command -v opencode2 finds the executable) and provide the usual PATH and GitHub authentication. A reboot-only task does not handle later opencode2 service restart calls.

Update from a .tgz package

Wait for active bot work to finish, then:

1. Run the versioned command in Install from a .tgz package using the same prefix as before. After publication, the README on release links to the new stable package; main receives that link through the promotion PR.

   postinstall refreshes registration; project settings and queues are preserved. Do not run init again.

2. Reload the service:

   opencode2 service restart

3. Run the headless command for each project, or open each in the TUI. Reopen existing TUI clients when the update changes the UI.

Switching from a source installation to .tgz uses the same procedure; recognized source loaders are repointed to the installed package instead of duplicated.

Update from source

Wait for active bot work to finish, then:

1. Download changes for your current branch:

   cd "$HOME/opencode2-github-automation"
   git pull --ff-only

2. Rebuild:

   npm ci && npm run build

3. Restart and reload each project:

   opencode2 service restart

Settings and queues remain in place. Do not run init again. If switching back from .tgz to source, also run the source install command after rebuilding.

Switch to the feature branch for testing

For a fresh source installation, add --branch codex/issue-dialogue-capabilities to the clone command. For an existing source checkout, replace update step 1 with:

cd "$HOME/opencode2-github-automation"
git fetch origin
git switch codex/issue-dialogue-capabilities
git pull --ff-only

Then complete source installation or update as appropriate. A .tgz contains the code from the branch used to build it; there is no Git branch to switch on the receiving machine.

Remove automation from one project

Wait for its bot sessions to finish, then:

1. Remove that project's settings:

   rm -i /absolute/path/to/your-project/.opencode/automation.json

2. Restart the service:

   opencode2 service restart

3. Reload the other projects you still want automated.

Removing the file alone does not stop an already-loaded worker. Queues, worktrees, branches, and GitHub issues/PRs are preserved. Running init again can resume saved work. If you configured the plugin through opencode.json options instead, remove those options or disable its entry too.

Uninstall the global plugin

Wait for active work to finish. Use the loader directory reported during install; older installations may use a different name. With the default directory:

1. Remove the two loaders:

   rm -i "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/plugins/opencode-automation/index.js" "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/plugins/opencode-automation/tui.js"

2. For a .tgz installation, remove the package:

   npm uninstall --global --prefix "$HOME/.local" opencode2-automation

3. Run opencode2 service restart and reopen any TUI clients.

Project settings and saved work remain on disk. Source and project-local installations are not removed by npm uninstall --global.

Configuration and everyday use

• Questions: answer in the issue using an account in authors. The bot waits for your answer; the bot and human can share a GitHub account.
• Branches: write naturally, e.g. "use branch develop". baseBranch sets the default for new work; existing tasks keep their chosen base.
• Media: the wizard can configure a separate vision model. Set actual model capabilities (text, vision, audio); helpers run in separate sessions.
• Instructions: prompts/bot.md is always loaded. Append your own Markdown with "systemPromptFile": ".opencode/bot.md".
• Merging: approve the bot's PR or post a configured merge phrase. The author must be allowed and have repository write access. Set autoMerge.enabled to false to disable this. signature controls the signature on new bot messages.
• Progress: use /bot in the TUI, or the CLI's status, scan, pause, and resume commands from the target repository. Closing a PR closes its bot tabs while retaining session history. Authorized issue comments can continue work on an open PR without another mention.

Keep machine-specific .opencode/automation.json files out of Git: global init does not add an ignore rule. See configuration and Git branches for ignore instructions, branch-switch behavior, and all JSON options.

More details: runtime behavior, installation troubleshooting and project-local installs, and advanced settings.

Alternative: install only in one project

For a project without a global installation, use the existing source installer:

bash "$HOME/opencode2-github-automation/scripts/install-local.sh" /absolute/path/to/your-project

It configures the project on first install and preserves settings on updates. Do not combine it with a global installation for the same project.

Development and building a .tgz

cd "$HOME/opencode2-github-automation"
npm ci
npm run check
npm pack

Use Node 22.13+ or 24+ for development. npm run check runs ESLint, type checking, tests, and a build. npm run package:check additionally packs and verifies a global install in a temporary directory, including postinstall and the CLI. npm pack creates opencode2-automation-<version>.tgz using the version in package.json, with compiled code and the installer; copy it to another machine and follow the .tgz instructions above. private: true prevents accidental npm publication.

GitHub Actions and releases

1. Work on a feature branch and add release notes under Unreleased in CHANGELOG.md. Ordinary branch pushes do not run CI or publish packages.
2. Open a PR into the long-lived release branch. CI runs lint, type checking, tests, a build, and an installation check on Node 22 and 24. New commits to the open PR rerun these checks. Review and merge after they pass.
3. The merge starts Release. It increments the patch version on release, moves the unreleased notes into that version's changelog section, and pushes the version commit and tag atomically. It builds and verifies the tagged package, then publishes the GitHub Release with .tgz, SHA-256, and exact version notes. No package is published to npm.
4. Only after publication succeeds, automation commits the versioned README link on release and opens or updates a PR from release into main.
5. Review and merge that PR with a merge commit. All code, version metadata, release notes, and README changes reach protected main through this PR. The automation never pushes to main or writes its files through the API.

To choose a version manually, prepare and commit its exact changelog section on release, then use npm version, for example:

git switch release
git pull --ff-only origin release
# Prepare and commit the CHANGELOG.md section for 1.0.0 first.
npm version 1.0.0
git push --atomic origin release v1.0.0

The pushed tag publishes exactly 1.0.0, without another version bump. Both v1.0.0 and 1.0.0 tag names are accepted. The next automatic patch is 1.0.1. Version tags must point to code on release; ordinary pushes to that branch never start publication. Finish the active release before merging another feature.

The README on release is updated after publication; the README on main changes when the promotion PR is merged. The tag and packaged README remain snapshots from before the later README commit.

See Release process for required repository permissions, branch protection, CI approval for bot PRs, concurrency, and safe retry procedures.