microsoft · Oz Zafar (ozzafar) · Sep 17, 2026 · Sep 16, 2026 · Sep 16, 2026 · Sep 16, 2026
diff --git a/.gitignore b/.gitignore
@@ -421,4 +421,7 @@ FodyWeavers.xsd
 node_modules/*
 out/*
 dist/*
-.vscode-test/*
+.vscode-test/*
+*.tgz
+npm/cli/LICENSE.txt
+npm/cli/dist/
diff --git a/README.md b/README.md
@@ -4,9 +4,18 @@ Let AI agents debug your code inside VS Code - set breakpoints, step through exe
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![VS Code](https://img.shields.io/badge/VS%20Code-1.104.0+-blue.svg)](https://code.visualstudio.com/)
-[![Version](https://img.shields.io/badge/version-2.3.7-green.svg)](https://github.com/microsoft/DebugMCP)
+[![Version](https://img.shields.io/badge/version-2.4.0-green.svg)](https://github.com/microsoft/DebugMCP)
 [![VS Marketplace](https://img.shields.io/badge/VS%20Marketplace-Install-blue.svg)](https://marketplace.visualstudio.com/items?itemName=ozzafar.debugmcpextension)
 
+
+> 🚀 **DebugMCP CLI is now available on npm!** Debug directly from the
+> terminal **without requiring VS Code or any IDE at all** by connecting AI
+> coding agents to explicitly configured Debug Adapter Protocol (DAP) adapters.
+> The debug adapter and target process **run in the background**. Install it with
+> `npm install --global debugmcp`, then run
+> `debugmcp configure --agent copilot-cli`. The CLI also installs the
+> `debug-live` skill automatically. **[View the package on npm](https://www.npmjs.com/package/debugmcp)**
+
 > ⭐ **If you find DebugMCP useful, please [star the repo on GitHub](https://github.com/microsoft/DebugMCP)!** It helps others discover the project and motivates continued development.
 
 > **📢 Developers Notice**: This extension is maintained by [ozzafar@microsoft.com](mailto:ozzafar@microsoft.com) and [orbarila@microsoft.com](mailto:orbarila@microsoft.com). We welcome feedback and contributions to help improve this extension.
@@ -19,6 +28,9 @@ Let AI agents debug your code inside VS Code - set breakpoints, step through exe
 
 ## ✨ What's New
 
+### 2.4
+- **Standalone DebugMCP CLI** — install [`debugmcp`](https://www.npmjs.com/package/debugmcp) from npm and give MCP-compatible agents direct access to explicitly configured DAP adapters without running VS Code. The CLI supports any language with a DAP adapter that communicates over stdio, configures supported agents, and installs the `debug-live` skill automatically.
+
 ### 2.2
 - **Cross-agent `debug-live` skill install** — the systematic debugging workflow ships as an [Agent Skill](https://agentskills.io) and is now installed into the **standard skills directories** — `~/.agents/skills/` (the cross-agent location honored by skills-compatible harnesses, including VS Code agent mode) and `~/.copilot/skills/` when present — so it's discoverable everywhere instead of being copied next to each agent's config where nothing scans it (fixes [#105](https://github.com/microsoft/DebugMCP/issues/105), where VS Code never loaded the skill). The server also advertises MCP `instructions` and the `start_debugging` tool points at the skill for the full workflow.
 - **Pause running programs** — new `pause_execution` tool interrupts a freely-running program and stops at its current location, even with no breakpoint set (great for busy loops and embedded/bare-metal targets), so you can then inspect state or step from there.
@@ -92,6 +104,68 @@ DebugMCP follows systematic debugging practices for effective issue resolution:
 
 ## Installation
 
+### Standalone CLI (preview)
+
+The standalone host talks directly to explicitly configured DAP adapters and
+does not require VS Code. It never discovers, downloads, installs, or selects an
+adapter automatically.
+
+Install the published package:
+
+```console
+npm install --global debugmcp
+```
+
+For repository development, build and invoke the local bundle:
+
+```console
+npm install
+npm run package
+node dist/debugmcp.js adapter add python --command "python -m debugpy.adapter"
+node dist/debugmcp.js adapter validate python
+node dist/debugmcp.js configure
+```
+
+Adapter registrations are stored in `.debugmcp.json` by default. Add `--user`
+to `adapter add`, `adapter list`, or `adapter remove` to use the per-user
+configuration. Project registrations override registrations with the same name
+in user configuration.
+
+Language shorthands derive the DAP type and file extensions for `python`,
+`csharp`, `dotnet`, `cpp`, `c`, `javascript`, `typescript`, `node`, `java`,
+`go`, `rust`, `ruby`, `php`, `swift`, and `dart`. These are configuration
+conveniences, not a language support boundary. The command remains explicit so
+the selected environment determines which adapter installation is used.
+Languages without a shorthand provide `--type` and `--extensions` explicitly.
+Compiled-language registrations can provide the executable in `--launch`;
+values support `${workspaceFolder}`, `${file}`, `${fileDirname}`, and
+`${fileBasenameNoExtension}`.
+
+The current CLI supports adapters that speak DAP over stdio. A registration can
+provide adapter-specific launch properties with `--launch` followed by a JSON
+object. If multiple registered adapters claim the same file extension,
+`start_debugging.configurationName` must identify the adapter to use. Test
+discovery remains host-specific; configure the adapter launch properties to run
+the required test command.
+
+Adapter arguments beginning with `--` can follow `--args` directly. Use a
+standalone `--` after `--args` when an adapter argument has the same name as a
+DebugMCP option, for example `--args -- --user`.
+
+`debugmcp configure` presents the same agent choices as the VS Code extension's
+setup popup and writes the standalone stdio command for every selected agent.
+In automation, repeat `--agent <id>` to bypass the terminal prompt, for example
+`debugmcp configure --agent copilot-cli --agent codex`. Each configuration has
+one canonical `debugmcp` entry, so configuring the CLI replaces an existing
+extension HTTP entry rather than registering both.
+The command also installs the bundled `debug-live` skill into the standard
+personal skills directories. Restart configured agents to discover it.
+
+Use `debugmcp status` to inspect the GitHub Copilot CLI registration. The
+DebugMCP command configures only the standalone CLI. To use the interactive
+VS Code version, configure it through the DebugMCP extension's agent popup;
+the command line does not select or configure the extension.
+
 ### Quick Install Options
 
 **Option 1: Direct Link** (Fastest)
@@ -519,5 +593,3 @@ If DebugMCP has helped you debug faster, please consider giving it a star on Git
 ## License
 
 MIT License - See [LICENSE](LICENSE.txt) for details
-
-This extension was created by **Oz Zafar**, **Ori Bar-Ilan** and **Karin Brisker**.
diff --git a/docs/architecture/agentConfigurationManager.md b/docs/architecture/agentConfigurationManager.md
@@ -95,7 +95,12 @@ The `debug-live` Agent Skill is installed into the **standard personal skills di
 - **`~/.agents/skills/debug-live/`** — the cross-agent location honored by skills-compatible harnesses, including VS Code agent mode and Copilot CLI. Always installed.
 - **`~/.copilot/skills/debug-live/`** — Copilot's own skills path; also installed when a Copilot home directory (`~/.copilot`, or `$COPILOT_HOME`) exists.
 
-`installDebugMCPSkill()` copies the one bundled source (`skills/debug-live/SKILL.md`) into each target with `force: true` (idempotent refresh) and removes stale legacy copies (`debug`, `really-debug`). It is agent-independent — a single shared install covers every skills-compatible harness.
+The shared installer in `src/utils/debugSkillInstaller.ts` copies the one bundled
+source (`skills/debug-live/`) into each target with `force: true` (idempotent
+refresh) and removes stale legacy copies (`debug`, `really-debug`). Both the VS
+Code extension and standalone CLI use this installer. The npm package includes
+the complete skill tree, and `debugmcp configure` installs it while registering
+the selected agents.
 
 This fixes issue #105: earlier builds copied the skill next to each agent's config (e.g. `Code/User/skills/` for VS Code Copilot), a directory no harness scans, so the skill never loaded. Installing to `~/.agents/skills/` — which VS Code agent mode does scan — makes it discoverable.
 
@@ -104,7 +109,9 @@ This fixes issue #105: earlier builds copied the skill next to each agent's conf
 - Class definition: `src/utils/agentConfigurationManager.ts`
 - Agent definitions: `getSupportedAgents()`
 - Config writing: `addDebugMCPToAgent()`
-- Skill install: `installDebugMCPSkill()` / `getSkillInstallTargets()` / `ensureSkillRegistered()`
+- Shared skill install: `src/utils/debugSkillInstaller.ts`
+- Extension skill orchestration: `installDebugMCPSkill()` / `ensureSkillRegistered()`
+- Standalone skill orchestration: `src/cli/main.ts` (`configureAgents()`)
 - Codex TOML upsert: `upsertCodexDebugMCPConfig()`
 - Path detection: `getConfigBasePath()`
 - Popup logic: `shouldShowPopup()`, `showAgentSelectionPopup()`

diff --git a/docs/architecture/debugConfigurationManager.md b/docs/architecture/debugConfigurationManager.md
@@ -4,6 +4,10 @@
 
 Produces the argument passed to `vscode.debug.startDebugging()` — either a launch.json configuration name or a minimal `DebugConfiguration` stub.
 
+The standalone counterpart, `src/cli/cliConfigurationManager.ts`, resolves an
+explicit adapter registration from project or user configuration and produces
+the DAP launch/attach arguments. It intentionally has no default adapters.
+
 ## Motivation
 
 Earlier versions of this class manually parsed `launch.json`, scored configurations, and assembled fully populated per-language config objects. That duplicated work VS Code and the language debug extensions already do better:
@@ -25,6 +29,14 @@ Delegating to those mechanisms keeps this class small and ensures defaults stay
 
 ## Key Concepts
 
+### Standalone adapter selection
+
+The CLI merges user registrations with `.debugmcp.json`, with project entries
+overriding user entries of the same name. It selects the sole adapter claiming
+the source extension, or the adapter named by `configurationName`. Missing and
+ambiguous registrations fail with configuration commands instead of triggering
+environment discovery or installation.
+
 ### Return type
 
 `getDebugConfig()` returns `string | vscode.DebugConfiguration`. Both forms are accepted by `vscode.debug.startDebugging(folder, nameOrConfiguration)`.

diff --git a/docs/architecture/debugMCPServer.md b/docs/architecture/debugMCPServer.md
@@ -2,11 +2,15 @@
 
 ## Purpose
 
-The MCP server component that exposes VS Code debugging capabilities to AI agents via the Model Context Protocol. This is the main entry point for all external AI agent communication.
+The MCP server component that exposes debugging capabilities to AI agents via
+the Model Context Protocol. It is shared by the VS Code extension and the
+standalone CLI.
 
 ## Motivation
 
-AI coding agents need a standardized way to control debuggers programmatically. MCP provides this standard, and `DebugMCPServer` implements it using the official `@modelcontextprotocol/sdk` with Streamable HTTP transport over an express HTTP server.
+AI coding agents need a standardized way to control debuggers programmatically.
+MCP provides this standard, and `DebugMCPServer` implements it using the official
+`@modelcontextprotocol/sdk` with Streamable HTTP and stdio transports.
 
 ## Responsibility
 
@@ -15,16 +19,17 @@ AI coding agents need a standardized way to control debuggers programmatically.
 - Register documentation resources for agent guidance
 - Delegate all debugging operations to `DebuggingHandler`
 - Manage Streamable HTTP transport via `StreamableHTTPServerTransport` on configurable port (default: 3001)
+- Manage `StdioServerTransport` when launched by the standalone CLI
 
 ## Architecture Position
 
 ```
 AI Agent (MCP Client)
-        │
-        ▼ HTTP POST /mcp
+        │ HTTP or stdio
+        ▼
 ┌───────────────────┐
 │  DebugMCPServer   │  ◄── You are here
-│ (express + HTTP)  │
+│   (MCP transport) │
 └───────────────────┘
         │
         ▼ Delegates to
@@ -35,6 +40,14 @@ AI Agent (MCP Client)
 
 ## Key Concepts
 
+### Standalone CLI
+
+`src/cli/main.ts` starts this server without loading the VS Code module. It
+injects a `CliDebuggingExecutor` and `CliConfigurationManager` for each MCP
+session. The CLI can use stdio or the same loopback Streamable HTTP endpoint.
+Unlike the extension host, it requires an explicit adapter registration and
+does not use window routing.
+
 ### Multi-window routing (multiple VS Code windows / repos)
 
 The MCP endpoint uses a fixed port, but every open VS Code window activates the

diff --git a/docs/architecture/debuggingExecutor.md b/docs/architecture/debuggingExecutor.md
@@ -2,7 +2,9 @@
 
 ## Purpose
 
-Low-level wrapper around VS Code's Debug API and Debug Adapter Protocol (DAP). Executes actual debugging commands and retrieves debug state.
+Host abstraction for executing debugging commands and retrieving debug state.
+The VS Code implementation wraps the editor Debug API, while the standalone CLI
+implementation hosts a debug adapter directly over DAP stdio.
 
 ## Motivation
 
@@ -31,11 +33,25 @@ VS Code's debug API is powerful but requires careful handling. `DebuggingExecuto
         │
         ▼ Calls
 ┌───────────────────┐
-│  VS Code Debug API │
-│  (DAP Protocol)    │
+│ VS Code Debug API │
+│ or CLI DAP Client │
 └───────────────────┘
 ```
 
+### Standalone CLI host
+
+`src/cli/cliDebuggingExecutor.ts` implements the same executor interface without
+VS Code. It starts an explicitly registered adapter, performs the DAP
+initialize/launch/configuration sequence, handles adapter events and
+`runInTerminal`, and owns session, thread, frame, and breakpoint state.
+Step operations wait for a fresh stopped or terminated event. Continue allows a
+short stop-event grace period so immediately reached breakpoints are reported,
+while still returning promptly for long-running programs.
+Closing an MCP session disposes its standalone executor, adapter process, and
+any debuggee processes started through reverse `runInTerminal` requests.
+`src/cli/adapterConfig.ts` loads project and user registrations. No adapter is
+registered, discovered, selected, installed, or upgraded implicitly.
+
 ## Key Concepts
 
 ### Startup Failure Diagnostics

diff --git a/docs/architecture/debuggingHandler.md b/docs/architecture/debuggingHandler.md
@@ -2,7 +2,9 @@
 
 ## Purpose
 
-High-level orchestration layer that coordinates debugging operations between the MCP server and VS Code's debug API. Handles the asynchronous nature of debugging by implementing state change detection.
+Host-neutral orchestration layer that coordinates debugging operations between
+the MCP server and an injected executor. The executor may use VS Code's debug
+API or host a DAP adapter directly in the standalone CLI.
 
 ## Motivation
 
@@ -48,7 +50,10 @@ After executing a debug command (step over, continue, etc.), the handler:
 
 ### Exponential Backoff
 
-Polling starts at 1 second intervals and increases exponentially (capped at 10 seconds for session activation, 1 second for state changes). Jitter is added to prevent thundering herd issues.
+State-change polling uses short bounded intervals so either executor can expose
+new stopped/running state without the handler depending on host-specific event
+APIs. Session activation remains delegated to the executor, which can use its
+native VS Code or DAP events.
 
 ### Meaningful State Changes
 

diff --git a/esbuild.js b/esbuild.js
@@ -30,7 +30,7 @@ const esbuildProblemMatcherPlugin = {
 };
 
 async function main() {
-	const ctx = await esbuild.context({
+	const extensionCtx = await esbuild.context({
 		entryPoints: ['src/extension.ts'],
 		bundle: true,
 		format: 'cjs',
@@ -43,11 +43,23 @@ async function main() {
 		logLevel: 'silent',
 		plugins: [esbuildProblemMatcherPlugin],
 	});
+	const cliCtx = await esbuild.context({
+		entryPoints: ['src/cli/main.ts'],
+		bundle: true,
+		format: 'cjs',
+		minify: production,
+		sourcemap: !production,
+		sourcesContent: false,
+		platform: 'node',
+		outfile: 'dist/debugmcp.js',
+		logLevel: 'silent',
+		plugins: [esbuildProblemMatcherPlugin],
+	});
 	if (watch) {
-		await ctx.watch();
+		await Promise.all([extensionCtx.watch(), cliCtx.watch()]);
 	} else {
-		await ctx.rebuild();
-		await ctx.dispose();
+		await Promise.all([extensionCtx.rebuild(), cliCtx.rebuild()]);
+		await Promise.all([extensionCtx.dispose(), cliCtx.dispose()]);
 	}
 }
 

diff --git a/npm/cli/README.md b/npm/cli/README.md
@@ -0,0 +1,40 @@
+# DebugMCP CLI
+
+DebugMCP CLI lets MCP-capable coding agents control language debuggers without
+running VS Code. It communicates with explicitly configured Debug Adapter
+Protocol (DAP) adapters over stdio, supporting any language for which such an
+adapter is available.
+
+## Install
+
+```console
+npm install --global debugmcp
+```
+
+## Configure an agent
+
+Configure GitHub Copilot CLI once:
+
+```console
+debugmcp configure --agent copilot-cli
+```
+
+This also installs the bundled `debug-live` skill into the standard personal
+skills directories. Restart the agent after configuration so it discovers the
+skill.
+
+## Configure a project
+
+DebugMCP does not discover, install, or choose debugger installations. Register
+the adapter provided by the project's environment:
+
+```console
+cd path\to\python-project
+debugmcp adapter add python --command "python -m debugpy.adapter"
+debugmcp adapter validate python
+```
+
+The project registration is stored in `.debugmcp.json`. Start the configured
+agent from that project and ask it to use the `debug-live` skill.
+
+Use `debugmcp help` for all commands.