Skip to main content
Glama

Patchwork OS

npm version CI npm downloads license

You don't have an automation problem. You have a decision problem.

Every AI-agent horror story ends the same way: an action nobody stopped to question. Patchwork OS is the layer between the agent's impulse and the action — a local-first runtime where your AI can automate real work across your editor, GitHub, Slack, Gmail, and 45+ services, while anything consequential can be made to stop and ask you first.

Who it's for: developers and technical operators who already run agents against real systems — a repo that ships, an inbox that matters, a production service — and who want a record of what was allowed and why. It expects a terminal, a Node install, and comfort editing YAML.

Three ideas, one runtime:

  • Ask before acting. Every action is classified by blast radius — can it be undone, and how much breaks if it's wrong? Reversible things flow freely. Risky things wait in an approval queue with the evidence attached: what exactly will run, why it fired, and what happens if it's wrong.

  • Trust is earned, never assumed. Workers — named agents with jobs — start supervised and earn independence from their track record, per action type. Good at filing issues ≠ allowed to push code. One bad high-stakes action outweighs a hundred trivial successes. You set the ceiling; the math never raises it for them.

  • Every decision leaves a receipt. What was done, why it was allowed, and how it turned out — durable, replayable, explainable via patchwork judgments, the dashboard's traces page, and patchwork gate explain. When you approve something, you find out later whether you were right.

An agent wants to write a file. With the gate on, it waits — and shows you exactly what it would do:

The approval queue: a pending createFile call showing its risk tier, whether it can be undone, and the full content it would write, with Approve and Reject

You approve. The call proceeds, and both halves are on the record:

The activity stream showing two events — an approval_decision marked approved, and the createFile tool call that followed it, succeeding in 4ms

Status: stable 1.2

Version 1.2.7, published to npm as latest. The decision layer, recipes, connectors and IDE bridge all work and are dogfooded daily. Interfaces can still change between minor versions and some surfaces are rougher than others. Pin an exact version if you are building on it.

Whether the safety features are on depends on how you installed. This matters more than any other line in this README:

  • New install: patchwork-os init on a machine with no ~/.patchwork/config.json writes profile: governed. The gate is on from the first run.

  • Existing install: upgrading never changes your profile. An existing config stays as it is; opt in with patchwork profile governed and restart the bridge.

  • No config at all (starting the bridge without init): the compat profile, where nothing is gated.

Run patchwork doctor to see what is enforced on your machine right now. Trust its output over this table.

Feature

governed (new init)

compat (existing config, or none)

Approval queue

on at high, for automated triggers (cron, webhook, file-watch, git-hook) as well as manual runs

off unless --approval-gate high or all, and then manual runs only

Non-reversible writes

ask for approval whatever their tier

follow the tier threshold

Agent steps

contained: read-only tools, no network or shell

full access unless a step sets sandbox: true

Recipe plugins (servers:)

load only if listed in plugins.allow

any entry loads, in-process

A tool nothing is registered under

the run halts

the step is skipped

Kill switch (patchwork panic)

available; fails closed if its state is unreadable

available; fails open

Worker autonomy ramp

on for worker-owned recipes (runs need a driver, e.g. --driver subprocess)

off unless PATCHWORK_FLAG_WORKER_AUTONOMY=1 (same driver requirement)

Telemetry

off

off; opt in explicitly (details)

Under compat, a fresh bridge is an automation runtime, and it becomes a decision layer when you switch the gate on. Everything above about "stops and asks you first" describes the gate when it is on.

Related MCP server: MCP HTTP Proxy

The loop

trigger → recipe/worker → reversible?           → runs
                        → risky, gate on        → approval queue → your yes → receipt
                        → risky, gate off       → runs
                        → forbidden by policy   → refused (no approval unlocks it)

patchwork panic blocks every write-tier tool call across all running bridges, immediately. Reads keep working, and in-flight reasoning is not killed — it is a write block, not a full stop.

Install

npm install -g patchwork-os
patchwork-os init

init scaffolds ~/.patchwork, seeds local-only recipes, and registers Patchwork's PreToolUse hook in ~/.claude/settings.json. Restart Claude Code afterwards — it reads hooks at session start.

Prereqs: Node 22.5+. macOS, Linux, and native Windows (no WSL).

Two things worth knowing before you start:

  • Use a global install, not npx. npx does not persist the binary, so the very next command in any guide will not be found.

  • The web dashboard is not in the npm package. It's a Next.js app that needs its own build, so it ships with the repo:

    git clone https://github.com/Oolab-labs/patchwork-os && cd patchwork-os/dashboard
    npm install && npm run build && npm start   # http://localhost:3200

    Everything below works from the CLI without it. The dashboard is where approvals, traces and connector setup are pleasant rather than possible.

First run: zero connectors

Prove the runtime works before wiring any service to it. daily-status touches only git and local files — no accounts, no network:

patchwork recipe run daily-status

It reads your commits since yesterday plus ~/.patchwork/planned.md, and writes a Markdown digest to ~/.patchwork/inbox/daily-status-<date>.md. If that file exists, your install is sound.

Useful neighbours: patchwork recipe list, patchwork status, patchwork recipe doctor <name> when something misbehaves.

Morning Brief: the connected workflow

