<div align="right">

**English** | [简体中文](README.zh-CN.md)

</div>

# BlackHole

**BlackHole is a local MCP bridge that gives web-based AI agents controlled access to your local development workspace.**

Remote agents connect through MCP Streamable HTTP and can inspect files, edit code, and run commands using a deliberately small tool surface. Every workspace operation is scoped to a session, while destructive, high-risk, or out-of-bound actions are held for explicit human approval.

```text
Web AI (ChatGPT / other MCP-capable agents)
        ↕ MCP Streamable HTTP
Persistent or quick tunnel
        ↓
BlackHole daemon (localhost only)
        ↓
Your local workspace
```

## Why BlackHole?

BlackHole is designed for a simple use case: let a remote AI agent do real development work on your machine **without giving it unrestricted machine access**.

- **Local execution** — your real shell, repository, dependencies, and developer tools stay on your machine.
- **Workspace boundaries** — file operations are constrained to the selected workspace.
- **Human approval gates** — risky or destructive shell operations pause until you approve or deny them.
- **Persistent sessions** — sessions, tool calls, todos, events, and approvals survive reconnects.
- **Small MCP surface** — agents primarily work through `pwsh` and `workspace_editor`, with optional semantic code search.
- **VS Code integration** — create and manage sessions, inspect calls, and approve operations from the sidebar.
- **MCP Apps panel** — supported hosts can render live task progress and tool activity directly in the conversation.

## Quick Start

### From source

```bash
pnpm install
pnpm build
pnpm start
```

The daemon listens on `127.0.0.1:7306` by default.

Create a session for a project:

```bash
node dist/cli.js create D:/path/to/project --copy prompt
```

Check tunnel status:

```bash
node dist/cli.js tunnel
```

BlackHole does **not** automatically expose the daemon publicly. Start a public channel only when you need one:

```bash
# Persistent named tunnel (recommended)
# Set BLACKHOLE_PUBLIC_URL to your stable public URL first.
node dist/cli.js tunnel start named

# Temporary Cloudflare Quick Tunnel
node dist/cli.js tunnel start quick

# Stop the active tunnel
node dist/cli.js tunnel stop
```

## VS Code Extension

The VS Code extension in [`packages/vscode`](packages/vscode) is the recommended user-facing entry point. It provides:

- session creation and management;
- connector and sandbox prompt generation;
- live tool-call history;
- task progress;
- human approval UI for risky commands;
- daemon start / attach / stop / restart controls;
- public-channel management.

The extension launches the daemon using VS Code's bundled Electron runtime (`ELECTRON_RUN_AS_NODE`), so end users do not need to install Node.js separately.

Build or package the extension:

```bash
pnpm --filter blackhole-vscode build
pnpm --filter blackhole-vscode package
```

## MCP Tools

### `pwsh`

A persistent PowerShell session. The working directory, environment, and shell state survive across calls. High-risk operations are blocked until explicitly approved.

On Windows, the shell also runs under an ACL-restricted token so writes outside the workspace and the session-private temp directory can be rejected by the OS itself.

### `workspace_editor`

Purpose-built workspace file operations:

```text
view / create / str_replace / insert / delete
```

Paths are guarded and constrained to the active workspace.

### `context_search` (optional)

Semantic code navigation for questions such as:

> Where is uploaded content validated before it is sent?

It returns relevant files, line ranges, and code excerpts. The tool is registered only when a supported semantic-search credential is available.

Unlike the core local tools, `context_search` may send workspace paths and code excerpts to the configured Devin/Windsurf endpoint. It is therefore opt-in and absent from the MCP tool list when no credential is configured.

### `guide`

Returns the BlackHole operating rules that tell the agent how to use the workspace tools, approval model, task contract, and verification workflow.

### `show`

For hosts with MCP Apps support, `show` mounts the live BlackHole session panel for the current conversation round.

## Human Approval Model

BlackHole separates ordinary development work from operations that deserve human attention.

In the default `workspace-write` mode:

- normal workspace reads and edits proceed automatically;
- destructive, system-level, security-sensitive, or out-of-scope commands pause for approval;
- approval resumes the blocked call rather than asking the agent to retry it;
- denied operations fail without execution.

A session can also run in `read-only` mode, which rejects mutations entirely.

Approval decisions can be made through the local VS Code / CLI control plane or, for supported MCP Apps hosts, through the embedded session panel.

## Security Model

BlackHole uses multiple boundaries rather than relying on a single prompt-level instruction.

