Claw VS Code Extension

A modular VS Code extension that connects to a bundled or custom Python claw runtime, provides chat + model/skills/context management UIs, supports transcripts, fallback providers, and built-in diff rendering.

Features

• Spawns Python claw-code as a child process.
• Webview panels:
  • Model Selector (OpenRouter / LM Studio / Ollama)
  • Skill Manager (install/toggle/delete)
  • Context Rules
  • Chat panel
• Global config persisted at ~/.claw-vscode/config.json.
• Workspace override via .clawrc with priority over global config.
• Multi-model fallback order handling.
• Session transcript save/load at ~/.claw-vscode/sessions/<timestamp>.json.
• Diff output support via vscode.diff.
• Built-in run-code-mcp skill registered automatically.
• Per-prompt context toggles in chat (git diff, workspace summary, open editors only).
• Optional Plan Then Apply mode for deliberate execution.
• Runtime progress streaming while tools are executing.
• Crash-safe pending request resume.
• Multi-turn in-process runtime memory with automatic context compaction.
• Runtime permission-mode enforcement with pre/post tool hooks.
• Optional post-apply test command hook.
• Enterprise governance controls: workspace trust requirement, optional write approval, read-only request mode, and append-only audit log.
• Automatic structured-write fallback when a model refuses or skips native tool calls.

Commands

• Claw: Start Session (claw.start)
• Claw: Restart Session (claw.restart)
• Claw: Open Settings (claw.openSettings)
• Claw: Install Skill (claw.installSkill)
• Claw: Open Chat (claw.openChat)
• Claw: New Task (claw.newTask)
• Claw: Generate Project (claw.generateProject)
• Claw: Explain Selection (claw.explainSelection)
• Claw: Edit Current File (claw.editFile)
• Claw: Resume Last Request (claw.resumeLastRequest)
• Claw: Open Model Selector (claw.openModelSelector)
• Claw: Open Skill Manager (claw.openSkillManager)
• Claw: Open Context Rules (claw.openContextRules)
• Claw: Save Session Transcript (claw.saveTranscript)
• Claw: Load Session Transcript (claw.loadTranscript)
• Claw: Show Logs (claw.showLogs)
• Claw: Open Audit Log (claw.openAuditLog)
• Claw: Open Runtime Tuning (claw.openRuntimeTuning)
• Claw: Reindex Skills (claw.reindexSkills)

Provider/model changes are applied immediately: saving in Model Selector now triggers a session restart automatically.

Required Runtime

• Node.js 20+
• Python 3 available as python (Windows) or python3 (Unix)
• No manual runtime required for default setup. Claw auto-installs a bundled runtime to ~/.claw-vscode/runtime/claw.py.
• git in PATH for skill installation

Development Setup

1. Install dependencies:

npm install

2. Compile:

npm run compile

3. Press F5 in VS Code to launch the extension host.

Config Model

Global config path:

• ~/.claw-vscode/config.json

Default shape:

{
  "runtime": {
    "clawPyPath": "",
    "pythonCommand": "python",
    "onboardingComplete": false,
    "requestTimeoutMs": 120000,
    "maxSessionMessages": 80,
    "autoCompactInputTokens": 18000,
    "compactPreserveRecent": 8,
    "permissionMode": "workspace-write",
    "preToolHooks": [],
    "postToolHooks": [],
    "postToolFailureHooks": [],
    "promptStallTimeoutMs": 45000,
    "autoRecoverPromptDelivery": true,
    "maxPromptReplayAttempts": 1,
    "allowOverwriteExistingFiles": false,
    "runTestsAfterApply": false,
    "testCommand": "npm test"
  },
  "modelProvider": "openrouter",
  "openrouter": {
    "apiKey": "",
    "model": "nvidia/nemotron-3-super-120b-a12b:free"
  },
  "lmstudio": {
    "baseUrl": "http://localhost:1234/v1"
  },
  "ollama": {
    "baseUrl": "http://localhost:11434/v1"
  },
  "skills": {},
  "contextRules": {
    "maxTokensPerFile": 2000,
    "include": ["src"],
    "exclude": ["node_modules"],
    "openEditorsOnly": false,
    "includeGitDiff": true,
    "includeWorkspaceSummary": true
  },
  "fallbackModels": ["openrouter", "lmstudio", "ollama"]
}

Workspace override (.clawrc) example:

{
  "skills": ["web", "browser"],
  "model": "openrouter/nemotron",
  "context": {
    "include": ["src", "lib"],
    "exclude": ["node_modules", "dist"]
  }
}

Notes

