IDE Adapter Skill (IDEAS)

A Claude Code skill that connects to the IDE Adapter VS Code extension via WebSocket, giving Claude direct access to VS Code's language intelligence, git history, and file system features.

Abbreviation: IDEAS (IDE Adapter Skill) — pronounced "ideas"

---

Quick Install

1. Install the IDE Adapter VS Code Extension

From VS Code Marketplace:

code --install-extension godstale.ide-adapter

Or from a .vsix file (download from Releases):

code --install-extension ide-adapter-<version>.vsix

2. Install the Python dependency

pip install websocket-client

3. Install this skill in Claude Code

Download ide-adapter-skill.skill from Releases, then:

/skills install ide-adapter-skill.skill

4. Verify

Open a workspace in VS Code — the extension starts automatically. Check the status bar at the bottom for IDEA: 7200 (0). You're ready.

---

Requirements

IDE Adapter VS Code Extension (Required)

This skill requires the IDE Adapter extension running in VS Code. Without it, the skill cannot connect to VS Code.

• Install the extension in VS Code
• The server starts automatically on port 7200 by default
• Auth token is auto-generated and saved to .vscode/settings.json

Python Dependency

pip install websocket-client

---

What This Skill Can Do

Once installed, Claude can use these VS Code features directly from the CLI:

Capability	Description
Search text	Grep-like search across the workspace with regex support
Replace text	Find-and-replace across multiple files
Go to definition	Resolve symbol definitions using VS Code's language server
Find references	Find all usages of a symbol
Diagnostics	Get errors/warnings from the language server
Document symbols	List classes, functions, interfaces in a file
Find files	Search files by name with glob patterns
Git history	View commit history for a file
Git diff	Compare file versions across commits
Git rollback	Restore a file to a previous commit
Local history	Access VS Code's automatic save snapshots
Local history diff	Compare snapshots between commits
Local history rollback	Restore to a local save snapshot

---

Installation

1. Install IDE Adapter in VS Code
2. Download ide-adapter-skill.skill from Releases
3. Install in Claude Code:

   /skills install ide-adapter-skill.skill
   

4. Install the Python dependency:

   pip install websocket-client

---

Settings Auto-Detection

The skill automatically reads port and auth token from .vscode/settings.json:

{
  "idea.server.port": 7200,
  "idea.server.authToken": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

No manual --port or --token arguments needed as long as the script runs from inside (or below) the workspace directory.

---

Usage Examples

Once installed, just describe what you want in natural language:

• "find all usages of IHandler"
• "go to definition of ClientSession"
• "show errors in src/extension.ts"
• "git history of src/server/IdeaServer.ts"
• "diff current version vs HEAD for src/extension.ts"
• "roll back src/extension.ts to 2 commits ago"
• "show local save history for src/handlers/FindHandler.ts"
• "find files named Handler"

Claude will automatically use the IDEAS skill to fulfill these requests.

---

Protocol

The skill communicates with the IDE Adapter extension using a WebSocket protocol (v0.1.6).

Supported topics:

/app/vscode/edit/find
/app/vscode/edit/replace
/app/vscode/nav/definition
/app/vscode/nav/references
/app/vscode/nav/symbols
/app/vscode/diag/list
/app/vscode/fs/findFiles
/app/vscode/history/list
/app/vscode/history/diff
/app/vscode/history/rollback
/app/vscode/localhistory/list
/app/vscode/localhistory/diff
/app/vscode/localhistory/rollback

See references/protocol.md for full topic documentation.

---

Windows (Git Bash) Notes

Two known issues on Windows with Git Bash:

1. Path expansion: Git Bash expands /app/vscode/... to C:/Program Files/Git/app/vscode/.... The skill handles this automatically by using Python subprocess calls instead of shell arguments.

2. Encoding (cp949): Korean Windows defaults Python stdout to cp949. The idea_client.py script auto-reconfigures stdout to UTF-8.

---

Troubleshooting

Problem	Solution
CONNECTION_FAILED	IDE Adapter not running or wrong port. Check VS Code status bar.
UNAUTHORIZED	Auth token missing or wrong. Check .vscode/settings.json → idea.server.authToken.
UNKNOWN_TOPIC with Git path prefix	Git Bash path expansion. Skill uses subprocess pattern to avoid this.
UnicodeEncodeError: cp949	Update to latest idea_client.py.
ModuleNotFoundError: websocket	Run pip install websocket-client.
INVALID_REQUEST	Missing required params. filePath must be absolute for nav topics.
HANDLER_ERROR	VS Code internal error. File may not exist or git repo unavailable.

---

Related

• IDE Adapter VS Code Extension — the required server-side component