CrabCode for Visual Studio Code

Use CrabCode in Visual Studio Code. The extension connects to a CrabCode Gateway, providing streaming chat, code-aware actions, session management, permission prompts, file-change review, and checkpoint recovery without leaving the editor.

Display language

CrabCode supports Simplified Chinese, Traditional Chinese, English, Japanese, Korean, German, French, Spanish, Brazilian Portuguese, and Russian. It follows VS Code's display language by default. Choose CrabCode Settings → General → Display language or set crabcode.language to override the product UI. Changes preserve the current session and unsent composer text/attachments. Native commands and extension settings follow VS Code's own display language. Translation catalogs are included in the extension.

Requirements

• Visual Studio Code 1.85.0 or later.
• Python 3.10 or later when the extension starts a local Gateway.
• A running CrabCode Gateway for a remote connection.
• A model provider configured on the Gateway, with its required credentials.

Quick start

1. Install this extension from the Visual Studio Marketplace.

2. For a local Gateway, install CrabCode with Gateway support:

   python -m pip install "crabcode[gateway]==0.1.9"
   crabcode gateway
   

   The default Gateway WebSocket address is ws://localhost:4096/ws. The extension can also detect, install, and start a local Gateway when crabcode.gatewayAutoInstall is enabled. Automatic installation intentionally stays on the lightweight gateway extra. From CrabCode settings, select 选择并安装其他套件, or run CrabCode：选择并安装本地套件, to add optional capabilities through a multi-select checklist. Gateway is always included; Search and Debugger can be checked independently.

3. Configure the model provider, model, and credentials on the Gateway machine using ~/.crabcode/settings.json. See the model configuration examples. Provider API keys belong to the Gateway configuration, not the extension's crabcode.password setting. Restart the Gateway after changing its environment.

4. Open a project folder in VS Code, select CrabCode in the Activity Bar, and send a message. Use CrabCode：连接网关 if a connection is not established.

For a Gateway on another machine, start it there and configure crabcode.serverUrl with its ws:// or wss:// address. Use wss:// when the Gateway is accessed beyond the local machine. Remote Gateways must already be installed and running; the extension does not install them remotely.

For local Python discovery, crabcode.pythonPath takes precedence, followed by the active Python extension interpreter, the workspace .venv, Conda, and PATH. Packaged Gateways must meet both the wire protocol requirements and the extension's minimum release version. The extension prompts to upgrade older local packages and retains newer compatible releases. Stop a Gateway started manually or by another window before reconnecting; remote Gateways must be upgraded on their host. When this repository is open, the Gateway runs from workspace sources and checks CLI/server imports before starting. Source code still needs its Python dependencies installed: use the workspace interpreter to run python -m pip install -e ".[gateway]" from the repository root. Dependency failures and the selected interpreter appear in the CrabCode output channel.

Features

• Follow-up behavior: choose Queue (default) or Steer with crabcode.followUpMode. Queued cards above the composer offer Steer and Delete. Their menu offers Edit message (recall with images) and Disable queue (use Steer for future messages; existing queued messages remain). Enter uses the default; Cmd+Enter on macOS or Ctrl+Enter elsewhere sends the opposite for one message. Shift+Enter inserts a newline. Queue runs messages in order after the current turn; Steer supplies guidance at the next safe boundary. Unsent input remains recoverable after a stop.
• Streaming chat with Markdown, code blocks, diffs, tool results, attachments, permissions, choices, and plans. Markdown headings, nested lists, quotes, links, task lists, strikethrough and tables use the same CommonMark/GFM and CJK parsing rules as Desktop, including restored history and streaming replies. Code/table copy and image preview controls preserve the original content.
• Explain, fix, refactor, test, or send the selected editor code to chat.
• Create, resume, interrupt, and fork conversation sessions. Session and history lists default to the current workspace folders. Use their scope selector to switch to All projects (the latest 200 sessions on the connected Gateway); the selection is remembered per workspace. Without an open folder, select All projects to browse sessions.
• Restoring a conversation restores its saved model profile. The editor's default model applies to new sessions; refreshing settings or reconnecting does not replace an existing session's model.
• Choose reasoning effort from the composer capsule (none through max). Enable Ultra mode from +, and click its gradient capsule to turn it off. These settings are saved per session in the workspace and restored on reconnect. Ultra uses the Desktop spectrum animation and respects reduced motion.
• Review and keep or undo pending file edits.
• Start, reconnect to, or restart a local Gateway from the editor.
• See the active editor as a removable context capsule above the composer. Use + → IDE context to toggle it or reference workspace files and folders with the native VS Code picker; current and added references are also available from @ in the composer and are injected into that message by path.

Configuration

Use the chat toolbar's settings menu:

• CrabCode设置 opens a dedicated editor with General, Models, Permissions & Tools, Context Compaction, Prompts, and Usage sections. Search jumps to an individual setting. Chat preferences support VS Code user/workspace scopes; Gateway settings use the selected user/project/local configuration layer.
• 扩展设置 opens native VS Code settings filtered to connection, installation, editor integration, and debugging options. Existing product preference keys remain registered for settings JSON compatibility and Settings Sync.

The old context-compaction and prompt commands now open the corresponding section of CrabCode设置. Local chat preferences remain editable offline; Gateway-backed sections require a reachable Gateway with the corresponding API. The page uses the first workspace folder, matching the chat session's default project. Numeric controls save on change, while model and prompt editors have explicit save/cancel actions and preserve drafts when navigating between sections.

You can also configure existing keys in settings JSON:

