Testing OpenCode Plan Locally

This guide walks you through testing the OpenCode Plan flows (check-progress, detect-potential-problems, recommend-steps) locally using the copilot CLI, without running GitHub Actions.

Prerequisites

1. Node.js 20 – Use nvm use 20 if you have nvm.
2. Git repository – A repo with origin pointing to GitHub (e.g. github.com/owner/repo).
3. Personal Access Token (PAT) – Fine-grained PAT with repo and project access. Set PERSONAL_ACCESS_TOKEN in your environment or use -t / --token.
4. OpenCode server – Must be running and reachable (default: http://localhost:4096).

1. Start the OpenCode Server

In a separate terminal, start the OpenCode server:

npx opencode-ai serve
# or
opencode serve --port 4096

Ensure the server is healthy before running the CLI. The default URL is http://localhost:4096.

2. Build the CLI

From the copilot repository root:

nvm use 20
npm install
npm run build

3. Run the Commands

Execute commands from the target repository (the repo you want to analyze), or from any directory where git config remote.origin.url points to a valid GitHub repo.

Check progress

Analyzes the branch diff vs the issue description and posts a progress percentage on the issue:

node build/cli/index.js check-progress -i <issue-number> -t <PAT>
# Example
node build/cli/index.js check-progress -i 123 -t ghp_xxxx

Options:

• -i, --issue <number> – Issue number (required)
• -b, --branch <name> – Branch name (optional; will try to determine from issue)
• -t, --token <token> – PAT (or use PERSONAL_ACCESS_TOKEN env)
• --opencode-server-url <url> – Override OpenCode URL
• --opencode-model <model> – Override model (e.g. opencode/kimi-k2.5-free, anthropic/claude-3-5-sonnet)
• -d, --debug – Verbose logs

Detect potential problems (Bugbot)

Analyzes the branch vs base and reports findings as comments on the issue and review comments on open PRs; updates issue comments and marks PR review threads as resolved when findings are fixed.

node build/cli/index.js detect-potential-problems -i <issue-number> -t <PAT>
# Optional: -b <branch> (defaults to current git branch)

Recommend steps

Recommends implementation steps from the issue description:

node build/cli/index.js recommend-steps -i <issue-number> -t <PAT>

4. Optional: .env File

Create a .env file in the repo root (do not commit it):

PERSONAL_ACCESS_TOKEN=ghp_xxxx
OPENCODE_SERVER_URL=http://localhost:4096
OPENCODE_MODEL=opencode/kimi-k2.5-free

Then you can run without passing -t every time:

node build/cli/index.js check-progress -i 123

5. Troubleshooting

For more details, see OpenCode (AI) and Troubleshooting.