patchwork-os init --with-connectors   # seeds the connector-backed recipes
patchwork connect gmail
patchwork connect google-calendar
patchwork connect github
patchwork connect linear
patchwork recipe run morning-brief

The recipe pulls unread mail, today's calendar, your open GitHub issues and PRs, Linear issues, and local git activity, then has a model summarise them into one Markdown brief in ~/.patchwork/inbox/. Its email step is triage — it lists what needs an answer; it does not compose or send replies. Nothing leaves your machine except the API calls to the services you connected.

All four connectors are required as written — no step is guarded, so a missing one halts the run. Drop the steps you don't want, or start from daily-status and add sources one at a time.

Requires a working model driver (--driver subprocess with the Claude CLI on PATH, or an API key). patchwork recipe preflight templates/recipes/morning-brief.yaml lists exactly what a recipe needs before you run it.

Two ways to run this

As an automation runtime — recipes, workers, connectors, the decision layer. Needs ~/.patchwork and a model driver; an editor is optional.

patchwork start        # bridge + Claude + dashboard

patchwork start launches claude --ide alongside the bridge, so it expects the Claude CLI on your PATH. Use patchwork start --no-dashboard, or run the bridge alone with patchwork --workspace ., if you don't want that.

On a global npm install there is no dashboard/ to start, so it logs a dashboard warning and carries on with bridge + Claude; pass --no-dashboard to silence it. From a repo clone it starts all three.

As a standalone IDE bridge — 180 MCP tools giving Claude Code eyes and hands in your editor: diagnostics, LSP navigation, refactoring with risk analysis, debugger, terminal, git/GitHub, file ops. No ~/.patchwork, no recipes, no gate.

npm install -g patchwork-os
claude-ide-bridge install-extension     # VS Code / Cursor / Windsurf / Antigravity
claude-ide-bridge --workspace .
claude --ide                            # in another terminal

JetBrains via a companion plugin. Claude Desktop, Gemini CLI, Codex CLI, Grok Build, and claude.ai connect over stdio or HTTP. Use the bridge alone forever if that's all you need; the runtime is an optional layer on top.

claude --ide can't find an IDE? Set CLAUDE_CODE_IDE_SKIP_VALID_CHECK=true (init does this for you).

What "local-first" does and doesn't mean

On your machine: the runtime, every recipe and worker, all credentials and connector tokens, the approval queue, and every log and decision receipt under ~/.patchwork/. Nothing is uploaded, and no Patchwork-operated server sits in any path.

Over the network, necessarily: calls to whatever model you point it at (Anthropic, OpenAI, Google, xAI) and to every connector you authorise (Gmail, GitHub, Slack…). Prompts, and whatever context a step feeds them, go to that model provider. Choosing a local Ollama endpoint keeps inference on your machine too; connector calls still leave it, because that is what a connector is.

Only if you opt in: anonymous analytics.

Other boundaries worth knowing: runCommand executes only allowlisted commands, sendHttpRequest blocks private and loopback ranges, and file tools refuse symlink escapes out of the workspace. Remote deployments must sit behind TLS with OAuth 2.0 — see docs/remote-access.md.

What's here

  • Decision layer — approval queue · blast-radius action classes · worker trust ramp · kill switch · decision receipts

  • Automation — YAML recipes · cron/file/git/test/webhook triggers · event hooks · multi-model (Claude, GPT, Gemini, Grok, Ollama)

  • Connectors — 45+, all writes governed by your policy: GitHub, Slack, Gmail, Calendar, Drive, Linear, Jira, Sentry, Notion, Stripe, PagerDuty, Datadog, …

  • IDE bridge — 180 MCP tools · VS Code-family extension · JetBrains plugin · plugins hot-reload (write tools mid-session)

  • Oversight — web dashboard · mobile push approvals (PWA) · halts/judgments CLI · trace memory across sessions

  • Deployment — your laptop · headless VPS with OAuth 2.0 (guide) · native Windows

Recipes are plain YAML: a trigger (cron, file save, git commit, test run, or any webhook — iPhone Shortcut, Stream Deck, Home Assistant) plus steps. Share them like dotfiles, install them from the marketplace, or let the dashboard generate one from a sentence.

Workers are recipes with an identity and a track record. A worker that triages failing CI starts by only proposing ("this looks like a real break — file an issue?"). Confirm its filings were real and it earns a longer leash — for that job only. It can be demoted in one bad day. You can cap any worker permanently with one line of YAML.

Why not Zapier / an MCP server / a hosted assistant? Honest tradeoffs: documents/comparison.md.

Docs

Docs index · Platform reference · Recipes & triggers · Worker autonomy · Plugin authoring · Architecture · Windows · ADRs

Telemetry

Off by default; nothing is sent unless you opt in. If you do: aggregate counts and latencies only — never paths, prompts, file contents, arguments, or anything from ~/.patchwork/. Details & source.

Contributing & support

Issues · Discussions · CONTRIBUTING.md

⭐ If this saved you a config file or a blown deploy, a star is the only signal I get that it's helping.

MIT © Oolab Labs — what that covers · name and marks

Available Tools

178 tools
addLinearCommentA

Add a comment to a Linear issue. Requires Linear connector connected.

Inputs: id (required), body (required).

