CodeWhale VSCode ζ― CodeWhale η VSCode εΎε½’εζ©ε±οΌδΈΊη»η«― AI ηΌη¨ε©ζζδΎεηδΎ§θΎΉζ ηι’γ
CodeWhale VSCode is the graphical frontend for CodeWhale, bringing the terminal-based AI coding agent into VS Code as a native sidebar chat. Powered by the DeepSeek V4 model family, it functions as a full coding agent β reading your workspace, writing files, running commands, searching the web, and managing multi-step tasks β all from within the editor.
This extension depends on the CodeWhale TUI engine. The upstream project provides the core AI agent capabilities:
- π¦ Upstream repo: github.com/Hmbown/CodeWhale
- π₯οΈ Engine binary:
codewhaleCLI (see Prerequisites below)
TODO: Add screenshots or GIFs showing the extension in action.
Recommended: Chat interface, slash commands, task management, settings UI.
Before using this extension, you must have the CodeWhale engine installed and running:
| Requirement | How to Install |
|---|---|
| CodeWhale CLI | npm install -g codewhale |
| VS Code | 1.85+ (download) |
| Node.js | 18+ (required by the engine) |
The extension will attempt to locate the codewhale binary automatically from standard installation paths. On macOS, it may be under /opt/homebrew/lib/node_modules/codewhale/bin/downloads/codewhale.
β οΈ Important: This is a VSCode extension β it is the GUI layer for CodeWhale. The core AI engine (codewhaleCLI) must be installed separately from the upstream project: CodeWhale.
- Full coding agent β CodeWhale reads, writes, and patches files, runs shell commands, searches code, and browses the web to complete your goal.
- Three modes:
agent(autonomous with approval),plan(propose before acting),yolo(fully autonomous). - Model of your choice β switch between models at any time (
/model). - Reasoning effort control β from
offtomaxto balance speed and depth.
- Threaded conversations β organize work into separate threads with automatic history.
- Slash commands β
/help,/mode,/model,/reasoning,/task,/compact,/note,/memory,/export, and more. - Context compaction β when conversations grow long, use
/compactto summarize and free up context window space. - Export & save β export conversations for sharing or archiving.
- Context-aware β CodeWhale automatically understands your open workspace, project structure, and file contents.
- Live diff β see file changes proposed by the agent with inline diff views.
- File change tracking β created, modified, and deleted files are highlighted per turn.
- Background tasks β offload long-running work with
/task add <prompt>. - Task sidebar β view and manage task progress in the Tasks panel.
- Task lifecycle β create, view, cancel tasks without leaving the editor.
- Auto-start β the CodeWhale engine starts automatically when the extension activates.
- Restart on demand β use the
CodeWhale: Restart Enginecommand or/restartif something goes wrong. - Port persistence β the engine reuses its last known port across sessions for faster startup.
- Activity bar integration β dedicated CodeWhale icon in the activity bar.
- Sidebar panels β Chat, Threads, Work, and Tasks panels.
- Status bar β model, mode, and workspace indicators.
- Settings UI β configure model, mode, reasoning effort, engine path, auto-approve, and more via VS Code settings.
- Dark & light themes β follows your VS Code theme automatically.
Open a terminal and install the codewhale CLI:
npm install -g codewhaleVerify the engine is installed:
codewhale --versionThe
codewhaleCLI is the AI engine that powers this extension. The source repository is available if you'd like to build from source instead.
Option A β VS Code Marketplace (recommended):
Search for "CodeWhale" in the VS Code extensions panel (Cmd+Shift+X) and click Install.
Option B β Build from source:
git clone https://github.com/HengQuWorld/CodeWhale-VSCode.git
cd CodeWhale-VSCode
npm install
npm run compile
npx @vscode/vsce package --no-dependenciesThen install the generated .vsix file from the VS Code extensions menu (Install from VSIX...).
Click the CodeWhale icon in the activity bar (the layered whale icon on the left edge of VS Code). The engine starts automatically β you'll see a "Ready" indicator in the status bar.
Type something in the chat panel. Try your first command:
What files are in my project?
That's it. The agent reads your workspace and responds.
| Command | Description |
|---|---|
CodeWhale: Open Chat |
Open the CodeWhale chat panel |
CodeWhale: New Thread |
Start a fresh conversation |
CodeWhale: Compact Context |
Compact the current conversation context |
CodeWhale: Restart Engine |
Restart the CodeWhale engine |
| Command | Action |
|---|---|
/mode [agent|plan|yolo] |
Switch mode |
/model [name] |
Switch model |
/reasoning [auto|off|low|medium|high|max] |
Set reasoning effort |
/task add <prompt> |
Create a background task |
/task list |
List tasks |
/task show <id> |
View task details |
/task cancel <id> |
Cancel a task |
/compact |
Compact conversation context |
/clear |
Clear chat |
/save |
Save conversation |
/export |
Export conversation |
/note <text> |
Add a note |
/memory |
Manage persistent memory |
/help |
Show all commands |
CodeWhale is configurable via VS Code settings (Cmd+, β search "brotherwhale").
| Setting | Default | Description |
|---|---|---|
brotherwhale.enginePath |
"codewhale" |
Path to the codewhale binary |
brotherwhale.enginePort |
7878 |
Port for the CodeWhale runtime API |
brotherwhale.defaultModel |
"deepseek-v4-pro" |
Default model for new threads |
brotherwhale.defaultMode |
"agent" |
Default mode (agent / plan / yolo) |
brotherwhale.reasoningEffort |
"auto" |
Reasoning effort level |
brotherwhale.autoStartEngine |
true |
Auto-start engine on activation |
brotherwhale.autoApprove |
false |
Auto-approve tool calls in agent mode |
- Ensure
codewhaleis installed:npm list -g codewhale - Try
CodeWhale: Restart Enginefrom the command palette. - Check the CodeWhale output channel (View β Output β CodeWhale) for error details.
- Reload the VS Code window (
Cmd+Shift+PβDeveloper: Reload Window). - Ensure VS Code 1.85+ is installed.
- Set the full path to the engine binary in
brotherwhale.enginePath. - Common paths:
/opt/homebrew/bin/codewhale,/usr/local/bin/codewhale.
code --install-extension /path/to/brotherwhale-vscode-0.1.0.vsix --forceTrae CN users: if
codeis not available, use the full path:"/Applications/Trae CN.app/Contents/Resources/app/bin/code" --install-extension /path/to/brotherwhale-vscode-0.1.0.vsix --force
CodeWhale connects to your locally running engine. No conversation data is sent anywhere beyond the AI model provider configured in your CodeWhale setup. You control the provider, the model, and the data flow.
git clone https://github.com/HengQuWorld/CodeWhale-VSCode.git
cd CodeWhale-VSCode
npm install
npm run compile # development build with source maps
npm test # run tests
npm run package # production build (minified)
npx @vscode/vsce package --no-dependencies # build VSIX- CodeWhale β The terminal-based AI agent that powers this extension.