CodeWhale — AI Coding Agent for VS Code
CodeWhale is a full AI coding agent that lives in your VS Code sidebar. It reads your workspace, writes and patches files, runs shell commands, searches code, browses the web — all without leaving the editor. Powered by the DeepSeek V4 model family.
Quick Start — Zero to Chatting in 3 Minutes
1. Install the Engine (one time)
Open a terminal and install the codewhale CLI:
npm install -g codewhale
Verify the engine is installed:
codewhale --version
The codewhale CLI is the AI engine that powers this extension. The source repository is available if you'd like to build from source instead.
2. Install the Extension
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-dependencies
Then install the generated .vsix file from the VS Code extensions menu (Install from VSIX...).
3. Open CodeWhale
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.
4. Start a Conversation
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. No API keys to configure — the engine uses its built-in configuration.
What You Can Do
- Full agent capabilities — CodeWhale reads, writes, and patches files, runs shell commands, searches code, and browses the web.
- Three modes:
agent (autonomous, asks before acting), plan (proposes a plan first), yolo (fully autonomous, use with care).
- Switch models anytime —
/model to choose any model available to your engine.
- Reasoning depth control — from
off to max to balance speed and depth.
Conversation Management
- Threaded conversations — organize work into separate threads, each with its own history.
- Slash commands —
/help, /mode, /model, /task, /compact, /note, /memory, and more.
- Context compaction — when a conversation grows long,
/compact summarizes the history and frees up context space.
- Export & save — save and export conversations for sharing or archiving.
Task System
- Background tasks — offload long-running work:
/task add "refactor the auth module"
- Task sidebar — view and manage progress in the Tasks panel.
- Full lifecycle — create, view, and cancel tasks without leaving the editor.
Workspace Integration
- Context-aware — automatically understands your open workspace, project structure, and file contents.
- Live diff — see every file change proposed by the agent with inline diffs.
- Change tracking — created, modified, and deleted files are highlighted per turn.
Engine Management
- Auto-start — the engine starts when the extension activates.
- Restart on demand —
CodeWhale: Restart Engine from the command palette, or /restart in chat.
- Port persistence — the engine reuses its last port across sessions for faster startup.
Usage
Slash Commands
| Command |
What it does |
/help |
Show all available commands |
/mode [agent\|plan\|yolo] |
Switch between agent modes |
/model [name] |
Switch the AI model |
/reasoning [auto\|off\|low\|medium\|high\|max] |
Set reasoning depth |
/task add <prompt> |
Create a background task |
/task list |
List all background tasks |
/task show <id> |
View task details |
/task cancel <id> |
Cancel a task |
/compact |
Compact conversation context |
/clear |
Clear the current chat |
/save |
Save the current thread |
/export |
Export the conversation |
/note <text> |
Add a persistent note |
/memory |
View and manage persistent memory |
Commands (Command Palette)
| Command |
Description |
CodeWhale: Open Chat |
Open the chat panel |
CodeWhale: New Thread |
Start a fresh conversation |
CodeWhale: Compact Context |
Compact the current thread |
CodeWhale: Restart Engine |
Restart the engine |
Configuration
Open VS Code settings (Cmd+,) and search for codewhale.
| Setting |
Default |
Description |
codewhale.enginePath |
"codewhale" |
Path to the codewhale binary |
codewhale.enginePort |
7878 |
Port for the engine API |
codewhale.defaultModel |
"deepseek-v4-pro" |
Default model for new threads |
codewhale.defaultMode |
"agent" |
Default mode |
codewhale.reasoningEffort |
"auto" |
Reasoning depth level |
codewhale.autoStartEngine |
true |
Start engine on activation |
codewhale.autoApprove |
false |
Auto-approve tool calls in agent mode |
Troubleshooting
Engine fails to start
- Check if
codewhale is installed: npm list -g codewhale
- Try
CodeWhale: Restart Engine from the command palette.
- Open the CodeWhale output channel: View → Output → select "CodeWhale" from the dropdown.
Extension doesn't activate
- Reload the window:
Cmd+Shift+P → Developer: Reload Window.
- Make sure you have VS Code 1.85+.
Engine not found
- Set the full path in
codewhale.enginePath.
- Common locations:
/opt/homebrew/bin/codewhale, /usr/local/bin/codewhale.
VSIX install on Trae CN
"/Applications/Trae CN.app/Contents/Resources/app/bin/code" \
--install-extension /path/to/codewhale-vscode-0.1.0.vsix \
--force
Privacy
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.
Development
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
License
MIT