applyCodeActionA
Destructive

Apply code action by title. Use getCodeActions first to see options.

Inputs: endLine (required), filePath (required), endColumn (required), startLine (required), +2 more.

auditDependenciesA
Read-only

Detect outdated packages (current vs latest). Supports npm, yarn, pnpm, cargo, pip. Complement to getSecurityAdvisories.

Inputs: maxAge, packageManager.

batchFindImplementationsA
Read-only

Find implementations for up to 10 symbols. Prefer over repeated findImplementations.

Inputs: items (required).

batchGetHoverA
Read-only

Hover info (type signatures, docs) for up to 10 positions. Prefer over repeated getHover.

Inputs: items (required).

batchGoToDefinitionA
Read-only

Go to definition for up to 10 symbols. Prefer over repeated goToDefinition.

Inputs: items (required).

beginTransactionA
Read-only

Start a new multi-file edit transaction. Returns a transactionId for subsequent stageEdit calls.

Inputs: transactionId.

bridgeDoctorA
Read-only

Health check: extension, git, linters, test runners, GitHub CLI. Use when tools misbehave.

Inputs: no named parameters.

butlerForgetA
Destructive

Retract a fact by its seq (from butlerRecall). Writes a tombstone — the fact stops being believed, and the original row stays in the log so the history remains auditable.

Inputs: seq (required).

butlerRecallA
Read-only

Read what Butler currently believes about the user. Returns one value per subject+predicate, already resolved for contradictions and retractions. Filter by subject to narrow.

Inputs: limit, subject, minTrust, predicate.

butlerRememberA

Record one durable fact about the user (preference, household, standing context) as subject + predicate + value. Stored at agent trust: auditable, but not something Butler asserts on its own.

Inputs: object (required), subject (required), predicate (required), sourceRef, +1 more.

cancelClaudeTaskA
Idempotent

Cancel a pending or running Claude task.

Inputs: taskId (required).

captureScreenshotA
Read-only

Capture screenshot → base64 PNG. macOS/Linux with display only. Not available on headless servers.

checkDocumentDirtyA
Read-only

Check if file has unsaved changes. Uses VS Code buffer when ext connected; heuristic otherwise.

Inputs: filePath (required).

clearEditorDecorationsA
Idempotent

Clear editor decorations by ID, or omit id to clear all Claude-managed decorations.

Inputs: id.

closeAllDiffTabsA
Destructive

Close all diff tabs and clean up temp diff directories.

closeTabA
Destructive

Close editor tab by file path. Prompts to save if dirty. Requires ext.

Inputs: filePath (required).

commitTransactionA
Destructive

Write all staged edits atomically. All files are written; on partial failure, written files are NOT rolled back (use rollbackTransaction before commitTransaction to verify).

Inputs: transactionId (required).

contextBundleA
Read-only

Collect IDE context in one call: active file, diagnostics, diff, editors, handoff note, git status.

Inputs: summarize, includeDiff, includeHandoffNote.

createFileA
Destructive

Create file or directory within workspace. Uses VS Code when connected, native fs fallback.

Inputs: filePath (required), content, overwrite, isDirectory, +1 more.

createLinearIssueA

Create a new Linear issue. Requires Linear connector connected. Returns the created issue identifier and URL.

Inputs: title (required), teamKey, priority, labelNames, +1 more.

createPlanB

Create .claude-plan.md in workspace root. Markdown with sections and task checklists.

Inputs: title (required), fileName, sections.

createTerminalC
Destructive

Create VS Code integrated terminal. Options: name, cwd, env vars, shell.

Inputs: cwd, env, name, show.

ctxGetTaskContextA
Read-only

Unified context for issue/PR/commit/error ref. Composes issue + linked commits + related traces. mode:'summary' (default) caps bodies; mode:'full' for untruncated. Prefer over gh/git.

Inputs: ref (required), mode, maxLinkedCommits.

ctxQueryTracesB
Read-only

Unified query over approval / enrichment / recipe-run trails. Filter by traceType, time window, or natural key. Answers 'why did X happen' across sources.

Inputs: q, key, tag, limit, +3 more.

ctxSaveTraceA

Record a problem+solution trace after resolving a task. Future sessions see it via ctxQueryTraces and the session-start digest. Keep problem + solution to one line each.

Inputs: ref (required), problem (required), solution (required), tags.

deleteFileA
Destructive

Delete workspace file or directory. VS Code (with trash) when connected, native fs fallback.

Inputs: filePath (required), useTrash, recursive.

deletePlanA
Destructive

Delete a plan file from the workspace root.

Inputs: fileName (required).

detectUnusedCodeA
Read-only

Find unused exports, locals, parameters via tsc --noUnusedLocals or ts-prune.

Inputs: maxResults, includePatterns.

disposeTerminalA
Destructive

Close a VS Code terminal by name or index.

Inputs: name, index.

editTextA
Destructive

Insert/delete/replace text at 1-based line/col. Atomic multi-edit. Uses VS Code or native fs. Workspace files only.

Inputs: edits (required), filePath (required), save.

enrichCommitA
Read-only

Enrich commit w/ linked issues. Parses #N / GH-N refs from message, fetches issue state via gh, classifies close vs ref. Missing issues flagged unresolved — not errors.

