Skip to content

VSCode Sockpuppet Python API

Welcome to the VSCode Sockpuppet Python API documentation!

VSCode Sockpuppet is a Python library that lets you programmatically control Visual Studio Code from Python scripts. It provides a clean, typed API that mirrors the VS Code Extension API.

Key Features

  • 🎯 Full VS Code Control - Access windows, editors, documents, and workspace
  • 🔄 Real-time Events - Subscribe to editor changes, file events, and more
  • 🎨 Rich UI - Create webviews, show messages, and dialogs
  • 📝 Document Manipulation - Read and edit text documents with full API
  • 🔌 Extension Integration - Launched by VS Code extensions for seamless integration
  • 🐍 Pythonic API - Clean, typed, intuitive interface

Quick Example

from vscode_sockpuppet import VSCodeClient

with VSCodeClient() as vscode:
    # Show a message
    vscode.window.show_information_message("Hello from Python!")

    # Get the active editor
    editor = vscode.window.active_text_editor
    if editor:
        doc = editor.document
        print(f"Editing: {doc.file_name}")
        print(f"Language: {doc.language_id}")
        print(f"Lines: {doc.line_count}")

    # List workspace folders
    folders = vscode.workspace.workspace_folders
    for folder in folders:
        print(f"Workspace: {folder['name']} at {folder['uri']}")

Installation

pip install vscode-sockpuppet

Or with uv:

uv pip install vscode-sockpuppet

Getting Started

  1. Quick Start Guide - Get up and running in 5 minutes
  2. API Reference - Complete API documentation
  3. Examples - Working code examples

Main Components

  • VSCodeClient - Main entry point for connecting to VS Code
  • Window - Window operations (messages, dialogs, editors)
  • Workspace - Workspace operations (files, configuration)
  • Editor - Text editor manipulation and decorations
  • TextDocument - Document access and text operations
  • Events - Event subscription system

Architecture

VSCode Sockpuppet consists of two parts:

  1. VS Code Extension (TypeScript) - Runs inside VS Code, provides WebSocket/Named Pipe server
  2. Python Package (this library) - Connects to VS Code and provides the API

The extension must be installed and running in VS Code for the Python client to work.

Support

License

MIT License - see LICENSE for details.