ClawAgents for VS Code

Coding agent for VS Code and Cursor. Chat from the right Secondary Side Bar (same strip as Claude Code / Codex), edit your workspace with permission controls, and use OpenAI, Anthropic, Gemini, or local OpenAI-compatible models (including Ollama).

Requirements

• VS Code 1.85+ (or Cursor)
• Python 3.10+ on this host (managed mode discovers compatible PATH and standard installations, or set clawagents.pythonPath)
• clawagents ≥ 6.20.88 (GPT-6 Responses bridge)
• A provider credential for at least one model provider

Quick start

1. Install this extension from the Marketplace (or a .vsix).
2. Open a folder / Remote SSH window. On first start the extension auto-installs Python packages into its isolated managed environment (or clawagents.pythonPath when using the custom runtime):

clawagents[gemini,anthropic,bedrock,mcp,media,accurate-tokens,pty]>=6.20.88,<7  fastapi  uvicorn  pydantic  python-dotenv

You can also run ClawAgents: Install/Upgrade Python Dependencies from the Command Palette.

3. Add credentials: Command Palette → ClawAgents: Set API Key (OpenAI / Anthropic / Gemini / Bedrock / Tavily), or put keys in a workspace .env. For browser tools: Settings → Enable browser tools, then pip install 'clawagents[browser]' && playwright install chromium.

4. Open the right Secondary Side Bar and click ClawAgents, or run ClawAgents: Open Chat (⌘⇧' / Ctrl+Shift+').

5. Start in Plan / ask mode if you want confirmations. Turn on Auto-approve → Edit / Execute only when you trust the agent for that workspace.

Features

• Multi-turn chats with history, regenerate, live token usage, and independent concurrent conversation tabs
• Cache read/write accounting and an efficiency tooltip for fused follow-ups, artifact token estimates, diagnostic reduction, and compaction counts when reported by the Python core; completed-run usage survives chat reloads
• Per-conversation side chat overlays that keep running across thread switches and support minimize, maximize, and drag resizing
• Permission modes: ask · read-only · auto · full access
• Opt-in auto-approve for edits, shell, and web
• Clickable assistant file references and end-of-turn Edited N files summaries; click a file to open it
• Checkpoints before writes (diff / restore); workspace-mutating turns stay serialised across concurrent chats
• Skills folders, MCP servers (.clawagents/mcp.json), optional Context Mode
• Local sidecar process (loopback only) with a per-session bearer token

Settings

Sidebar Settings cover provider, model, base URL, skills, MCP, Graphify, browser tools, and telemetry (stored under .clawagents/ in the workspace). Use composer Goal for long-horizon autopilot (start_goal / verifier).

For multi-root workspaces, run ClawAgents: Select Workspace Root. Switching roots restarts the sidecar and opens a fresh chat so paths, .env, history, and trust approvals stay scoped to one folder.

Companions (lockstep with clawagents ≥6.20.32)

Command Palette → ClawAgents: Ensure Companions forces a re-probe/upgrade.

Security

• Sidecar binds to loopback only; every HTTP endpoint requires a session bearer token
• Provider credentials stay in VS Code SecretStorage or your workspace env file — not written to disk by the extension
• Workspace .env only forwards API key / model vars (no PYTHONPATH / base-URL redirection)
• File restore, snapshots, and chat IDs are confined under the workspace / .clawagents/
• Mutating tools are gated by mode + Auto-approve toggles (defaults: off)
• MCP is off by default; workspace mcp.json requires an explicit trust toggle; only allowlisted launchers (npx, uvx, …) and loopback URLs
• full_access mode requires Settings → Allow Full Access; stale permission IDs cannot create wildcard grants

Troubleshooting