Inputs: ref.

enrichStackTraceA
Read-only

Map stack-trace frames to introducing commits via git blame. Parses Node/Python/browser traces, filters to in-workspace files, returns per-frame commit + overall top suspect.

Inputs: stackTrace (required), maxFrames.

evaluateInDebuggerA
Read-only

Evaluate expression in active debug session. Session must be paused at a breakpoint.

Inputs: expression (required), context, frameId.

executeVSCodeCommandA

Execute VS Code command by ID. Use listVSCodeCommands to discover IDs.

Inputs: command (required), args.

explainDiagnosticA
Read-only

Bundle diagnostic details + code context (±10 lines) + go-to-definition + callers (up to 5) for a file/line/character position.

Inputs: line (required), filePath (required), character (required).

explainSymbolA
Read-only

Get comprehensive symbol info in one call: type signature, docs, definition location, call hierarchy, and reference count.

Inputs: line (required), column (required), filePath (required), useMemoryGraph, +3 more.

fetchCalendarEventsA
Read-only

Fetch upcoming Google Calendar events. Returns events for the next N days. Requires Google Calendar connector connected.

Inputs: daysAhead, calendarId, maxResults.

fetchGithubIssueA
Read-only

Fetch a GitHub issue by URL or owner/repo#number ref. Returns title, body, state, labels, assignees, and author. Requires GitHub connector connected.

Inputs: issueRef (required).

fetchGithubPRA
Read-only

Fetch a GitHub pull request by URL or owner/repo#number ref. Returns title, body, state, branches, labels, review decision, and diff stats. Requires GitHub connector connected.

Inputs: prRef (required).

fetchLinearIssueA
Read-only

Fetch a Linear issue by identifier or URL. Returns title, description, state, assignee, labels, and priority. Requires Linear connector connected.

Inputs: issueId (required).

fetchSentryIssueA
Read-only

Fetch a Sentry issue and enrich its stack trace with git blame. Returns per-frame commit attribution + top suspect commit. Requires Sentry connector connected.

Inputs: issueId (required), maxFrames.

fetchSlackProfileA
Read-only

Get the connected Slack workspace name, team ID, and bot user ID. Use to confirm Slack is connected.

Inputs: no named parameters.

findFilesA
Read-only

Find files by name/glob pattern in the workspace. Respects .gitignore.

Inputs: pattern (required), directory.

findImplementationsA
Read-only

Find implementations of interface, abstract method, or abstract class.

Inputs: line (required), column (required), filePath (required).

findReferencesA
Read-only

Find all references to a symbol at a given position using VS Code LSP.

Inputs: line (required), column (required), filePath (required), cursor.

findRelatedTestsA
Read-only

Find test files that cover a source file via import search + name patterns. Optionally includes coverage pct per test file.

Inputs: filePath (required), includeCoverage.

fixAllLintErrorsA
DestructiveIdempotent

Auto-fix lint errors. VS Code source.fixAll when connected, falls back to eslint/biome/ruff.

Inputs: filePath (required).

foldingRangesA
Read-only

Foldable regions in a file (functions, classes, imports, comments). Returns {startLine, endLine, kind}.

Inputs: filePath (required).

formatAndSaveA
DestructiveIdempotent

Format a file and save it in one call (formatDocument + saveDocument). Formatter errors propagate; save is not attempted on format failure.

Inputs: filePath (required).

formatDocumentA
DestructiveIdempotent

Format file via VS Code formatter or CLI fallback (prettier/biome/black/gofmt/rustfmt).

Inputs: filePath (required).

formatRangeA

Format a line range via LSP formatter. Faster than full formatDocument for large files.

Inputs: endLine (required), filePath (required), startLine (required).

generateAPIDocumentationA
Read-only

Generate API docs (markdown/JSON) for TS/JS exported symbols. Extracts fns, classes, interfaces, JSDoc.

Inputs: files (required), format, includePrivate.

generateTestsA
Read-only

Generate test scaffold from exported fns/classes. Returns describe/it content; does not write file.

Inputs: file (required), framework, outputFile.

getActivityLogA
Read-only

Query recent tool call log: names, timing, status, percentiles, co-occurrence.

Inputs: last, tool, status, showStats, +3 more.

getAnalyticsReportB
Read-only

Session analytics: top tools by call count, hook events, recent automation tasks.

Inputs: windowHours.

getArchitectureContextA
Read-only

Architectural overview via codebase-memory graph: module boundaries, dependencies, ADRs, hotspot files. Returns structured query plan. Requires codebase-memory connected.

Inputs: aspects, maxNodes.

getBridgeStatusA
Read-only

IDE bridge status: ext connection, circuit breaker, uptime, tool availability.

Inputs: no named parameters.

getBufferContentA
Read-only

Read workspace file from VS Code buffer including unsaved changes. Use before editText. Returns isDirty flag. Workspace files only.

Inputs: filePath (required), endLine, startLine.

getCallHierarchyB
Read-only

Get the call hierarchy for a function or method. Use direction="incoming" to find callers, "outgoing" to see everything it calls, or "both" (default).

Inputs: line (required), column (required), filePath (required), cursor, +2 more.

getChangeImpactB
Read-only

