Skip to main content
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:

Bug Fixes

Help us squash bugs and improve stability

LSPs & Formatters

Add support for new language servers and formatters

LLM Performance

Improvements to AI model behavior and performance

Provider Support

Support for new AI providers

Environment Fixes

Platform-specific quirks and edge cases

Documentation

Improve docs, guides, and examples
UI or core product features must go through a design review with the core team before implementation. Open an issue first to discuss.

​
Finding Issues

Looking for something to work on? Check out these labels:
  • help wanted - Issues where we’d love community help
  • good first issue - Great starting points for new contributors
  • bug - Known bugs that need fixing
  • perf - Performance improvements
Want to take on an issue? Leave a comment and a maintainer may assign it to you. Please wait for assignment before starting work.

​
Adding New Providers

New providers shouldn’t require code changes to OpenCode. First make a PR to: 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: 
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: 
bun dev <directory>
To run OpenCode in the root of the opencode repo itself: 
bun dev .

​
Building a Local Binary

To compile a standalone executable: 
./packages/opencode/script/build.ts --single
Then run it with: 
./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
  • 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

During development, bun dev is the local equivalent of the built opencode command. Both run the same CLI interface:
# 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
To start the OpenCode headless API server:
bun dev serve
This starts the headless server on port 4096 by default. You can specify a different port:
bun dev serve --port 8080
To test UI changes during development:
  1. First, start the OpenCode server: 
    bun dev serve
  2. Then run the web app: 
    bun run --cwd packages/app dev
This starts a local dev server at http://localhost:5173. Most UI changes can be tested here, but the server must be running for full functionality.
The desktop app is a native Tauri application that wraps the web UI.To run the native desktop app:
bun run --cwd packages/desktop tauri dev
This starts the web dev server on http://localhost:1420 and opens the native window.If you only want the web dev server (no native shell):
bun run --cwd packages/desktop dev
To create a production build:
bun run --cwd packages/desktop tauri build
Running the desktop app requires additional Tauri dependencies (Rust toolchain, platform-specific libraries). See the Tauri prerequisites for setup instructions.
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.
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.
Please try to follow the style guide.

​
Pull Request Guidelines

​
Issue First Policy

All PRs must reference an existing issue. PRs without a linked issue may be closed without review.
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

Long, AI-generated PR descriptions and issues are not acceptable and may be ignored.
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 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: Thank you for contributing to OpenCode!