---
title: Testing OpenCode Plan Locally
description: Step-by-step guide to test check-progress, detect-potential-problems, and recommend-steps locally using the CLI
---

# 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:

```bash
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:

```bash
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:

```bash
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.

```bash
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:

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

## 4. Optional: .env File

<Info>
  You can store your token and OpenCode settings in a `.env` file so you don't need to pass `-t` and OpenCode options every time.
</Info>

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

```bash
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:

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

## 5. Troubleshooting

| Issue | Solution |
|-------|----------|
| "Missing required AI configuration" | Set `OPENCODE_SERVER_URL` and `OPENCODE_MODEL` (or use `--opencode-server-url` and `--opencode-model`). |
| "Git repository not found" | Ensure you're in a repo with `origin` set to a GitHub URL. |
| Connection refused to OpenCode | Start the OpenCode server (`npx opencode-ai serve`) before running the CLI. |
| No branch found for issue | Ensure the issue has a linked branch (e.g. `feature/123-title`); run the issue workflow first or create the branch manually. |

For more details, see [OpenCode (AI)](/opencode-integration) and [Troubleshooting](/troubleshooting).