Blast radius after editing a file: diagnostics + reference counts for changed symbols.

Inputs: filePath (required), workspaceOnly, changedSymbols.

getClaudeTaskStatusA
Read-only

Get the status and output of a Claude task enqueued with runClaudeTask.

Inputs: taskId (required).

getCodeActionsA
Read-only

Get available code actions (quick fixes, refactorings) for a range in a file.

Inputs: endLine (required), filePath (required), endColumn (required), startLine (required), +1 more.

getCodeCoverageA
Read-only

Parse coverage report (lcov/coverage-summary.json/clover.xml) → per-file line/branch/fn %. Does not run tests.

Inputs: file, minCoverage.

getCodeLensA
Read-only

Code lens items for a file: ref counts, Run/Debug buttons, impl counts from language server.

Inputs: filePath (required).

getCommitDetailsA
Read-only

Full commit details: author, date, message, changed files, optional diff patch.

Inputs: commitHash (required), filePath, includePatch.

getCommitsForIssueA
Read-only

Reverse commit→issue lookup from the persisted enrichment log. Returns commits that referenced the given issue, newest first.

Inputs: issue (required), limit, linkType, workspaceScope.

getConnectorStatusA
Read-only

Returns the auth status of all MCP connectors (GitHub, Linear, Sentry). Shows whether each is connected and verified, when the token expires, and whether re-authorization is needed.

Inputs: no named parameters.

getCurrentSelectionA
Read-only

Get the current text selection in the editor

getDebugStateA
Read-only

VS Code debugger state: session info, paused location, call stack, locals. hasActiveSession=false if idle.

getDependencyTreeA
Read-only

Dependency tree (npm/cargo/go/pip). Auto-detects package manager. Returns names and versions.

Inputs: depth, packageManager.

getDiagnosticsB
Read-only

Errors/warnings from TS, ESLint, Pyright, Ruff, Cargo, Go vet, Biome. Real-time LSP when ext connected.

Inputs: uri, topN, severity, maxResults.

getDiffBetweenRefsC
Read-only

Diff between two git refs (branches/tags/commits). statOnly for file-level summary only.

Inputs: ref1 (required), ref2 (required), context, filePath, +1 more.

getDiffFromHandoffA
Read-only

Compute what changed since the handoff note was written: git diff summary + new/resolved diagnostics.

Inputs: no named parameters.

getDocumentSymbolsA
Read-only

List symbols (fns, classes, interfaces, methods) in a file: names, kinds, lines, parents.

Inputs: filePath (required), kind, topN, maxDepth.

getFileTreeA
Read-only

Workspace file tree. Respects .gitignore. Skips node_modules, .git, dist, build, coverage.

Inputs: maxDepth, directory, maxEntries, includeHidden.

getGitDiffA
Read-only

Get the git diff output for the workspace or a specific file

Inputs: staged, context, filePath.

getGitHotspotsC
Read-only

Most frequently changed files in git history. High frequency → active dev or instability.

Inputs: days, path, limit.

getGitLogA
Read-only

Get recent git log entries for the workspace or a specific file

Inputs: filePath, maxEntries.

getGitStatusA
Read-only

Git status: branch, staged/unstaged/untracked files, ahead/behind counts.

Inputs: filePath.

getHandoffNoteA
Read-only

Retrieve handoff note from prior session (Desktop or CLI). Call at session start to resume.

Inputs: no named parameters.

getHoverA
Read-only

Get hover information (type info, documentation) for a symbol at a given position.

Inputs: line (required), column (required), filePath (required).

getHoverAtCursorA
Read-only

Hover docs for symbol at current cursor. Zero-input wrapper around getHover.

getImportedSignaturesA
Read-only

Resolve imported symbols → type signatures. Use before calling unfamiliar functions.

Inputs: filePath (required), maxImports.

getImportTreeA
Read-only

Tree of local imports for a file. Useful for understanding deps and finding circular imports.

Inputs: file (required), maxDepth, includeExternal.

getInlayHintsA
Read-only

Inlay hints (inline type annotations, param names) for a line range. e.g. TS types, Rust lifetimes.

Inputs: file (required), endLine (required), startLine (required).

getLatestSelectionA
Read-only

Get the most recent text selection (even if not in the active editor)

getOpenEditorsA
Read-only

Open files/tabs with isDirty, isActive when ext connected. Fallback: session-opened files only.

getPerformanceReportB
Read-only

Live performance assessment: per-tool latency percentiles, throughput, extension health, session counts, and overall health score.

Inputs: windowMinutes.

getPlanA
Read-only

Read plan file. Returns title, sections, tasks, and completion status.

Inputs: fileName.

getProjectContextA
Read-only

Cached session-start brief: active file, errors, recent commits, modules. Skips cold-start re-exploration.

Inputs: force, maxAgeMs, sections.

getProjectInfoA
Read-only

Project overview: name/version, languages, pkg manager, scripts, deps, config, git. Call at session start.

Inputs: no named parameters.

getPRTemplateA
Read-only

PR description from commits and diff stats vs base branch. Returns markdown → pass to githubCreatePR.

Inputs: base, style.

getSecurityAdvisoriesA
Read-only

Security audit: CVEs with severity and remediation. Auto-detects npm/yarn/pnpm/cargo/pip-audit.

