| 1 | # CodeWhale for VS Code |
| 2 | |
| 3 | Official Codewhale extension: an agentic chat sidebar over the local Engine |
| 4 | Runtime API, with editor context, streaming turns, approvals, and terminal |
| 5 | parity. |
| 6 | |
| 7 | ## What it does |
| 8 | |
| 9 | **Chat sidebar** (primary view): |
| 10 | |
| 11 | - create, switch, and resume Codewhale threads; every thread stays available |
| 12 | from the terminal and the embedded browser client |
| 13 | - stream turns live over the runtime's replayable SSE contract |
| 14 | (`GET /v1/threads/{id}/events?since_seq=…`) with automatic reconnection |
| 15 | - attach editor context as chips before sending: current selection, |
| 16 | active file, or Problems-panel diagnostics |
| 17 | - resolve tool approvals (allow / deny / remember) and clarification |
| 18 | questions inline, hydrated from the thread-detail snapshot so a reload |
| 19 | never strands pending work |
| 20 | - steer a running turn or stop it |
| 21 | - render agent replies as a safe Markdown subset; every code block gets |
| 22 | Copy and Insert-at-cursor actions |
| 23 | - open changed files from `file_change` items when the runtime includes a path |
| 24 | |
| 25 | **Runtime view** (secondary): connection state, recent thread summaries, |
| 26 | restore points, and the original terminal launch helpers. |
| 27 | |
| 28 | **Connection**: the extension attaches to `codewhale serve --http` on |
| 29 | `127.0.0.1:7878` by default, starts it in a visible terminal on request, and |
| 30 | never runs its own agent engine — the runtime is the single turn/event owner. |
| 31 | |
| 32 | ## Security posture |
| 33 | |
| 34 | - Runtime bearer tokens are stored in VS Code SecretStorage via |
| 35 | **CodeWhale: Set Runtime Token**; the legacy `codewhale.runtimeToken` |
| 36 | setting still works and is migrated into secret storage on first use. |
| 37 | - The webview renders with a strict CSP (`default-src 'none'`), and all |
| 38 | model output is HTML-escaped before any Markdown transform runs; links |
| 39 | must be http(s). |
| 40 | - The chat webview script is a static string — no runtime data is |
| 41 | interpolated into it. |
| 42 | |
| 43 | ## Local use |
| 44 | |
| 45 | ```bash |
| 46 | npm install |
| 47 | npm test # compile + unit tests |
| 48 | npm run package # -> codewhale-vscode-<version>.vsix |
| 49 | code --install-extension codewhale-vscode-<version>.vsix |
| 50 | ``` |
| 51 | |
| 52 | Settings: `codewhale.commandPath`, `codewhale.runtimeHost`, |
| 53 | `codewhale.runtimePort`, `codewhale.agentViewRefreshIntervalSeconds` |
| 54 | (`0` disables automatic refresh). Commands: **CodeWhale: Ask Codewhale** |
| 55 | (`ctrl+alt+c` from the editor, also on the editor context menu), |
| 56 | **CodeWhale: New Chat**, **CodeWhale: Set Runtime Token**, |
| 57 | **CodeWhale: Start Local Runtime**. |
| 58 | |
| 59 | Keep the runtime on `127.0.0.1` unless you deliberately front it with trusted |
| 60 | local networking controls. |
| 61 | |
| 62 | ## Not yet built |
| 63 | |
| 64 | VS Code-native diff/merge review of agent file changes (blocked on the |
| 65 | runtime publishing a Files/Changes contract), provider/model switching from |
| 66 | the composer, retry/undo/restore buttons, and account sign-in surface. The |
| 67 | runtime's embedded browser client (`codewhale web`) remains the full-feature |
| 68 | fallback for those flows. |
| 69 |