clawdybackride

README

clawdybackride

Clawdybackride is a set of bindings to Claude Code's VSCode Extension. It allows you to "piggy-back" off of the claude extension's MCP server, such that you can interact with the VSCode window from your Go program.

The easy path

Just call the package-level functions, the way you'd call http.Get. The first call finds the extension session whose workspace matches your working directory, dials it, and caches the connection for everything after.

package main

import (
    "context"
    "fmt"

    "github.com/alexbathome/clawdybackride"
)

func main() {
    selection, err := clawdybackride.LatestSelection(context.Background())
    if err != nil {
        panic(err)
    }

    fmt.Printf("%s#L%d-L%d\n", selection.FilePath, selection.Start.Line, selection.End.Line)
    // output: main.go#L5-L10
}

If you'd rather blow up immediately than get a connection error from your first real call, force the connection up front with MustDefault:

var _ = clawdybackride.MustDefault() // panics if no IDE session matches cwd

The hard path

The default client is just a *client.Client. Build your own when you want to pick the working directory, hold several connections, or manage the lifetime yourself:

cbr, err := clawdybackride.Connect(ctx, "/path/to/workspace")
if err != nil {
    return err
}
defer cbr.Close()

sel, err := cbr.LatestSelection(ctx)

Drop lower still and choose the session yourself with ide.FindLockFile and client.Dial. Either way, clawdybackride.SetDefault(c) installs your client behind the package-level functions.

Both Connect and client.Dial take options for what they would otherwise assume — how long a call may take, where the extension is listening, and so on:

cbr, err := clawdybackride.Connect(ctx, cwd,
    client.WithCallTimeout(time.Minute), // default is 10s per call
    client.WithHost("172.30.16.1"),      // IDE on a Windows host, driven from WSL
    client.WithKeepAlive(30*time.Second),
)

Examples

Runnable programs for every supported call live in example/.

Disclaimer

The initial implementation of this library was human-driven. Latter functionality of additional MCP tools have then been added by Claude itself :)

Additionally, since this library relies on an internal API there is a high percentage change of this API making breaking changes that could break clawdybackride. I'll endeavour to keep this as up to date as I possibly can through the integration tests in internal/integration_tests.

Documentation

Overview

Package clawdybackride talks to the Claude Code IDE extension's MCP server, letting a Go program drive the editor window it was launched from.

The easy path is the package-level functions, which share a default client much like net/http.Get shares net/http.DefaultClient:

sel, err := clawdybackride.LatestSelection(ctx)

The first such call discovers the extension session whose workspace best matches the current working directory, dials it, and caches the connection for every later call. Discovery failures (no cwd, no matching lockfile, extension not running) surface as errors from that first call. If you would rather find out immediately - in a main() or a package-level var - use MustDefault, which panics instead.

The hard path is github.com/alexbathome/clawdybackride/client. Build your own client.Client with Connect, or with ide.FindLockFile and client.Dial directly if you want to choose the session yourself, then either use it as-is or install it with SetDefault.

Index

• func CheckDocumentDirty(ctx context.Context, filePath string) (client.DocumentStatus, error)
• func Close() error
• func CloseAllDiffTabs(ctx context.Context) (int, error)
• func CloseTab(ctx context.Context, tabName string) error
• func Connect(ctx context.Context, cwd string, opts ...client.Option) (*client.Client, error)
• func Default() (*client.Client, error)
• func Diagnostics(ctx context.Context, uri string) ([]client.FileDiagnostics, error)
• func ExecuteCode(ctx context.Context, code string) ([]client.ExecuteCodeContent, error)
• func LatestSelection(ctx context.Context) (client.Selection, error)
• func MustDefault() *client.Client
• func OpenDiff(ctx context.Context, p client.OpenDiffParams) (string, error)
• func OpenEditors(ctx context.Context) ([]client.EditorTab, error)
• func OpenFile(ctx context.Context, p client.OpenFileParams) (client.OpenFileResult, error)
• func SaveDocument(ctx context.Context, filePath string) (bool, error)
• func SetDefault(c *client.Client)
• func WorkspaceFolders(ctx context.Context) (client.WorkspaceFolders, error)

Functions

func CheckDocumentDirty

func CheckDocumentDirty(ctx context.Context, filePath string) (client.DocumentStatus, error)

CheckDocumentDirty reports whether a document has unsaved changes. The document must already be open in the editor; the extension does not read from disk, so an unopened file is an error rather than a clean result. filePath may be relative to the first workspace folder.

CheckDocumentDirty is a wrapper around client.Client.CheckDocumentDirty on the default client.

func Close

func Close() error

Close closes the default client and clears it, so a later package-level call dials a fresh connection. It is a no-op if no connection has been made.

func CloseAllDiffTabs

func CloseAllDiffTabs(ctx context.Context) (int, error)

CloseAllDiffTabs closes every open diff tab and returns how many it closed. Useful for clearing up after OpenDiff calls that were abandoned.