Inputs: severity, onlyFixable, packageManager.

getSemanticTokensA
Read-only

Semantic token types and modifiers for a file from the language server.

Inputs: filePath (required), endLine, maxTokens, startLine.

getSessionUsageA
Read-only

Token usage estimate for this session: schema size, call counts, largest tool results.

Inputs: no named parameters.

getSymbolHistoryA
Read-only

Symbol evolution: LSP definition + git blame on definition site + file commit history. Answers 'why does this exist?' and 'who changed it last?'

Inputs: line (required), column (required), filePath (required), blameLines, +1 more.

getTerminalOutputA
Read-only

Get recent output from a VS Code integrated terminal. Identify by name or index (from listTerminals). Returns last N lines. On headless VPS/SSH, use runInTerminal instead.

Inputs: name, index, lines.

getToolCapabilitiesB
Read-only

Available CLI tools, ext connection state, and which features are functional vs stub-only.

Inputs: verbose.

getTypeHierarchyA
Read-only

Type hierarchy: supertypes (parents) and subtypes (impls/subclasses). Requires LSP support.

Inputs: file (required), line (required), column (required), direction, +1 more.

getTypeSignatureB
Read-only

Type signature for symbol at position via LSP hover. Returns clean signature from hover markdown.

Inputs: file (required), line (required), column (required).

getWorkspaceFoldersA
Read-only

Get all workspace folders currently open in the IDE

getWorkspaceSettingsA
Read-only

Read VS Code workspace settings. Filter by section (e.g. 'editor', 'typescript'). Returns source scope.

Inputs: target, section.

gitAddA

Stage files for commit. Omit to stage all tracked (git add -u). addUntracked:true for new files.

Inputs: files, addUntracked.

gitBlameA
Read-only

Per-line last modifier and commit. Trace why code was written or find the introducing commit.

Inputs: filePath (required), endLine, startLine.

gitCheckoutA
Destructive

Switch to a branch, or create and switch to a new branch. Use create: true to create from HEAD or a specified base.

Inputs: branch (required), base, create.

gitCommitA
Destructive

Commit staged changes. Pass files to stage-and-commit in one step. Returns hash, branch, files.

Inputs: message (required), files, addAll.

gitFetchA
Read-only

Fetch updates from a remote without merging. Updates remote-tracking branches so gitListBranches and gitCheckout see the latest state. Use gitPull to fetch and merge in one step.

Inputs: all, remote.

gitListBranchesA
Read-only

List git branches. Returns local branches with the current branch marked. Pass includeRemote: true for remote-tracking branches.

Inputs: includeRemote.

gitPullA
Destructive

Pull changes from a remote into the current branch. Defaults to origin with merge. Use rebase: true for linear history.

Inputs: branch, rebase, remote.

gitPushA
Destructive

Push the current branch to a remote. Use setUpstream: true on the first push. Force push uses --force-with-lease. Blocked on main/master.

Inputs: force, branch, remote, setUpstream.

gitStashA
Destructive

Stash current changes to get a clean working tree. Required before switching branches with uncommitted changes. Use gitStashPop to restore. Pass includeUntracked: true to also stash new files.

Inputs: message, includeUntracked.

gitStashListA
Read-only

List all stash entries in the repository. Returns each entry's index, branch it was stashed from, message, and age. Use before gitStashPop to identify the right entry to restore.

Inputs: no named parameters.

gitStashPopA
Destructive

Restore stashed changes to the working tree. Pops the most recent stash by default, or a specific entry by index (from gitStashList).

Inputs: index.

goToDeclarationA
Read-only

Go to the declaration of a symbol (header file in C/C++, .d.ts entry in TypeScript). Unlike goToDefinition, navigates to the 'declare' statement rather than the implementation.

Inputs: line (required), column (required), filePath (required).

goToDefinitionB
Read-only

Go to the definition of a symbol at a given position using VS Code LSP.

Inputs: line (required), column (required), filePath (required).

goToTypeDefinitionA
Read-only

Go to the type definition of a symbol. Unlike goToDefinition (navigates to declaration), this navigates to where the type itself is defined.

Inputs: line (required), column (required), filePath (required).

jumpToFirstErrorA
Idempotent

Jump to first workspace error (getDiagnostics→openFile→decoration). Returns {found:false} if none.

Inputs: no named parameters.

launchQuickTaskA

Launch context-aware Claude task from named preset. Same dispatch path as sidebar + CLI. 5s cooldown per preset.

Inputs: presetId (required), source.

listClaudeTasksA
Read-only

List your Claude tasks, optionally filtered by status.

Inputs: status.

listPlansA
Read-only

List all plan files in the workspace root. Returns filenames with titles from frontmatter.

Inputs: no named parameters.

listTerminalsA
Read-only

List active VS Code terminals: names, indices, output capture availability.

Inputs: no named parameters.

listVSCodeCommandsA
Read-only

List all registered VS Code commands (up to 2000). Filter by substring to find IDs.

Inputs: filter.

listVSCodeTasksA
Read-only

List VS Code tasks from tasks.json and extensions. Returns name, type, group, source.

Inputs: type.

openDiffA
Destructive

Open a diff view comparing old file content with new file content. Creates temporary files on disk.

