openAgent

1# Contributing to OpenCode
2 
3We want to make it easy for you to contribute to OpenCode. Here are the most common type of changes that get merged:
4 
5- Bug fixes
6- Additional LSPs / Formatters
7- Improvements to LLM performance
8- Support for new providers
9- Fixes for environment-specific quirks
10- Missing standard behavior
11- Documentation improvements
12 
13However, any UI or core product feature must go through a design review with the core team before implementation.
14 
15If you are unsure if a PR would be accepted, feel free to ask a maintainer or look for issues with any of the following labels:
16 
17- [`help wanted`](https://github.com/anomalyco/opencode/issues?q=is%3Aissue%20state%3Aopen%20label%3Ahelp-wanted)
18- [`good first issue`](https://github.com/anomalyco/opencode/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22)
19- [`bug`](https://github.com/anomalyco/opencode/issues?q=is%3Aissue%20state%3Aopen%20label%3Abug)
20- [`perf`](https://github.com/anomalyco/opencode/issues?q=is%3Aopen%20is%3Aissue%20label%3A%22perf%22)
21 
22> [!NOTE]
23> PRs that ignore these guardrails will likely be closed.
24 
25Want to take on an issue? Leave a comment and a maintainer may assign it to you unless it is something we are already working on.
26 
27## Adding New Providers
28 
29New providers shouldn't require many if ANY code changes, but if you want to add support for a new provider first make a PR to:
30https://github.com/anomalyco/models.dev
31 
32## Developing OpenCode
33 
34- Requirements: Bun 1.3+
35- Install dependencies and start the dev server from the repo root:
36 
37  ```bash
38  bun install
39  bun dev
40  ```
41 
42### Running against a different directory
43 
44By default, `bun dev` runs OpenCode in the `packages/opencode` directory. To run it against a different directory or repository:
45 
46```bash
47bun dev <directory>
48```
49 
50To run OpenCode in the root of the opencode repo itself:
51 
52```bash
53bun dev .
54```
55 
56### Building a "localcode"
57 
58To compile a standalone executable:
59 
60```bash
61./packages/opencode/script/build.ts --single
62```
63 
64Then run it with:
65 
66```bash
67./packages/opencode/dist/opencode-<platform>/bin/opencode
68```
69 
70Replace `<platform>` with your platform (e.g., `darwin-arm64`, `linux-x64`).
71 
72- Core pieces:
73  - `packages/opencode`: OpenCode core business logic & server.
74  - `packages/opencode/src/cli/cmd/tui/`: The TUI code, written in SolidJS with [opentui](https://github.com/sst/opentui)
75  - `packages/app`: The shared web UI components, written in SolidJS
76  - `packages/desktop`: The native desktop app, built with Electron (wraps `packages/app`)
77  - `packages/plugin`: Source for `@opencode-ai/plugin`
78 
79### Understanding bun dev vs opencode
80 
81During development, `bun dev` is the local equivalent of the built `opencode` command. Both run the same CLI interface:
82 
83```bash
84# Development (from project root)
85bun dev --help           # Show all available commands
86bun dev serve            # Start headless API server
87bun dev web              # Start server + open web interface
88bun dev <directory>      # Start TUI in specific directory
89 
90# Production
91opencode --help          # Show all available commands
92opencode serve           # Start headless API server
93opencode web             # Start server + open web interface
94opencode <directory>     # Start TUI in specific directory
95```
96 
97### Running the API Server
98 
99To start the OpenCode headless API server:
100 
101```bash
102bun dev serve
103```
104 
105This starts the headless server on port 4096 by default. You can specify a different port:
106 
107```bash
108bun dev serve --port 8080
109```
110 
111### Running the Web App
112 
113To test UI changes during development:
114 
1151. **First, start the OpenCode server** (see [Running the API Server](#running-the-api-server) section above)
1162. **Then run the web app:**
117 
118```bash
119bun run --cwd packages/app dev
120```
121 
122This starts a local dev server at http://localhost:5173 (or similar port shown in output). Most UI changes can be tested here, but the server must be running for full functionality.
123 
124### Running the Desktop App
125 
126The desktop app is an Electron application that wraps the web UI.
127 
128To run the desktop app in development:
129 
130```bash
131bun run --cwd packages/desktop dev
132```
133 
134To create a production build and package the app:
135 
136```bash
137bun run --cwd packages/desktop build
138bun run --cwd packages/desktop package
139```
140 
141> [!NOTE]
142> 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.
143 
144Please try to follow the [style guide](./AGENTS.md)
145 
146### Setting up a Debugger
147 
148Bun debugging is currently rough around the edges. We hope this guide helps you get set up and avoid some pain points.
149 
150The most reliable way to debug OpenCode is to run it manually in a terminal via `bun run --inspect=<url> dev ...` and attach
151your debugger via that URL. Other methods can result in breakpoints being mapped incorrectly, at least in VSCode (YMMV).
152 
153Caveats:
154 
155- If you want to run the OpenCode TUI and have breakpoints triggered in the server code, you might need to run `bun dev spawn` instead of
156  the usual `bun dev`. This is because `bun dev` runs the server in a worker thread and breakpoints might not work there.
157- If `spawn` does not work for you, you can debug the server separately:
158  - Debug server: `bun run --inspect=ws://localhost:6499/ --cwd packages/opencode ./src/index.ts serve --port 4096`,
159    then attach TUI with `opencode attach http://localhost:4096`
160  - Debug TUI: `bun run --inspect=ws://localhost:6499/ --cwd packages/opencode --conditions=browser ./src/index.ts`
161 
162Other tips and tricks:
163 
164- You might want to use `--inspect-wait` or `--inspect-brk` instead of `--inspect`, depending on your workflow
165- Specifying `--inspect=ws://localhost:6499/` on every invocation can be tiresome, you may want to `export BUN_OPTIONS=--inspect=ws://localhost:6499/` instead
166 
167#### VSCode Setup
168 
169If you use VSCode, you can use our example configurations [.vscode/settings.example.json](.vscode/settings.example.json) and [.vscode/launch.example.json](.vscode/launch.example.json).
170 
171Some debug methods that can be problematic:
172 
173- Debug configurations with `"request": "launch"` can have breakpoints incorrectly mapped and thus unusable
174- The same problem arises when running OpenCode in the VSCode `JavaScript Debug Terminal`
175 
176With that said, you may want to try these methods, as they might work for you.
177 
178## Pull Request Expectations
179 
180### Issue First Policy
181 
182**All PRs must reference an existing issue.** Before opening a PR, open an issue describing the bug or feature. This helps maintainers triage and prevents duplicate work. PRs without a linked issue may be closed without review.
183 
184- Use `Fixes #123` or `Closes #123` in your PR description to link the issue
185- For small fixes, a brief issue is fine - just enough context for maintainers to understand the problem
186 
187### General Requirements
188 
189- Keep pull requests small and focused
190- Explain the issue and why your change fixes it
191- Before adding new functionality, ensure it doesn't already exist elsewhere in the codebase
192 
193### UI Changes
194 
195If your PR includes UI changes, please include screenshots or videos showing the before and after. This helps maintainers review faster and gives you quicker feedback.
196 
197### Logic Changes
198 
199For non-UI changes (bug fixes, new features, refactors), explain **how you verified it works**:
200 
201- What did you test?
202- How can a reviewer reproduce/confirm the fix?
203 
204### No AI-Generated Walls of Text
205 
206Long, AI-generated PR descriptions and issues are not acceptable and may be ignored. Respect the maintainers' time:
207 
208- Write short, focused descriptions
209- Explain what changed and why in your own words
210- If you can't explain it briefly, your PR might be too large
211 
212### PR Titles
213 
214PR titles should follow conventional commit standards:
215 
216- `feat:` new feature or functionality
217- `fix:` bug fix
218- `docs:` documentation or README changes
219- `chore:` maintenance tasks, dependency updates, etc.
220- `refactor:` code refactoring without changing behavior
221- `test:` adding or updating tests
222 
223You can optionally include a scope to indicate which package is affected:
224 
225- `feat(app):` feature in the app package
226- `fix(desktop):` bug fix in the desktop package
227- `chore(opencode):` maintenance in the opencode package
228 
229Examples:
230 
231- `docs: update contributing guidelines`
232- `fix: resolve crash on startup`
233- `feat: add dark mode support`
234- `feat(app): add dark mode support`
235- `fix(desktop): resolve crash on startup`
236- `chore: bump dependency versions`
237 
238### Style Preferences
239 
240These are not strictly enforced, they are just general guidelines:
241 
242- **Functions:** Keep logic within a single function unless breaking it out adds clear reuse or composition benefits.
243- **Destructuring:** Do not do unnecessary destructuring of variables.
244- **Control flow:** Avoid `else` statements.
245- **Error handling:** Prefer `.catch(...)` instead of `try`/`catch` when possible.
246- **Types:** Reach for precise types and avoid `any`.
247- **Variables:** Stick to immutable patterns and avoid `let`.
248- **Naming:** Choose concise single-word identifiers when they remain descriptive.
249- **Runtime APIs:** Use Bun helpers such as `Bun.file()` when they fit the use case.
250 
251## Feature Requests
252 
253For net-new functionality, start with a design conversation. Open an issue describing the problem, your proposed approach (optional), and why it belongs in OpenCode. The core team will help decide whether it should move forward; please wait for that approval instead of opening a feature PR directly.
254 
255## Issue Requirements
256 
257All issues **must** use one of our issue templates:
258 
259- **Bug report** — for reporting bugs (requires a description)
260- **Feature request** — for suggesting enhancements (requires verification checkbox and description)
261- **Question** — for asking questions (requires the question)
262 
263Blank 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.
264 
265Issues may be flagged for:
266 
267- Not using a template
268- Required fields left empty or filled with placeholder text
269- AI-generated walls of text
270- Missing meaningful content
271 
272If you believe your issue was incorrectly flagged, let a maintainer know.
273