From 066a876f3da55fb57e0883b22d1cf9930f08092f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Haris=20Gu=C5=A1i=C4=87?= <harisgusic.dev@gmail.com>
Date: Mon, 17 Nov 2025 21:28:06 +0100
Subject: [PATCH] docs(contributing): Add "Setting up a Debugger" section
 (#4421)

Co-authored-by: GitHub Action <action@github.com>
---
 .vscode/launch.example.json   | 11 +++++++++++
 .vscode/settings.example.json |  5 +++++
 CONTRIBUTING.md               | 32 ++++++++++++++++++++++++++++++++
 3 files changed, 48 insertions(+)
 create mode 100644 .vscode/launch.example.json
 create mode 100644 .vscode/settings.example.json

diff --git a/.vscode/launch.example.json b/.vscode/launch.example.json
new file mode 100644
index 00000000..3f8a2a76
--- /dev/null
+++ b/.vscode/launch.example.json
@@ -0,0 +1,11 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "bun",
+      "request": "attach",
+      "name": "opencode (attach)",
+      "url": "ws://localhost:6499/"
+    }
+  ]
+}
diff --git a/.vscode/settings.example.json b/.vscode/settings.example.json
new file mode 100644
index 00000000..05bbf7fe
--- /dev/null
+++ b/.vscode/settings.example.json
@@ -0,0 +1,5 @@
+{
+  "recommendations": [
+    "oven.bun-vscode"
+  ]
+}
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index ecfa7b3d..2fc5737d 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -42,6 +42,38 @@ Want to take on an issue? Leave a comment and a maintainer may assign it to you
 > [!NOTE]
 > After touching `packages/opencode/src/server/server.ts`, run "./packages/sdk/js/script/build.ts" to regenerate the JS sdk.
 
+### Setting up a Debugger
+
+Bun debugging is currently rough around the edges. We hope this guide helps you get set up and avoid some pain points.
+
+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. Other methods can result in breakpoints being mapped incorrectly, at least in VSCode (YMMV).
+
+Caveats:
+
+- `*.tsx` files won't have their breakpoints correctly mapped. This seems due to Bun currently not supporting source maps on code transformed
+  via `BunPlugin`s (currently necessary due to our dependency on `@opentui/solid`). Currently, the best you can do in terms of debugging `*.tsx`
+  files is writing a `debugger;` statement. Debugging facilities like stepping won't work, but at least you will be informed if a specific code
+  is triggered.
+- 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
+  the usual `bun dev`. This is because `bun dev` runs the server in a worker thread and breakpoints might not work there.
+
+Other tips and tricks:
+
+- You might want to use `--inspect-wait` or `--inspect-brk` instead of `--inspect`, depending on your workflow
+- Specifying `--inspect=ws://localhost:6499/` on every invocation can be tiresome, you may want to `export BUN_OPTIONS=--inspect=ws://localhost:6499/` instead
+
+#### VSCode Setup
+
+If 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).
+
+Some debug methods that can be problematic:
+
+- Debug configurations with `"request": "launch"` can have breakpoints incorrectly mapped and thus unusable
+- The same problem arises when running OpenCode in the VSCode `JavaScript Debug Terminal`
+
+With that said, you may want to try these methods, as they might work for you.
+
 ## Pull Request Expectations
 
 - Try to keep pull requests small and focused.