Inputs: tabName (required), newFilePath (required), oldFilePath (required), newFileContents (required).

openFileA
Idempotent

Open a file in the editor and optionally select a range of text

Inputs: filePath (required), startLine, startText.

openInBrowserA

Write HTML to temp file and open in default browser. For visual reports and dashboards.

Inputs: html (required), filename.

organizeImportsA
DestructiveIdempotent

Organize/sort imports in workspace file. Uses VS Code ext when connected; falls back to Biome or Prettier.

Inputs: filePath (required).

parseHttpFileA
Read-only

Parse VS Code REST Client file (.http/.rest). Returns method, URL, headers, body per request.

Inputs: filePath (required).

prepareRenameA
Read-only

Check if symbol can be renamed. Returns canRename:false with reason if not. Use before renameSymbol.

Inputs: line (required), column (required), filePath (required).

previewCodeActionA
Read-only

Preview edits a code action would make without applying. Use before applyCodeAction.

Inputs: endLine (required), filePath (required), endColumn (required), startLine (required), +2 more.

previewEditA
Read-only

Preview what editText or searchAndReplace would do as a unified diff, without writing to disk.

Inputs: filePath (required), operation (required), search, endLine, +5 more.

readClipboardA
Read-only

Read system clipboard. Returns up to 100 KB of text.

refactorAnalyzeA
Read-only

Refactor impact: rename safety, ref/caller counts, risk level (low/medium/high). Use before renameSymbol.

Inputs: line (required), column (required), filePath (required).

refactorExtractFunctionB
Destructive

Extract lines into a named function. Uses VS Code Extract Function when available.

Inputs: file (required), endLine (required), startLine (required), functionName (required).

refactorPreviewA

Preview refactoring edits across files without applying. Use getCodeActions first.

Inputs: endLine (required), filePath (required), endColumn (required), startLine (required), +2 more.

renameFileA
Destructive

Rename or move workspace file/directory. Uses VS Code when connected, native fs fallback.

Inputs: newPath (required), oldPath (required), overwrite.

renameSymbolA
Destructive

Rename symbol across all files via LSP. Returns affected files and edit counts.

Inputs: line (required), column (required), newName (required), filePath (required).

replaceBlockA
Destructive

Replace exact text block in a workspace file by content match, no line numbers. Fails clearly if not found or ambiguous.

Inputs: filePath (required), newContent (required), oldContent (required), save.

resumeClaudeTaskA

Re-run a failed, cancelled, or completed Claude task with same prompt. Returns new taskId.

Inputs: taskId (required), effort, timeoutMs, maxBudgetUsd, +2 more.

rollbackTransactionA
Read-only

Discard all staged edits for a transaction without writing anything to disk.

Inputs: transactionId (required).

runClaudeTaskA

Enqueue Claude subprocess task. Returns taskId for getClaudeTaskStatus, or stream=true to block.

Inputs: prompt (required), model, effort, stream, +7 more.

runCommandA
Destructive

Execute allowlisted command. Returns stdout, stderr, exit code, timing. No shell for security.

Inputs: command (required), cwd, args, timeout.

runInTerminalA
Destructive

Execute command and wait for completion. Returns exit code and output. Prefer over runCommand.

Inputs: command (required), name, show, index, +1 more.

runTestsA

Run tests (Vitest/Jest/Pytest/Cargo/Go). Returns pass/fail, failures, file:line. Cached 30s.

Inputs: filter, runner, noCache, timeoutMs.

runVSCodeTaskA
Destructive

Run VS Code task by name. Waits for completion, returns exit code. For build/test/lint tasks.

Inputs: name (required), type, timeout.

saveDocumentA
Destructive

Save workspace document via VS Code buffer when ext connected. No-op otherwise (editText writes to disk).

Inputs: filePath (required).

screenshotAndAnnotateB
Read-only

Correlate browser state with IDE state: dev server URL, diagnostics, git diff summary, and Playwright steps to capture screenshot.

Inputs: url, fullPage, waitForSelector.

searchAndReplaceA
Destructive

Find and replace across workspace files. Supports regex with capture groups. Returns modified files.

Inputs: pattern (required), replacement (required), glob, dryRun, +3 more.

searchToolsA
Read-only

Find tools by keyword/category before tools/list. In --lazy-tools mode, call this first then tools/schema, or set includeSchema:true to return each match's inputSchema inline.

Inputs: limit, query, categories, includeSchema.

searchWorkspaceA
Read-only

Search workspace files via ripgrep. Returns matching lines with file paths and line numbers.

Inputs: query (required), isRegex, fileGlob, maxResults, +2 more.

searchWorkspaceSymbolsB
Read-only

Search workspace symbols (classes, fns, vars, interfaces) by name via LSP.

Inputs: query (required), maxResults.

selectionRangesB
Read-only

Hierarchical selection ranges at position: identifier→expression→block→function→class.

Inputs: line (required), column (required), filePath (required).

sendHttpRequestA

HTTP/HTTPS request → status, headers, body. Body truncated at maxResponseBytes (default 50 KB).

Inputs: url (required), method (required), body, headers, +3 more.

sendTerminalCommandA
Destructive

Send text/command to VS Code terminal. Fire-and-forget; use getTerminalOutput to check results.