{
  "crabcode.serverUrl": "ws://localhost:4096/ws",
  "crabcode.autoConnect": true,
  "crabcode.gatewayAutoInstall": true,
  "crabcode.pythonPath": "",
  "crabcode.showDiffOnFileChange": false,
  "crabcode.computerUseEnabled": true,
  "crabcode.computerUseTargetScope": "app_window",
  "crabcode.computerUseDeliveryPolicy": "allow_foreground"
}

crabcode.computerUseEnabled defaults to true, enabling the standalone native component through the CrabCode Computer Use companion without Crab Desktop. The main extension includes the companion in its extension pack. For offline installation, install both VSIXs. Set the setting to false to disable Computer Use. Source companions without a native bundle can reuse an installed shared component from CLI, Desktop or another CrabCode extension. The Computer Use status-bar menu provides monitoring, permission settings and refresh. On macOS, grant Crab Computer Use Accessibility and Screen Recording access. Remote SSH/WSL/container windows require CrabCode Computer Use installed on the local UI side; operations target the local desktop. Use the VSIX matching your local OS and architecture.

Explicit VS Code values override the Gateway's computer_use.target_scope and computer_use.delivery_policy when creating, resuming or sending to a session. Merely inheriting an extension default does not override Gateway settings. Targets are app_window and desktop; policies are strict_background and allow_foreground. Desktop scope requires foreground permission.

The Computer Use delivery policy is independent of tool approval modes, including Full Access (run_everything / bypassPermissions). Strict background uses process/window-targeted input and never exposes focus_window. Some applications can ignore input while inactive; select allow_foreground in settings to permit activation-assisted fallback. The model cannot set this permission inside a ComputerUse action. Legacy crabcode.computerUseMode remains a target alias only and grants no foreground permission. The new target setting takes precedence over that alias.

Installing a suite provides its Python package and dependencies. Search and Debugger remain disabled until their import paths are added to the Gateway's extra_tools configuration. Remote Gateway suites must be installed on the remote host.

Gateway authentication

The Gateway binds to 127.0.0.1:4096 and disables authentication by default, unless you have configured another security mode. To enable password authentication for a manually started Gateway, for example in a POSIX shell:

export CRABCODE_GATEWAY_PASSWORD="replace-with-a-strong-password"
crabcode gateway --security-mode password

Set the same value in VS Code User Settings:

{
  "crabcode.serverUrl": "ws://localhost:4096/ws",
  "crabcode.password": "replace-with-a-strong-password"
}

The extension sends this value as a Bearer credential using the Gateway's compatible password authentication. This setting is stored in VS Code's settings JSON; do not add a real password to shared workspace settings or source control. The extension does not perform the Gateway's public-key challenge and signature flow; use password mode, or the password method in mixed mode. For a remote Gateway, configure HTTPS/WSS and use its wss://.../ws address.

crabcode.chatModels lists the Gateway model profiles shown in the chat UI; crabcode.chatModelDefault selects the initial one. crabcode.permissionMode controls how the current Gateway session handles tool permissions.

By default, Enter sends a message and Ctrl+Enter (Windows/Linux) or Cmd+Enter (macOS) inserts a newline. Set crabcode.composerSendKey to mod_enter to reverse these actions.

Commands

Open the Command Palette and run one of the following:

• CrabCode：打开聊天
• CrabCode：解释选中代码
• CrabCode：修复选中代码
• CrabCode：重构选中代码
• CrabCode：为选中代码添加测试
• CrabCode：发送到聊天
• CrabCode：连接网关 / CrabCode：断开网关
• CrabCode：新建会话 / CrabCode：中断当前任务
• CrabCode：重启网关 / CrabCode：打开扩展设置
• CrabCode：打开CrabCode设置 (the unified product settings editor)
• CrabCode：打开提示词设置 / CrabCode：打开上下文压缩设置 (section shortcuts)

Troubleshooting

• Cannot connect: check crabcode.serverUrl, the Gateway process, and the password. The local health endpoint is http://localhost:4096/health.
• Python not found: set crabcode.pythonPath to the Python 3.10+ executable in the environment where you installed CrabCode.
• Incompatible Gateway: follow the local upgrade prompt, or upgrade the Gateway on its host if using a remote connection.
• Connected but model requests fail: check the Gateway's model configuration and provider credentials.

Open View → Output → CrabCode for connection and startup diagnostics. crabcode.debugLogRawWsPayload is off by default; enabling it can log message content, so review logs before sharing them.

Building from source

From packages/vscode, use Node.js 24 (the tested version is in .nvmrc): Native component builds also require Rust/Cargo and the platform's native build tools (Xcode Command Line Tools on macOS).

nvm use
npm ci
npm ci --prefix computer-use
npm run lint
npm test
npm run package

The package command builds the universal main extension and creates crabcode-0.1.9.vsix. It does not embed native components. The companion must also be installed. For extension-host development, npm run watch (also used by the F5 launch task) builds a debug native component and the companion before starting the JavaScript watcher. The F5 launch configuration loads both extensions. Install it with Extensions → … → Install from VSIX…, or run code --install-extension crabcode-0.1.9.vsix. Node.js and npm are only required for building the extension, not for installing the VSIX in VS Code.

For platform and all-platform VSIXs, run Actions → Client Packages → Run workflow and download the vsix-* artifact. The same manual workflow builds Desktop DMGs and MSI. See client packaging for artifacts, signing and offline installation. Python Release publishing is independent.

Support and source

Report issues or contribute at ylzz1997/crabcode. The full Gateway configuration and security documentation is in the repository's README.

License

MIT