Claude Inmate

Claude-powered coding assistant for VS Code

• Persistent vault-based project memory
• Multi-step iterative prompt workflows via Claude CLI
• Transparent per-turn cost tracking
• Autonomous diff writeback

⚠️ PREVIEW — New & Experimental

This extension is a very new idea and is currently in preview. The concepts — iterative prompt webview, vault-based memory, cost transparency, auto-apply diffs — are being actively developed and refined.

You may encounter rough edges, breaking changes, or features that shift as we learn what works. Feedback and contributions are very welcome.

📋 Prerequisite — Claude Code CLI

This extension requires the Claude Code CLI to be installed and authenticated. Run claude --version in your terminal to verify. The extension pipes prompts through claude --bare --print — no API keys are configured inside VS Code.

Table of Contents

1. Overview
2. Transparency & Iterative Workflow
3. Cost Tracking Per Iteration
4. Getting Started: Start a Workflow & Add Files
5. Vault-Based Persistent Memory
6. Sidebar Explorer
7. Writeback Engine (Auto-Apply Diffs)
8. Commands Reference
9. Configuration Reference
10. Architecture Overview
11. Build & Install

1. Overview

Claude Inmate integrates the Claude CLI directly into VS Code as a structured coding assistant. Unlike a simple chat wrapper, it provides:

• Iterative Prompt Webview — A dedicated panel for constructing structured prompts with memory files, file attachments, and a full refinement loop. Each iteration shows token usage and cost in a transparent table.
• Vault-Based Persistent Memory — An embedded collection of Markdown notes (tags, frontmatter) that forms an evolving knowledge base for your project. Claude always has context.
• Tag-Based Context Selection — Select which tags to include; vault notes matching those tags are automatically injected into prompts.
• Transparent Cost Display — Every iteration displays input/output/cache tokens and the calculated cost, so you always know what each turn costs.
• Diff-Based Writeback — Claude can propose file changes as unified diffs. The extension parses, validates, and applies them automatically.
• Sidebar Explorer — Tree view of vault files, tags, TODOs, and saved prompts. Right-click to add anything to your prompt.
• Explorer & Editor Integration — Right-click any file or selected code from the Explorer or editor and send it directly into your active prompt.

2. Transparency & Iterative Workflow

The core philosophy of this extension is full transparency — you should always know what context is being sent, what the model costs, and what changes it proposes.

How It Works

1. Create a Prompt — Run Claude: Iterative Prompt from the command palette. A webview opens with sections for System Prompt, Tags, Memory Files, TODOs, Attached Files, and User Prompt.
2. Add Context — Select tags, add vault notes, attach workspace files, or paste code selections. Every piece of context is visible in the prompt.
3. Send to Claude — Click Send. The prompt is piped through the Claude CLI (claude --bare --print). The webview shows a Raw Request tab so you can inspect exactly what was sent.

🔍 Fully visible terminal execution — Every call to Claude runs through a real VS Code terminal. There's no hidden API call, no background HTTP request. You can see the raw prompt being piped, watch Claude's response stream in, and inspect the exact command being executed. What you see is what the AI sees.

4. Review the Response — The response appears in the Response tab. A Raw Response tab shows the exact output from Claude.
5. See the Cost — After each iteration, a cost table is appended to the response showing tokens and pricing (see §3).
6. Apply Changes — If Claude suggests unified diffs, the Apply button activates. You can review, validate, and apply each patch.
7. Iterate & Approve File Requests — Edit the User Prompt section and re-submit. Claude can also proactively request changes to the prompt. If Claude determines that more context is needed, it responds with an adjustment-request YAML block containing an updated objective, additional files it needs from your workspace, and clarifications. These appear as checkboxes under Actionable Items — you tick which changes to accept, then click Apply. The prompt updates automatically, and you review before re-sending. Nothing is applied without your explicit approval.
8. Save — Save any prompt to the vault under saved-prompts/ for later reuse.

What Makes It Transparent

• Every section of the prompt is visible and editable — nothing is hidden.
• Raw Request & Raw Response tabs show the exact bytes sent and received.
• The cost table is appended to each response — you see cumulative spend across all iterations in the current session.

• Diff patches are parsed and shown inline — you can review each hunk before applying.
• Patch validation — the writeback engine verifies that diffs apply cleanly and can show a side-by-side comparison of original vs. fixed diffs.

3. Cost Tracking Per Iteration

Every response includes a cost history table showing the token usage and dollar cost for each iteration in the current session.

Example Table

Pricing by Model

What's Tracked

