> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/anomalyco/opencode/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing

> Guide to contributing to OpenCode

We want to make it easy for you to contribute to OpenCode. This guide covers everything you need to know about contributing to the project.

## Welcome Contributions

The following types of changes are commonly accepted:

<CardGroup cols={2}>
  <Card title="Bug Fixes" icon="bug">
    Help us squash bugs and improve stability
  </Card>

  <Card title="LSPs & Formatters" icon="code">
    Add support for new language servers and formatters
  </Card>

  <Card title="LLM Performance" icon="brain">
    Improvements to AI model behavior and performance
  </Card>

  <Card title="Provider Support" icon="server">
    Support for new AI providers
  </Card>

  <Card title="Environment Fixes" icon="wrench">
    Platform-specific quirks and edge cases
  </Card>

  <Card title="Documentation" icon="book">
    Improve docs, guides, and examples
  </Card>
</CardGroup>

<Warning>
  **UI or core product features** must go through a design review with the core team before implementation. Open an issue first to discuss.
</Warning>

## Finding Issues

Looking for something to work on? Check out these labels:

* [`help wanted`](https://github.com/anomalyco/opencode/issues?q=is%3Aissue%20state%3Aopen%20label%3Ahelp-wanted) - Issues where we'd love community help
* [`good first issue`](https://github.com/anomalyco/opencode/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22) - Great starting points for new contributors
* [`bug`](https://github.com/anomalyco/opencode/issues?q=is%3Aissue%20state%3Aopen%20label%3Abug) - Known bugs that need fixing
* [`perf`](https://github.com/anomalyco/opencode/issues?q=is%3Aopen%20is%3Aissue%20label%3A%22perf%22) - Performance improvements

<Tip>
  Want to take on an issue? Leave a comment and a maintainer may assign it to you. Please wait for assignment before starting work.
</Tip>

## Adding New Providers

New providers shouldn't require code changes to OpenCode. First make a PR to:
[https://github.com/anomalyco/models.dev](https://github.com/anomalyco/models.dev)

## Development Setup

### Requirements

* Bun 1.3 or higher

### Getting Started

Install dependencies and start the dev server from the repo root:

```bash theme={null}
bun install
bun dev
```

### Running Against Different Directories

By default, `bun dev` runs OpenCode in the `packages/opencode` directory. To run it against a different directory:

```bash theme={null}
bun dev <directory>
```

To run OpenCode in the root of the opencode repo itself:

```bash theme={null}
bun dev .
```

### Building a Local Binary

To compile a standalone executable:

```bash theme={null}
./packages/opencode/script/build.ts --single
```

Then run it with:

```bash theme={null}
./packages/opencode/dist/opencode-<platform>/bin/opencode
```

Replace `<platform>` with your platform (e.g., `darwin-arm64`, `linux-x64`).

## Project Structure

Core pieces of the codebase:

* `packages/opencode` - OpenCode core business logic & server
* `packages/opencode/src/cli/cmd/tui/` - The TUI code, written in SolidJS with [opentui](https://github.com/sst/opentui)
* `packages/app` - The shared web UI components, written in SolidJS
* `packages/desktop` - The native desktop app, built with Tauri
* `packages/plugin` - Source for `@opencode-ai/plugin`

## Development Workflows

<AccordionGroup>
  <Accordion title="Understanding bun dev vs opencode" icon="terminal">
    During development, `bun dev` is the local equivalent of the built `opencode` command. Both run the same CLI interface:

    ```bash theme={null}
    # Development (from project root)
    bun dev --help           # Show all available commands
    bun dev serve            # Start headless API server
    bun dev web              # Start server + open web interface
    bun dev <directory>      # Start TUI in specific directory

    # Production
    opencode --help          # Show all available commands
    opencode serve           # Start headless API server
    opencode web             # Start server + open web interface
    opencode <directory>     # Start TUI in specific directory
    ```
  </Accordion>

  <Accordion title="Running the API Server" icon="server">
    To start the OpenCode headless API server:

    ```bash theme={null}
    bun dev serve
    ```

    This starts the headless server on port 4096 by default. You can specify a different port:

    ```bash theme={null}
    bun dev serve --port 8080
    ```
  </Accordion>

  <Accordion title="Running the Web App" icon="browser">
    To test UI changes during development:

    1. **First, start the OpenCode server:**
       ```bash theme={null}
       bun dev serve
       ```

    2. **Then run the web app:**
       ```bash theme={null}
       bun run --cwd packages/app dev
       ```

    This starts a local dev server at [http://localhost:5173](http://localhost:5173). Most UI changes can be tested here, but the server must be running for full functionality.
  </Accordion>

  <Accordion title="Running the Desktop App" icon="desktop">
    The desktop app is a native Tauri application that wraps the web UI.

    To run the native desktop app:

    ```bash theme={null}
    bun run --cwd packages/desktop tauri dev
    ```

    This starts the web dev server on [http://localhost:1420](http://localhost:1420) and opens the native window.

    If you only want the web dev server (no native shell):

    ```bash theme={null}
    bun run --cwd packages/desktop dev
    ```

    To create a production build:

    ```bash theme={null}
    bun run --cwd packages/desktop tauri build
    ```

    <Note>
      Running the desktop app requires additional Tauri dependencies (Rust toolchain, platform-specific libraries). See the [Tauri prerequisites](https://v2.tauri.app/start/prerequisites/) for setup instructions.
    </Note>
  </Accordion>

  <Accordion title="Setting up a Debugger" icon="bug">
    Bun debugging is currently rough around the edges. The most reliable way to debug OpenCode is to run it manually in a terminal via `bun run --inspect=<url> dev ...` and attach your debugger via that URL.

    **Caveats:**

    * If you want to debug server code with the TUI, you might need to run `bun dev spawn` instead of `bun dev`
    * You can debug the server separately:
      * Debug server: `bun run --inspect=ws://localhost:6499/ --cwd packages/opencode ./src/index.ts serve --port 4096`
      * Then attach TUI: `opencode attach http://localhost:4096`
      * Debug TUI: `bun run --inspect=ws://localhost:6499/ --cwd packages/opencode --conditions=browser ./src/index.ts`

    **Tips:**

    * Use `--inspect-wait` or `--inspect-brk` for different workflows
    * Set `export BUN_OPTIONS=--inspect=ws://localhost:6499/` to avoid repeating the flag

    **VSCode Setup:**

    See `.vscode/settings.example.json` and `.vscode/launch.example.json` for example configurations.
  </Accordion>
</AccordionGroup>

<Note>
  If you make changes to the API or SDK (e.g. `packages/opencode/src/server/server.ts`), run `./script/generate.ts` to regenerate the SDK and related files.
</Note>

Please try to follow the [style guide](https://github.com/anomalyco/opencode/blob/dev/AGENTS.md).

## Pull Request Guidelines

### Issue First Policy

<Warning>
  **All PRs must reference an existing issue.** PRs without a linked issue may be closed without review.
</Warning>

Before opening a PR, open an issue describing the bug or feature. This helps maintainers triage and prevents duplicate work.

* Use `Fixes #123` or `Closes #123` in your PR description to link the issue
* For small fixes, a brief issue is fine - just enough context to understand the problem

### General Requirements

* Keep pull requests small and focused
* Explain the issue and why your change fixes it
* Before adding new functionality, ensure it doesn't already exist elsewhere in the codebase

### UI Changes

If your PR includes UI changes, please include screenshots or videos showing the before and after. This helps maintainers review faster.

### Logic Changes

For non-UI changes (bug fixes, new features, refactors), explain **how you verified it works**:

* What did you test?
* How can a reviewer reproduce/confirm the fix?

### No AI-Generated Walls of Text

<Warning>
  Long, AI-generated PR descriptions and issues are not acceptable and may be ignored.
</Warning>

Respect the maintainers' time:

* Write short, focused descriptions
* Explain what changed and why in your own words
* If you can't explain it briefly, your PR might be too large

### PR Titles

PR titles should follow conventional commit standards:

* `feat:` new feature or functionality
* `fix:` bug fix
* `docs:` documentation or README changes
* `chore:` maintenance tasks, dependency updates, etc.
* `refactor:` code refactoring without changing behavior
* `test:` adding or updating tests

You can optionally include a scope:

* `feat(app):` feature in the app package
* `fix(desktop):` bug fix in the desktop package
* `chore(opencode):` maintenance in the opencode package

**Examples:**

* `docs: update contributing guidelines`
* `fix: resolve crash on startup`
* `feat: add dark mode support`
* `feat(app): add dark mode support`
* `fix(desktop): resolve crash on startup`
* `chore: bump dependency versions`

### Style Preferences

These are general guidelines, not strictly enforced:

* **Functions:** Keep logic within a single function unless breaking it out adds clear reuse or composition benefits
* **Destructuring:** Avoid unnecessary destructuring of variables
* **Control flow:** Avoid `else` statements
* **Error handling:** Prefer `.catch(...)` instead of `try`/`catch` when possible
* **Types:** Use precise types and avoid `any`
* **Variables:** Stick to immutable patterns and avoid `let`
* **Naming:** Choose concise single-word identifiers when descriptive
* **Runtime APIs:** Use Bun helpers such as `Bun.file()` when appropriate

## Feature Requests

For net-new functionality, start with a design conversation. Open an issue describing:

* The problem you're trying to solve
* Your proposed approach (optional)
* Why it belongs in OpenCode

Wait for core team approval before opening a feature PR.

## Trust & Vouch System

This project uses [vouch](https://github.com/mitchellh/vouch) to manage contributor trust. The vouch list is maintained in `.github/VOUCHED.td`.

### How it works

* **Vouched users** are explicitly trusted contributors
* **Denounced users** are explicitly blocked. Issues and pull requests from denounced users are automatically closed
* **Everyone else** can participate normally — you don't need to be vouched to open issues or PRs

### For maintainers

Collaborators with write access can manage the vouch list by commenting on any issue:

* `vouch` — vouch for the issue author
* `vouch @username` — vouch for a specific user
* `denounce` — denounce the issue author
* `denounce @username` — denounce a specific user
* `denounce @username <reason>` — denounce with a reason
* `unvouch` / `unvouch @username` — remove someone from the list

Changes are committed automatically to `.github/VOUCHED.td`.

### Denouncement Policy

Denouncement is reserved for users who repeatedly submit low-quality AI-generated contributions, spam, or otherwise act in bad faith. It is not used for disagreements or honest mistakes.

## Issue Requirements

All issues **must** use one of our issue templates:

* **Bug report** — for reporting bugs (requires a description)
* **Feature request** — for suggesting enhancements (requires verification checkbox and description)
* **Question** — for asking questions (requires the question)

Blank issues are not allowed. When a new issue is opened, an automated check verifies that it follows a template and meets our contributing guidelines. If an issue doesn't meet the requirements, you'll receive a comment explaining what needs to be fixed and have **2 hours** to edit the issue. After that, it will be automatically closed.

Issues may be flagged for:

* Not using a template
* Required fields left empty or filled with placeholder text
* AI-generated walls of text
* Missing meaningful content

If you believe your issue was incorrectly flagged, let a maintainer know.

## Community

Join the OpenCode community:

* [Discord](https://opencode.ai/discord) - Chat with the community and maintainers
* [GitHub Discussions](https://github.com/anomalyco/opencode/discussions) - Ask questions and share ideas
* [Twitter](https://twitter.com/opencode_ai) - Stay updated with the latest news

Thank you for contributing to OpenCode!