• Python interpreter not found — managed mode discovers compatible Python on the extension host when the configured base is missing or incompatible. If none is available, run ClawAgents: Select Python Interpreter, or click Select Python in the error banner. Enter python3 or a full path to Python 3.10+. This validates Python, saves User/Remote settings, and retries startup when idle. In an SSH window, use a remote interpreter; a local Mac path such as /usr/local/bin/python3 may not exist there. Custom mode never substitutes another environment.
• Missing Python packages — click Install Python dependencies in the error banner. This installs into the actual sidecar runtime, including its isolated environment in managed mode.
• Sidecar health check timed out — open ClawAgents Sidecar output. Usually missing pip packages or a bad clawagents.pythonPath.
• provider_auth — invalid credential. Precedence: SecretStorage → workspace .env → shell. Path-like values (python.exe) are ignored/purged so a real key elsewhere can win.
• Gemini — set the Gemini/Google provider credential; pip install 'clawagents[gemini]'.
• MCP — enable MCP in Settings, optionally trust workspace config, and check ~/.clawagents/mcp.json.
• Restart — Command Palette → ClawAgents: Restart Sidecar.

Optional tools

• Companions above (optional; enable clawagents.ensureCompanions or run Ensure Companions)
• Browser tools: Playwright Chromium via clawagents browser extras

Source & development

• Source: github.com/x1jiang/clawagents-vscode
• Runtime: github.com/x1jiang/clawagents_py

npm run install:all
npm run build
# F5 → Run ClawAgents Extension
npm run package

Selecting your Python interpreter

In VS Code User settings (or Remote settings in an SSH window), set:

{
  "clawagents.pythonRuntime": "custom",
  "clawagents.pythonPath": "/absolute/path/to/venv/bin/python"
}

On Windows, use the full venv\\Scripts\\python.exe path in JSON. The interpreter must exist on the host running the extension. Workspace absolute paths are ignored for security; VS Code's separate Python extension selection does not configure ClawAgents.

Custom mode runs the sidecar with this exact interpreter and prepends its directory to PATH for local agent commands. A missing or incompatible custom interpreter is an error. Managed mode creates a separate extension-owned venv using the preferred base Python; if unavailable, it discovers Python 3.10+ on the current host, excluding workspace executables and relative PATH entries. Discovery does not modify your settings or other Python installations. The chosen base, version, and host appear in ClawAgents Sidecar output. Settings changes restart the sidecar when active tasks finish; ClawAgents: Restart Sidecar applies them immediately.

In Output → ClawAgents Sidecar, Starting sidecar: shows the interpreter and PATH pin: shows its command directory. To verify a local agent command, run python -c "import sys; print(sys.executable); print(sys.prefix)". Explicit absolute commands and separately configured containers/remote execution environments retain their own interpreter selection.

Meta / Muse-Glimmer-30B

Choose Meta (Glimmer) in ClawAgents Settings. The preset selects Muse-Glimmer-30B at http://129.106.31.72:7790/v1; approve the displayed endpoint with Trust and save. Meta also appears in the per-chat provider selector. Chat Completions is selected automatically, with no inherited OpenAI reasoning settings or API key. The default backend does not require a key.

Optional workspace .env or shell overrides (restart the sidecar after changes):

glimmer_30B_backend=http://129.106.31.72:7790/v1
glimmer_30B_model=Muse-Glimmer-30B
# META_API_KEY=your-dedicated-key  # only for authenticated deployments

Select Meta again to apply changed environment defaults to Settings. Custom remote URLs still require approval. This integration requires a Python core containing the meta provider profile; during monorepo development, select the interpreter where the sibling clawagents_py is installed in editable mode.

Optional local Gemma

Choose Gemma Agentic Q4 (coordinator) in Settings, then Set up / start locally. Installation happens only after you request local setup and confirm the download; remote Gemma endpoints remain supported. The helper selects available GPU acceleration or CPU, downloads the Q4 model when missing, starts its server and configures the endpoint. See local setup, hardware support and controls.

Model catalog refresh: verified models, provider constraints and source audit (Python 6.20.83 / extension 1.0.194).

Chat storage without an open folder

No-folder windows keep chat history and settings in no-folder-workspace under the extension's host-local global storage. This location survives VSIX upgrades. On the first start, retained .clawagents state from older ClawAgents installation folders is copied without overwriting current files; the original files remain intact. Open workspace folders continue to use their own .clawagents state.

GPT-6.1 Sol agent tools require the Responses API. Selecting that model corrects an inherited Chat Completions setting to Responses. OpenAI also supports tool-free Chat Completions for this model.