• In — Input tokens (prompt) + cache creation tokens
• Out — Output tokens (response)
• Cache — Cache read tokens
• Size — Raw byte size of request → response
• Rate — The pricing tier used
• Cost — Calculated as: (input_tokens × input_price + cache_write_tokens × cache_write_price + cache_read_tokens × cache_read_price + output_tokens × output_price) / 1,000,000

Token usage is parsed from Claude CLI's project log files (~/.claude/projects/) after each call. The extension retries with short delays to handle the log-flush race condition.

Why Track Costs?

• Budget visibility — See exactly how much each iteration costs down to fractions of a cent.
• Model comparison — Try Sonnet vs Opus vs Haiku and compare cost vs. quality.
• Context optimization — The cost table helps gauge whether you're sending too much context (more tokens = higher cost). Adjust claude.maxContextNotes and claude.maxNoteLength to control it.

4. Getting Started: Start a Workflow & Add Files

Starting a Workflow

Method 1 — Command Palette (F1):

1. Press F1 and run Claude: Iterative Prompt.
2. The prompt webview opens with default tags (usually @interactions and @base).
3. Write your instruction in the User Prompt textarea.
4. Click Send to submit to Claude.

Method 2 — Iterative Prompt with Open Tabs:

1. Open the files you want to reference in editor tabs.
2. Run Claude: Iterative Prompt with Open Tabs from the command palette.
3. The open tab files are pre-attached as context.

Method 3 — From a Saved Prompt:

1. In the sidebar, expand Saved Prompts.
2. Click any saved prompt to reopen it in the webview.
3. Click Send to continue where you left off.

Adding Files to a Prompt

From the File Explorer:

• Single file: Right-click a file → Add to Claude Prompt. The file is added to Attached Files in the active prompt (auto-creates a prompt if none is open).
• Folder: Right-click a folder → Add to Claude Prompt. All .md files in that folder are added to Memory Files, with TODOs parsed into the TODO section.
• Multi-select: Select multiple files/folders, right-click → Add to Claude Prompt. All selected items are attached.

From the Editor:

1. Select code in the editor.
2. Right-click → Add to Claude Prompt.
3. If no prompt is open, one is created automatically with the selected code as the User Prompt.

From the Sidebar (Claude Explorer):

• Vault file: Right-click a vault file → Add to Claude Prompt. Added to Memory Files; TODOs are parsed from the file and added to the TODO section; suggestedFiles from YAML frontmatter are extracted and added to Attached Files.
• Vault folder: Right-click a vault folder → Add to Claude Prompt. All .md files and their TODOs are added.
• Tag: Right-click a tag → Add to Claude Prompt. All vault notes with that tag are added to Memory Files.
• TODO item: Right-click a TODO → Add to Claude Prompt. The TODO text goes to the TODO section; the parent file goes to Memory Files.
• Saved prompt: Right-click a saved prompt → Add to Claude Prompt. Its content is loaded into the webview.

Using the [...] menu:

Click the ellipsis icon on any sidebar item to see available actions, then select Add to Prompt.

5. Vault-Based Persistent Memory

The vault is an Obsidian-style Markdown note collection that serves as the project's persistent memory. Every note is a .md file with YAML frontmatter, stored in a configurable vault directory (default: .vault/ at the workspace root).

Vault Structure

.vault/
├── 00-core/              # Core interaction rules and conventions
├── 10-projects/          # Per-project memory files
├── 20-shared-systems/    # Shared system documentation
├── 30-publishing/        # Publishing-related notes
├── saved-prompts/        # Saved prompt files
├── reports/              # Response outputs
└── *.md                  # Any Markdown note files

Note Format

---
id: my-note
tags: [architecture, backend]
type: design-doc
suggestedFiles: [src/main.ts, src/utils.ts]
---

# My Note

Content here...

Frontmatter Fields

Creating a Vault

• Run Claude: Create Vault from the command palette.
• This creates the directory structure and starter files (interaction-rules.md, README.md).

How Notes Are Used

• When you select tags in the prompt webview, all notes with matching tags are injected as Memory Files.
• The system prompt instructs Claude to treat these notes as authoritative context.
• suggestedFiles from included notes are automatically added to Attached Files.

Vault Indexing

On startup, the extension scans all .md files in the vault and builds indexes by tag, ID, and type. The vault is auto-reindexed when files change.

6. Sidebar Explorer

The Claude Explorer sidebar (activity bar icon) provides a hierarchical view of:

Vault Files

