Arc - Terminal Bridge for AI Agents
Arc connects AI coding agents to VS Code terminals via the Model Context Protocol (MCP). It gives agents like Claude Code, Codex, and others the ability to create, execute, and monitor terminal sessions with full output capture.
Features
- Full Output Capture — Execute commands and get the complete stdout/stderr output back, not just fire-and-forget
- Shell Integration — Leverages VS Code's shell integration for reliable exit codes and streaming output
- 11 MCP Tools — Create, execute, send, focus, kill, list, observe, and monitor terminals
- TUI Auto-Detection — Automatically handles interactive apps (Codex, Claude, Gemini) with smart Enter key injection
- Pattern Matching — Set up regex watchers on terminals and get notifications when patterns match
- Zero Dependencies — Uses Node's built-in
http module for the internal bridge server
Architecture
AI Agent ←stdio→ MCP Server ←HTTP:3850→ VS Code Extension ←API→ Terminals
Arc consists of two components bundled together:
- VS Code Extension (
extension.js) — Manages terminals and runs an HTTP server on port 3850
- MCP Server (
mcp-server.mjs) — Translates MCP tool calls into HTTP requests to the extension
| Tool |
Description |
arc_terminal_create |
Create a new terminal with ID, name, working directory |
arc_terminal_execute |
Run a command with full output capture and exit code |
arc_terminal_send |
Send text to a terminal (for TUI apps and interactive use) |
arc_terminal_focus |
Bring a terminal tab to the front |
arc_terminal_kill |
Close and dispose a terminal |
arc_terminal_list |
List all terminals (managed, unmanaged, or all) |
arc_terminal_get_output |
Retrieve the last N lines from a terminal's output buffer |
arc_terminal_observe |
Watch for regex patterns in terminal output |
arc_terminal_exists |
Check if a terminal ID exists |
arc_terminal_health |
Verify the extension is running |
arc_execution_status |
Check status of a running or completed execution |
Setup with Claude Code
- Install the Arc extension from the VS Code Marketplace
- Register the MCP server with Claude Code:
claude mcp add --transport stdio --scope user arc -- \
node ~/.vscode/extensions/mercurial.arc-0.3.0/mcp-server.mjs
- Verify it's working:
claude mcp list
Arc tools will appear as arc_terminal_* in Claude Code's tool list.
Usage Examples
Execute a command and capture output
The AI agent calls arc_terminal_execute:
{
"id": "build",
"command": "npm run build"
}
Returns the full output, exit code, and duration.
Send to a TUI app
For interactive agents like Codex or Gemini:
{
"id": "codex",
"command": "fix the bug in auth.js",
"autoEnter": true
}
Watch for patterns
{
"id": "build",
"patterns": [
{ "regex": "ERROR", "name": "error" },
{ "regex": "Build complete", "name": "done" }
]
}
Requirements
Extension Commands
| Command |
Description |
Arc: List Managed Terminals |
Show all Arc-managed terminals |
Arc: Start HTTP Server |
Manually start the bridge server |
Arc: Stop HTTP Server |
Stop the bridge server |
Arc: Create New Terminal |
Create a terminal via input dialog |
How It Works
When VS Code starts, Arc activates and launches an HTTP server on 127.0.0.1:3850. The MCP server (mcp-server.mjs) runs as a stdio process that Claude Code communicates with directly. MCP tool calls are translated into HTTP requests to the extension, which uses the VS Code Terminal API to manage terminals.
Shell integration enables the key differentiator: full output capture with exit codes. Without shell integration, Arc falls back to sendText (fire-and-forget mode).
License
MIT