Inputs: text (required), name, index, isCommand, +1 more.

setActiveWorkspaceFolderA
Idempotent

Set active workspace folder for file ops. Useful in multi-root workspaces.

Inputs: path (required).

setDebugBreakpointsA

Set breakpoints in a file (replaces existing). Supports conditions, logpoints, hit counts.

Inputs: file (required), breakpoints (required).

setEditorDecorationsA
Idempotent

Place visual decorations (highlights, inline text) on file lines. Grouped by ID; replaces on each call.

Inputs: id (required), file (required), decorations (required).

setHandoffNoteA
DestructiveIdempotent

Save context note that persists across sessions. Use when switching between CLI and Desktop.

Inputs: note (required).

setWorkspaceSettingA
Destructive

Write VS Code workspace setting (dot notation e.g. editor.tabSize). security.* writes blocked.

Inputs: key (required), value (required), target.

signatureHelpA
Read-only

Function signature and param info at a call site. Returns active sig, param index, overloads.

Inputs: line (required), column (required), filePath (required).

slackListChannelsA
Read-only

List public Slack channels the bot has access to. Returns id, name, member count.

Inputs: limit.

slackPostMessageA

Post a message to a Slack channel. Use channel name (e.g. 'general') or channel ID. Optionally reply in a thread by providing threadTs.

Inputs: text (required), channel (required), threadTs.

spawnWorkspaceA

Spawn claude-ide-bridge for a workspace dir. Returns pid/port/authToken once lock appears; optionally waits for extension handshake.

Inputs: path (required), port, token, timeoutMs, +4 more.

stageEditB
Read-only

Stage a file edit inside a transaction. Supports lineRange and searchReplace operations (same params as previewEdit). Does NOT write to disk.

Inputs: filePath (required), operation (required), transactionId (required), search, +6 more.

startDebuggingA

Start debug session from .vscode/launch.json. Pass configName to select configuration.

Inputs: configName.

stopDebuggingA

Stop active debug session. No-op if none running.

testTraceToSourceA
Read-only

Map a test pattern to covered source lines from lcov.info or coverage-summary.json — no instrumentation needed. Without per-test coverage, returns whole-suite coverage filtered by filename pattern.

Inputs: testPattern (required), coverageDir, minCoverage.

unwatchFilesA

Stop watching files for a previously registered watcher by ID.

Inputs: id (required).

updateLinearIssueA

Update an existing Linear issue. Pass only the fields you want to change. Requires Linear connector connected.

Inputs: id (required), state, title, assignee, +3 more.

updatePlanA
Idempotent

Update plan file: mark tasks done/undone, add tasks or sections.

Inputs: addTasks, fileName, addSections, markComplete, +1 more.

waitForTerminalOutputA
Read-only

Block until regex matches terminal output. Returns {matched, matchedLine, elapsed} or timedOut.

Inputs: pattern (required), name, index, timeout.

watchActivityLogA
Read-only

Long-poll for new activity log entries. Pass lastId as sinceId on next call.

Inputs: sinceId, timeoutMs, maxEntries.

watchDiagnosticsA
Read-only

Long-poll for diagnostic changes. Use after edits to wait for LSP re-validation.

Inputs: filePath, timeoutMs, sinceTimestamp.

watchFilesA
Read-only

Watch glob pattern for file changes (created/modified/deleted). Use unwatchFiles to stop.

Inputs: id (required), pattern (required).

writeClipboardA
Idempotent

Write text to system clipboard. Max 1 MB.

Inputs: text (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 178 tools

    Disambiguation2/5

    Several tool families overlap heavily: hover has getHover, getHoverAtCursor, getTypeSignature, and batchGetHover; navigation has goToDefinition, batchGoToDefinition, and navigateToSymbolByName; execution has runCommand, runInTerminal, and sendTerminalCommand. Descriptions add detail, but across 178 tools the boundaries remain fuzzy enough to cause frequent misselection.

    Naming Consistency3/5

    Names are consistently camelCase, but the set mixes verb_noun (getGitStatus), noun-only (foldingRanges, contextBundle), prefix families (ctx*, butler*, batch*), and synonyms (get/fetch/list/search). It is readable, but not a predictable single convention across the whole server.

    Tool Count1/5

    178 tools is an extreme overload for any single MCP server, far beyond the typical 3-15 range. The count alone makes discovery, selection, and maintenance impractical, even if many tools are individually useful.

    Completeness3/5

    The server covers a broad IDE/bridge/connector surface, but there are notable lifecycle gaps. For example, getPRTemplate references githubCreatePR, which is absent; git merge/rebase/tag/delete-branch are missing; and GitHub issue create/update/comment are absent despite Linear CRUD support.

    Maintenance

    ActivityActive
    ResponsivenessUsually handled

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Exposes any stdio-based MCP server to the internet via HTTP/SSE transport, enabling remote agents to access MCP tools over a network.
      27 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      This server bridges a stdio MCP server to HTTP, allowing MCP clients that communicate over HTTP to use the server's tools. It includes a per-tool allow/deny filter for security.
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Minimal MCP server allowing Python functions to be served as MCP tools over stdio or HTTP, with a built-in client for connecting to MCP servers.
      135 PyPI
      2
      Apache 2.0