Cline rules

1# Debug Harness
2 
3HTTP-controlled debugger for the VSCode extension at `src/dev/debug-harness/server.ts`.
4 
5## Quick start
6 
7```bash
8# Build extension first if needed (protos + esbuild):
9bun run protos && IS_DEV=true bun esbuild.mjs
10 
11# Launch (skip-build if already built). Run with node, NOT bun — Playwright's
12# Electron launch times out under bun:
13node src/dev/debug-harness/server.ts --skip-build --auto-launch
14 
15# In another terminal:
16curl localhost:19229/api -d '{"method":"status"}'
17```
18 
19## Data Isolation
20 
21The debugee runs with `CLINE_DIR=~/.cline2` by default, separate from your real `~/.cline`.
22This prevents the debugee's logout from logging out the debugger, and vice versa.
23Override with `--cline-dir /tmp/test-dir`. Check with `status()` → `clineDir`.
24 
25## Browser Capture & OAuth
26 
27The debugee runs with `CLINE_CAPTURE_BROWSER=1`, which intercepts `openExternal()` in
28`src/utils/env.ts`. URLs are captured instead of opening a real browser:
29 
30- Logged to `$CLINE_DIR/data/debug-captured-urls.jsonl`
31- POSTed in real-time to `/captured-url` on the harness server
32- Queryable via `oauth.captured_urls`
33 
34### OAuth API
35 
36- **`oauth.captured_urls`** `{clear?}` — URLs the debugee tried to open
37- **`oauth.read_stored_token`** — Check auth token presence in secrets.json
38- **`oauth.simulate_callback`** `{path, code?, state?, provider?, token?}` — Build vscode:// callback URI
39- **`oauth.read_captured_urls_file`** — Read on-disk JSONL of captured URLs
40 
41### OAuth testing flow
42 
43For **Cline OAuth** (SDK local callback): The SDK starts a local HTTP server, the auth URL
44is captured. To complete: open the captured URL in a real browser (it redirects back to the
45SDK's callback server), OR extract the callback port and `curl http://127.0.0.1:PORT/callback?code=...`.
46 
47For **MCP/Provider OAuth** (vscode:// URI): The redirect goes to a vscode:// URI.
48`oauth.simulate_callback` only *builds* the URI — it does not deliver it, and the ESM
49extension host can't `require()` the handler. To actually deliver the callback, call the
50debug-only hook via `ext.evaluate` (with `awaitPromise: true`):
51`globalThis.__clineHandleUri("vscode://saoudrizwan.claude-dev/...?code=...&state=...")`.
52It runs the same `SharedUriHandler.handleUri` as VSCode's real URI handler and exists only
53when `CLINE_CAPTURE_BROWSER` is set (the harness always sets it; never ships in prod).
54For end-to-end MCP OAuth, get a real `code` from the local MCP OAuth test server
55(`bun run dev:mcp-oauth-test-server`).
56 
57## Navigating Views — Use Commands, Not Clicks
58 
59Don't try to find/click small sidebar icons. Use VSCode commands via command palette.
60Registered in `src/registry.ts`:
61 
62| Command | View |
63|---------|------|
64| `cline.accountButtonClicked` | Account / sign-in |
65| `cline.historyButtonClicked` | Task history |
66| `cline.settingsButtonClicked` | Settings |
67| `cline.mcpButtonClicked` | MCP servers |
68| `cline.plusButtonClicked` | New task (chat) |
69| `cline.worktreesButtonClicked` | Worktrees |
70 
71```bash
72curl localhost:19229/api -d '{"method":"ui.command_palette","params":{"command":"cline.accountButtonClicked"}}'
73```
74 
75## Key commands
76 
77All via `POST localhost:19229/api` with `{"method":"...", "params":{...}}`:
78 
79- **`launch`** / **`shutdown`** — lifecycle
80- **`ui.screenshot`** — screenshot to `/tmp/cline-debug/`; returns `{path}` — **use `read_file` on the path to examine, do NOT `open` the file** (Preview.app covers the VSCode window)
81- **`ui.open_sidebar`** — open the Cline sidebar
82- **`ext.set_breakpoint`** `{file, line, condition?}` — breakpoint by source file (sourcemap-resolved)
83- **`ext.evaluate`** `{expression, callFrameId?}` — eval in extension host
84- **`ext.resume`** / **`ext.step_over`** / **`ext.step_into`** — stepping
85- **`ext.call_stack`** — inspect when paused
86- **`web.evaluate`** `{expression}` — eval in webview
87- **`web.post_message`** `{message}` — send postMessage to extension host via exposed vsCodeApi
88- **`wait_for_pause`** `{timeout?}` — block until breakpoint hit
89- **`ui.locator`** `{role?, testId?, text?, frame?}` — Playwright locator (auto-retries on stale sidebar frame)
90- **`ui.react_input`** `{text, selector?, clear?, submit?}` — set React textarea value via `execCommand('insertText')`; works reliably across multiple tasks
91- **`ui.send_message`** `{text, images?, files?, responseType?}` — send chat message bypassing the textarea entirely (via gRPC postMessage)
92- **`ui.command_palette`** `{command}` — run VSCode command
93 
94## Typical Session
95 
96```bash
97# 1. Launch
98curl localhost:19229/api -d '{"method":"launch","params":{"skipBuild":true}}'
99 
100# 2. Open sidebar + dismiss overlays (ALWAYS do this first)
101curl localhost:19229/api -d '{"method":"ui.open_sidebar"}'
102curl localhost:19229/api -d '{"method":"web.evaluate","params":{"expression":"document.querySelectorAll(\".sr-only\").forEach(el => el.parentElement?.click())"}}'
103 
104# 3. Navigate to view
105curl localhost:19229/api -d '{"method":"ui.command_palette","params":{"command":"cline.accountButtonClicked"}}'
106 
107# 4. Check captured OAuth URLs if testing auth
108curl localhost:19229/api -d '{"method":"oauth.captured_urls"}'
109 
110# 5. Verify
111curl localhost:19229/api -d '{"method":"ui.screenshot"}'
112```
113 
114## Caveats
115 
116- **⚠️ Dismiss promotional overlays FIRST**: On fresh launches, full-screen promo overlays block the sidebar. **Dismiss immediately after `ui.open_sidebar`**, before any other interaction or screenshot. May need to run twice:
117```bash
118  curl localhost:19229/api -d '{"method": "ui.open_sidebar"}'
119  curl localhost:19229/api -d '{"method": "web.evaluate", "params": {"expression": "document.querySelectorAll(\".sr-only\").forEach(el => el.parentElement?.click())"}}'
120```
121- **Screenshots — don't open the file**: `ui.screenshot` and `ui.sidebar_screenshot` save PNGs to `/tmp/cline-debug/` and return the `{path}`. Use `read_file` on that path to examine screenshots. Running `open <path>` launches Preview.app on macOS which covers the VSCode window.
122- **Scripts count = 0 after launch**: CDP connects after extension host starts, so scripts parsed during startup aren't tracked. Breakpoints still work via sourcemap resolution.
123- **Port 9230**: Extension host inspector. If another VSCode instance uses this port, the harness will fail to connect. Kill other debug instances first.
124- **macOS only** for now (Playwright Electron launch behavior).
125- **Webview CDP**: `connect_webview` may fail depending on Electron version. `web.evaluate` still works via Playwright's `frame.evaluate()` fallback.
126- **Sourcemap paths**: esbuild outputs relative paths like `../src/extension.ts` in the sourcemap. The resolver handles this, but if a file isn't found, use `ext.source_files` to see exact paths.
127- **OAuth with fake codes**: Browser capture intercepts the URL but doesn't provide a valid auth code. For real OAuth testing, open the captured URL in a browser. For unit testing, mock the token exchange.
128 
129See `src/dev/debug-harness/README.md` for full API reference.
130