• All Markdown notes in the workspace vault, organized by folder.
• Click to open in a preview (.md files use markdown preview).
• Right-click: Add to Prompt, Delete.

Global Vault Files (if configured)

• Separate tree section for notes from an external global vault (set via claude.globalVaultPath).

Tags

• Flat list of all @tag entries found in vault notes.
• Click a tag to open all tagged files.
• Right-click: Add to Prompt (adds all tagged notes as context).

TODOs

• Parses TODO items from vault files containing sections matching "next steps", "todo", or "requests".
• Recognizes - [x] (done) and - (pending) items.
• Groups by parent folder. Click to open the file at the specific line.

Saved Prompts

• Lists all prompt files from {vaultRoot}/saved-prompts/.
• Click to reopen as an Iterative Prompt.
• Right-click: Add to Prompt, View Markdown, Delete.

Filtering

• Run Claude: Filter Vault Explorer to filter items by name.
• Run Claude: Clear Vault Explorer Filter to clear.

7. Writeback Engine (Auto-Apply Diffs)

When Claude outputs unified diffs inside fenced code blocks, the extension can apply them automatically.

Supported Diff Formats

• Standard unified diffs (--- a/file / +++ b/file)
• Diffs wrapped in [READY_TO_IMPLEMENT] / [/READY_TO_IMPLEMENT] markers
• Diffs wrapped in [DONE] / [/DONE] markers

Apply Flow

1. After a response, the Apply button activates if diffs are detected.
2. Click Apply — the extension parses, validates, and applies each patch.
3. If a patch fails to apply, the extension attempts to fix it (hunk alignment, context matching).
4. If validation still fails, a side-by-side comparison of original vs. fixed diffs is shown.
5. After successful application, the prompt updates to remove the applied patches and can re-request with adjustment-request for iterative refinement.

What Gets Applied

Only diffs inside the active response are applied. The extension tracks patch status (valid, fixed, invalid) and shows inline indicators.

8. Commands Reference

9. Configuration Reference

10. Architecture Overview

┌────────────────────────────────────────────────────────────┐
│                    VS Code Extension                        │
│  ┌──────────┐  ┌───────────────┐  ┌────────────────────┐  │
│  │ Sidebar   │  │ Prompt        │  │ Writeback Engine   │  │
│  │ Explorer  │  │ Webview       │  │ (diff parse/apply) │  │
│  └────┬─────┘  └───────┬───────┘  └─────────┬──────────┘  │
│       │                │                     │             │
│  ┌────▼────────────────▼─────────────────────▼──────────┐  │
│  │                Claude Client                          │  │
│  │  (shell integration → claude --bare --print)          │  │
│  └─────────────────────────┬────────────────────────────┘  │
│                            │                                │
│  ┌─────────────────────────▼────────────────────────────┐  │
│  │               Vault Manager + Index                   │  │
│  │  (tags, IDs, types → loaded from .vault/*.md)         │  │
│  └──────────────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────────────┘
           │
           ▼
    ┌──────────────┐
    │  Claude CLI   │
    │  (external)   │
    └──────────────┘

Key design decisions:

• No API keys — Routes through the locally-installed Claude CLI. You authenticate once via claude CLI login.
• Temp file piping — Prompts are written to temporary files and piped into claude --bare --print to avoid shell quoting issues.
• Token usage from project logs — The extension parses Claude CLI's project logs (~/.claude/projects/) to extract token counts after each call.
• Shared components — Reuses shared UI components from shared/vscode-components/ (prompt webview, vault sidebar, terminal abstraction).
• No Copilot integration — Unlike the DeepSeek extension, this one does not implement vscode.LanguageModelChatProvider. It uses the Claude CLI directly.

11. Build & Install

Prerequisites

• Node.js 20+
• Claude CLI installed and authenticated (claude available in PATH)
• VS Code 1.85+

Build

cd vscode-extensions/vscode-claude
npm install
npm run compile

The precompile step automatically materializes shared components from shared/vscode-components/.

Install

1. Run npm run compile to build the extension.
2. Copy the vscode-claude folder to your VS Code extensions directory, or package it:

   npx @vscode/vsce package
   code --install-extension vscode-claude-0.0.1.vsix
   

Development

For development with hot-reload:

cd vscode-extensions/vscode-claude
npm run watch

Then press F5 in VS Code to launch the extension debugger.

Dependencies

• js-yaml — YAML frontmatter parsing for vault notes
• sharp — Image processing (icon generation)
• Shared components from shared/vscode-components/ (materialized to vendor/ via prepare:shared-components)