CloseAllDiffTabs is a wrapper around client.Client.CloseAllDiffTabs on the default client.

func CloseTab

func CloseTab(ctx context.Context, tabName string) error

CloseTab closes the editor tab whose label is tabName - the Label reported by OpenEditors, or the tab name given to OpenDiff. Closing a tab with unsaved changes leaves the IDE to prompt the user as it normally would.

CloseTab is a wrapper around client.Client.CloseTab on the default client.

func Connect

func Connect(ctx context.Context, cwd string, opts ...client.Option) (*client.Client, error)

Connect dials the IDE extension session whose workspace folder best matches cwd, passing opts through to client.Dial. The returned client is independent of the default one; use SetDefault if you want the package-level functions to use it - which is also how you give the package-level functions non-default options:

c, err := clawdybackride.Connect(ctx, cwd, client.WithCallTimeout(time.Minute))
clawdybackride.SetDefault(c)

func Default

func Default() (*client.Client, error)

Default returns the client used by the package-level functions, dialing the session that matches the current working directory on first use.

func Diagnostics

func Diagnostics(ctx context.Context, uri string) ([]client.FileDiagnostics, error)

Diagnostics returns the errors, warnings and hints the IDE's language services currently report for uri - the same squiggles shown in the editor, grouped per file. uri is a file:// URI; if it is empty, diagnostics for every file the IDE holds diagnostics for are returned.

Diagnostics are only as fresh as the IDE's own analysis, so a language server that is still indexing may report nothing for a file it has yet to reach.

Diagnostics is a wrapper around client.Client.Diagnostics on the default client.

func ExecuteCode

func ExecuteCode(ctx context.Context, code string) ([]client.ExecuteCodeContent, error)

ExecuteCode runs Python in the Jupyter kernel attached to the active notebook editor and returns the output as text and image blocks - a matplotlib figure comes back as a base64 PNG. Variables persist between calls for as long as the kernel lives, so successive calls build on each other.

It blocks for as long as the code runs and the user may be prompted to approve execution first, so size ctx's deadline accordingly.

ExecuteCode is a wrapper around client.Client.ExecuteCode on the default client.

func LatestSelection

func LatestSelection(ctx context.Context) (client.Selection, error)

LatestSelection returns the user's most recent editor selection, including the selected text and its line/character range. The selection survives focus moving away from the editor, so it still reports what the user highlighted after they switch to a terminal to run your program.

LatestSelection is a wrapper around client.Client.LatestSelection on the default client.

func MustDefault

func MustDefault() *client.Client

MustDefault is like Default but panics if the connection cannot be established, for callers that would only turn the error into a fatal anyway:

var cbr = clawdybackride.MustDefault()

func OpenDiff

func OpenDiff(ctx context.Context, p client.OpenDiffParams) (string, error)

OpenDiff opens a git-style diff view between two files and blocks until the user accepts, rejects, or closes it, returning what they chose. Pass a context without an aggressive deadline: this waits on a human.

The extension serves one WebSocket client at a time, so a Claude Code session attaching to the same window will disconnect this one and cut the call short.

OpenDiff is a wrapper around client.Client.OpenDiff on the default client.

func OpenEditors

func OpenEditors(ctx context.Context) ([]client.EditorTab, error)

OpenEditors returns one entry per open plain-text editor tab, across every editor group, reporting which is active and which have unsaved changes. Preview tabs and unsaved scratch buffers are included; diff tabs (opened via OpenDiff) and webviews are not - they never appear here at all.

OpenEditors is a wrapper around client.Client.OpenEditors on the default client.

func OpenFile

func OpenFile(ctx context.Context, p client.OpenFileParams) (client.OpenFileResult, error)

OpenFile opens a file in the editor and can select a range within it, located by matching text rather than line numbers - see client.OpenFileParams. By default the file is brought to the front as the active tab, which the extension acknowledges with only a confirmation message; opening in the background instead returns the fuller document detail.

OpenFile is a wrapper around client.Client.OpenFile on the default client.

func SaveDocument

func SaveDocument(ctx context.Context, filePath string) (bool, error)

SaveDocument writes an already-open document to disk. filePath may be relative to the first workspace folder.

The returned bool mirrors vscode's TextDocument.save(): true whenever the save didn't fail, including when the document had no unsaved changes to begin with - it does not indicate whether a write actually occurred. False means the save failed.

SaveDocument is a wrapper around client.Client.SaveDocument on the default client.

func SetDefault

func SetDefault(c *client.Client)

SetDefault installs c as the client used by the package-level functions, replacing any connection already dialed. It does not close the old client.

func WorkspaceFolders

func WorkspaceFolders(ctx context.Context) (client.WorkspaceFolders, error)

WorkspaceFolders returns the folders open in the IDE's workspace, along with the workspace root and, for a multi-folder workspace saved to disk, the .code-workspace file backing it.

WorkspaceFolders is a wrapper around client.Client.WorkspaceFolders on the default client.