### Workspace boundary

`workspace_editor` guards paths against traversal, symlink, and realpath escapes.

### Shell policy boundary

Potentially dangerous commands are classified and held behind an approval gate.

### Windows kernel boundary

On Windows, shell processes use a restricted ACL token. Approval does not disable this restriction: even an approved command cannot write outside locations granted to the sandbox token.

> macOS and Linux currently rely on the policy layer and workspace/editor guards; they do not yet have an equivalent kernel-level write sandbox.

### Session credentials

Sessions use opaque numeric credentials. Rotating a credential invalidates the previous one while preserving the session state; revoking a session terminates access.

### External data flow

The core workspace and shell tools execute locally. The optional `context_search` capability is the exception: it can send repository paths and code excerpts to a configured third-party semantic-search endpoint.

## MCP Apps Session Panel

BlackHole includes an experimental MCP Apps UI for compatible hosts.

Calling `show` mounts a lightweight session panel that can display:

- current task / todo progress;
- tool calls from the active round;
- call status and durations;
- workspace edit deltas;
- pending approval actions.

The UI template uses the stable resource URI:

```text
ui://blackhole/panel.html
```

Per-session routing data is delivered separately in the `show` result. A new `show` call creates a new panel capability and invalidates the previous panel for that session.

Hosts without MCP Apps support simply ignore the UI metadata; the MCP tools continue to work normally.

## CLI

| Command | Description |
|---|---|
| `serve [--port N] [--db PATH]` | Start the daemon in the foreground |
| `create <workspace> [--mode workspace-write\|read-only] [--name <task>] [--copy url\|prompt]` | Create a workspace session |
| `ls / show <id>` | List or inspect sessions |
| `pause \| resume \| revoke \| rotate <id>` | Manage session lifecycle and credentials |
| `events <id> / calls <id>` | Inspect events and tool calls |
| `confirmations / approve \| deny <id>` | Manage pending approvals |
| `semantic [<KEY>\|clear]` | Inspect, set, or clear semantic-search credentials |
| `tunnel` | Inspect public-channel status |

## Configuration

Common environment variables:

| Variable | Default | Description |
|---|---|---|
| `BLACKHOLE_PORT` | `7306` | Loopback daemon port |
| `BLACKHOLE_DB` | `~/.blackhole/blackhole.db` | SQLite state database |
| `BLACKHOLE_TUNNEL_NAME` | `blackhole` | Cloudflare named tunnel name |
| `BLACKHOLE_PUBLIC_URL` | unset | Stable public URL for a named tunnel / reverse proxy |
| `BLACKHOLE_CLOUDFLARED` | `cloudflared` | cloudflared executable |
| `BLACKHOLE_BASH` | auto-detected | Bash executable fallback |
| `BLACKHOLE_EXEC_TIMEOUT_MS` | `120000` | Per-command timeout |
| `BLACKHOLE_GIT_USR_BIN` | unset | Optional GNU tool directory for the shell PATH |
| `BLACKHOLE_SEMANTIC` | `explicit` | Semantic credential policy: `off`, `explicit`, or `auto` |
| `BLACKHOLE_SEMANTIC_KEY` | unset | Devin/Windsurf API key |
| `BLACKHOLE_SEMANTIC_TIMEOUT_MS` | `120000` | `context_search` timeout |

## Development & Verification

Build:

```bash
pnpm build
```

Run the end-to-end smoke suite:

```bash
pnpm smoke
```

Verify prompt contracts:

```bash
pnpm verify:prompts
```

The repository also contains focused tunnel, semantic-search, sandbox, and VS Code webview checks under [`scripts/`](scripts).

## Project Structure

```text
src/                    daemon, MCP tools, storage, sandbox, panel
packages/vscode/        VS Code extension
client/                  lightweight client/bootstrap code
scripts/                 smoke tests and verification utilities
docs/                    implementation and extension design notes
web-agents/              web-agent integration assets
```

## Documentation

- [VS Code extension design](docs/vscode-extension.md)
- [Implementation notes](docs/implementation.md)
- [简体中文 README](README.zh-CN.md)

## Status

BlackHole is under active development. The daemon, persistent sessions, approval flow, VS Code extension, tunnel lifecycle, optional semantic search, and MCP Apps session panel are implemented, but interfaces may still evolve before a stable public release.

> `src/index.js` is a first-generation prototype. The current daemon implementation is based on `src/daemon.ts` and `dist/cli.js`.