• Chat messages are sent to claw.py over stdin as JSON lines.
• stdout lines are parsed as JSON first, then treated as plain assistant text if parsing fails.
• If claw emits a diff message ({ type: "diff", original, modified, ... }), the extension opens VS Code's native diff view.
• If runTestsAfterApply is enabled, Claw runs runtime.testCommand after successful file-changing responses.
• Audit events are stored in ~/.claw-vscode/audit.ndjson when runtime.auditLoggingEnabled is true.

Troubleshooting File Writes

• If chat replies claim it cannot edit files, Claw now attempts a structured fallback write plan automatically.
• For local backends, set a real model name in Model Selector for LM Studio/Ollama (not lmstudio/default or ollama/default).
• Restart session after changing provider/model.
• Ensure Read-only analysis is unchecked when you want edits.

Workspace Visibility

• Claw can now inspect existing workspace content using runtime tools:
  • list_directory
  • read_file
• This means the model can discover and read files like index.html directly during a request.
• Chat UI currently supports pasted images, not manual arbitrary file attachments.

Local Context Limits (LM Studio / Ollama)

• If a local model returns HTTP 400 context-length errors (for example n_keep >= n_ctx), Claw now auto-retries once with minimal skill context.
• Skill context injection is compacted automatically to reduce prompt size on smaller context windows.

Session Stability

• Manual stop/restart/cancel no longer trigger unintended fallback provider churn.
• Provider fallback is now reserved for real runtime failures, not intentional session transitions.
• Runtime now emits structured lane events with failure classes (for example: tool_runtime, prompt_delivery, mcp_startup, infra).
• Lane events are written to the audit log and reflected in sidebar/status messaging during failures.
• Prompt delivery watchdog detects stalled requests and can auto-restart + replay once (configurable).
• Sidebar now includes a recent lane diagnostics panel fed from audit lane-event history.

Prompt Delivery Recovery

• Configure watchdog and replay behavior with:
  • runtime.promptStallTimeoutMs
  • runtime.autoRecoverPromptDelivery
  • runtime.maxPromptReplayAttempts
• On stall, Claw emits lane events (lane.prompt_misdelivery) before retrying.

Runtime Memory + Compaction

• The bundled runtime now keeps multi-turn session memory inside each running Claw process.
• When session context grows past runtime.autoCompactInputTokens, older turns are summarized into a system compaction note while keeping the most recent turns verbatim.
• Use these runtime settings to tune behavior:
  • runtime.maxSessionMessages
  • runtime.autoCompactInputTokens
  • runtime.compactPreserveRecent

Runtime Permission Modes + Hooks

• Runtime-level permission mode now gates tool execution:
  • read-only: blocks file and MCP tool calls.
  • workspace-write: allows workspace file tools, blocks MCP tool calls.
  • danger-full-access: allows all runtime tools.
• Configure mode with runtime.permissionMode.
• Runtime tool definitions now carry explicit required_permission metadata and enforcement is applied from that registry (instead of implicit name checks).
• Optional hook command arrays are executed for each tool phase:
  • runtime.preToolHooks
  • runtime.postToolHooks
  • runtime.postToolFailureHooks
• Hook commands receive JSON payload on stdin and can deny a call or return adjusted arguments.

Skill Onboarding Lifecycle

• Installing a skill now performs clone + onboarding validation (not just a quick config write).
• Retroactive onboarding runs at extension activation and can be re-run with Claw: Reindex Skills.
• Valid skills are marked onboarded with type:
  • mcp: has skill.json with a valid entry file.
  • prompt: has instruction content in SKILL.md, README.md, or INSTRUCTIONS.md.
• Invalid skills are auto-disabled and show an onboarding error in Skill Manager.
• Enabled onboarded prompt skills are injected into runtime as additional system context.

MCP Skill Execution

• Onboarded enabled mcp skills are now registered as callable runtime tools (mcp_<skill_name>).
• At tool-call time, Claw executes the skill entry process and passes tool arguments as JSON on stdin.
• Supported entry types:
  • Node (.js, .cjs, .mjs) via node <entry>
  • Python (.py) via python/python3
  • Executable file paths
• Skill process output handling:
  • JSON stdout -> parsed tool result
  • Non-JSON stdout -> returned as text result
  • Non-zero exit -> tool error with stderr captured

Frontend Quality Guardrails

• For frontend requests (landing pages, websites, UI/UX tasks), Claw injects stronger design-quality instructions to avoid boilerplate outputs.
• The runtime now favors complete, cohesive file sets with intentional visual direction and responsive layout quality.