Forge

Why

AI coding agents (Claude Code, Codex, etc.) typically run one command at a time. Forge gives them persistent terminals — run your React frontend, Java API, and Postgres migrations in parallel, monitor all three, and only read what changed. Full-stack work without the bottleneck.

Works with any MCP-compatible client — Claude Code, Codex, or your own agent.

Key differentiators:

• Real PTY via node-pty (same lib as VS Code terminal) — interactive programs, colors, TUI apps all work

• Incremental reads — ring buffer with per-consumer cursors means each read_terminal only returns NEW output, saving context window tokens

• Clean screen reads — @xterm/headless renders the terminal server-side, so read_screen returns exactly what a human would see (no ANSI escape codes)

• Multi-agent orchestration — spawn Claude and Codex sub-agents, session groups, output multiplexing, event subscriptions, and templates for managing multiple concurrent sessions

• Web dashboard — real-time Preact-based browser UI to watch what your agents are doing across all terminals, browse past chat sessions, and monitor activity

• Zero config — single npx command or HTTP MCP endpoint

Quick Start

1. Add to Your Agent

# Basic (stdio)
claude mcp add forge -- npx forge-terminal-mcp

# With web dashboard
claude mcp add forge -- npx forge-terminal-mcp --dashboard --port 3141

Or add to ~/.claude/settings.json:

{
  "mcpServers": {
    "forge": {
      "command": "npx",
      "args": ["forge-terminal-mcp", "--dashboard", "--port", "3141"]
    }
  }
}

# Add Forge as HTTP MCP server
codex mcp add forge --url http://127.0.0.1:3141/mcp

# Verify
codex mcp list
codex mcp get forge

Codex stores this in ~/.codex/config.toml:

[mcp_servers.forge]
url = "http://127.0.0.1:3141/mcp"

Start the daemon (choose one launch mode), then point any MCP client at the HTTP endpoint:

# If forge is on PATH (global install or npm link)
forge start -d

# From this repo (local clone)
node dist/cli.js start -d

# Without install (published package)
npx forge-terminal-mcp start -d

{
  "mcpServers": {
    "forge": {
      "type": "http",
      "url": "http://127.0.0.1:3141/mcp"
    }
  }
}

Restart your agent and Forge tools are available.

Important: Codex and Claude Code load MCP servers at process start. If you add/remove servers, restart the current agent session.

2. Smoke Test (60s)

# Codex MCP registration
codex mcp list
codex mcp get forge

# Forge daemon status
node dist/cli.js status

Expected:

• codex mcp list shows forge as enabled

• node dist/cli.js status reports running and http://127.0.0.1:3141

Troubleshooting

3. Use It

Your agent now has access to 23 tools across 7 categories:

Session Lifecycle

create_terminal      → Spawn a PTY session with optional name, tags, buffer size
create_from_template → Spawn from a built-in template (shell, next-dev, vite-dev, etc.)
spawn_claude         → Launch a Claude Code sub-agent in a dedicated session
spawn_codex          → Launch a Codex sub-agent in a dedicated session
close_terminal       → Kill a session and free resources
close_group          → Close all sessions matching a tag
list_terminals       → List sessions, optionally filtered by tag
list_templates       → Show available session templates

I/O

write_terminal       → Send input (appends newline by default)
read_terminal        → Read NEW output since last read (incremental)
read_screen          → Get rendered viewport as clean text (no ANSI)
read_multiple        → Batch read from up to 20 sessions at once
send_control         → Send Ctrl+C, arrow keys, Tab, Enter, etc.
resize_terminal      → Change terminal dimensions

Search & Wait

grep_terminal        → Regex search across a session's output buffer
wait_for             → Block until output matches a pattern or process exits

Execution

run_command          → Run a command to completion, return output, auto-cleanup

Events

subscribe_events     → Get notified when a session exits or matches a pattern
unsubscribe_events   → Cancel an event subscription

Agent Delegation

delegate_task        → Delegate a task to another agent — oneshot or interactive multi-turn

Ops

health_check         → Server version, uptime, session count, memory usage
get_session_history  → Tool call history for agent sessions
clear_history        → Clear persisted stale session entries

Example Conversations

You: Start a Next.js dev server and run the test suite in parallel

Agent: (uses

You: Spin up 3 sub-agents to research different parts of the codebase

Agent: (uses

You: Build and test, just give me the result

Agent: (uses

Tools Reference

create_terminal

Returns session info including the id used by all other tools.

create_from_template

Built-in templates:

Templates with waitFor automatically block until the pattern appears (30s timeout).

spawn_claude

run_command

Creates a terminal, waits for the process to exit, returns all output, and auto-cleans up the session. Ideal for build/test/install commands.

write_terminal

read_terminal

Returns { status, data, bytes, droppedBytes? }. Only returns output produced since the last read. If droppedBytes > 0, some output was lost because the ring buffer wrapped.

read_screen

Returns the current terminal viewport as plain text — rendered through a headless xterm instance. No ANSI codes. Useful for TUI apps like htop, vim, or interactive prompts.

read_multiple

Returns a JSON array with per-session results. Sessions that error (e.g., not found) include an inline error field — the tool never fails as a whole, so partial results are always returned.

grep_terminal

Returns { matches: [{ lineNumber, text, context? }], totalMatches }.

wait_for

Checks the existing buffer first (instant match if pattern already appeared), then watches new output. Returns { matched, data?, reason?, elapsed }.

subscribe_events

Notifications are delivered as MCP logging messages with JSON payloads. Pattern match subscriptions auto-unsubscribe after the first match.

unsubscribe_events

list_terminals

Returns all sessions with id, pid, command, cwd, status, cols, rows, createdAt, lastActivityAt, name, tags.

close_terminal

close_group

Closes all active sessions with the matching tag. Returns the count closed.

send_control

Available keys: ctrl+c, ctrl+d, ctrl+z, ctrl+\, ctrl+l, ctrl+a, ctrl+e, ctrl+k, ctrl+u, ctrl+w, ctrl+r, ctrl+p, ctrl+n, up, down, right, left, home, end, tab, enter, escape, backspace, delete, pageup, pagedown

resize_terminal

health_check

No parameters. Returns { version, uptime, sessions: { active, max }, memory: { rss, heapUsed, heapTotal } }.

get_session_history

Returns timestamped tool call history for agent sessions (Claude, Codex).

clear_history

No parameters. Clears persisted stale session entries from previous server runs.

MCP Resources

Sessions are also exposed as MCP resources at terminal://sessions/{sessionId}, returning session metadata and rendered screen content. The resource list updates automatically when sessions are created or closed.

Web Dashboard

Enable the real-time web dashboard to monitor all terminals from your browser:

{
  "mcpServers": {
    "forge": {
      "command": "npx",
      "args": ["forge-terminal-mcp", "--dashboard", "--port", "3141"]
    }
  }
}

Open http://localhost:3141 to see:

• Live terminal sessions with real-time output via WebSocket

• Session grouping — terminals organized by working directory

• Activity log — tool calls and events for agent sessions

• Status bar — working directory, session ID, running/exited status

• Chat history browser — search, browse, and continue past Claude Code and Codex conversations grouped by project

• Session management — create, close, and switch between terminals

• Auto-follow mode — automatically switch to newly created sessions

• Memory monitoring — per-session and total RAM usage

If --auth-token is enabled, open the dashboard with ?token=YOUR_TOKEN so browser API/WebSocket calls are authorized.

The dashboard is built with Preact + htm + Preact Signals, loaded from CDN with zero build step. All UI code is bundled as string constants inside the server binary.

Desktop App (macOS)

Forge includes an Electron-based desktop app for macOS with native window management, system tray, and notifications.

Running in Development

npm run build                    # Build forge core
cd desktop && npm install        # Install Electron deps
npx @electron/rebuild            # Rebuild node-pty for Electron
npm run dev                      # Launch the desktop app

Or from the repo root: npm run desktop:dev

Features

• Native macOS title bar with traffic light integration

• System tray with session count, new terminal, start-at-login toggle

• Close-to-tray (app keeps running when window closed)

• Native notifications on session created/exited

• Window state persistence across restarts

• Auto-detects existing CLI daemon — connects to it or starts in-process

• Security hardened: sandboxed renderer, navigation lock, CSP, permission deny-all

Packaging

cd desktop
npm run package          # Build DMG + ZIP

Produces a signed Forge.app in desktop/release/. Requires Apple Developer certificate for notarization (see desktop/forge.entitlements.plist).

Configuration

All settings follow the precedence: CLI flag > environment variable > default.

Example with custom config:

{
  "mcpServers": {
    "forge": {
      "command": "npx",
      "args": ["forge-terminal-mcp", "--max-sessions", "20", "--idle-timeout", "3600000", "--dashboard"]
    }
  }
}

Architecture

MCP Client   <--stdio-->  MCP Server (23 tools + 1 resource)
(Claude Code,    or
 Codex, etc) <--HTTP--->
                              |
                         SessionManager
                         (lifecycle, groups, persistence)
                              |
                    +---------+---------+
                    v         v         v
               TerminalSession    TerminalSession    ...
               +---------------+
               |   node-pty     |  <-- real PTY (colors, signals, TUI)
               |  RingBuffer    |  <-- 1 MB circular, per-consumer cursors
               | @xterm/headless|  <-- server-side rendering
               +---------------+
                              |
              +---------------+---------------+
              v               v               v
         MCP Client      Dashboard WS    Event Subs
         (incremental)   (live stream)   (notifications)

• Single Node.js process — MCP server communicates over stdio (JSON-RPC) or HTTP (streamable)

• All logging to stderr — stdout is reserved for the MCP protocol

• Ring buffer per session — 1 MB circular buffer with cursor-based reads. When the buffer fills, old data is overwritten and droppedBytes tells the consumer how much was lost

• Headless xterm per session — full terminal emulation server-side. read_screen returns the rendered viewport, correctly handling cursor positioning, alternate screen, line wrapping

• Idle timeout — sessions auto-close after 30 minutes of inactivity (configurable)

• Session persistence — session metadata saved to ~/.forge/sessions.json, reloaded as stale entries on restart

• Event system — subscribe to session exit or pattern match events, delivered as MCP logging messages

• Agent env stripping — spawned terminals have agent-specific env vars (e.g., CLAUDECODE) removed to prevent nesting errors

Development

git clone https://github.com/ferodrigop/forge-terminal-mcp.git
cd forge-terminal-mcp
npm install
npm run build       # Compile with tsup
npm test            # 161 tests (unit + integration)
npm run typecheck   # TypeScript strict mode
npm run lint        # ESLint
npm run dev         # Watch mode

Project Structure

src/
  cli.ts                        # Entry point, arg parsing, stdio transport
  server.ts                     # McpServer + 22 tool registrations + resources
  core/
    types.ts                    # ForgeConfig, SessionInfo, defaults
    ring-buffer.ts              # Circular buffer with multi-consumer cursors
    terminal-session.ts         # PTY + headless xterm + ring buffer
    session-manager.ts          # CRUD, max sessions, groups, persistence
    state-store.ts              # ~/.forge/sessions.json persistence
    templates.ts                # Built-in session templates
    claude-chats.ts             # Claude Code chat session discovery
    command-history.ts          # Tool call history tracking
  dashboard/
    dashboard-server.ts         # HTTP + WebSocket + MCP transport server
    dashboard-html.ts           # HTML assembler (imports frontend parts)
    ws-handler.ts               # WebSocket message handling
    frontend/
      styles.ts                 # CSS styles (Tokyo Night theme)
      state.ts                  # Preact Signals + WebSocket + chat API
      utils.ts                  # timeAgo, formatSize, formatToolBlock
      app.ts                    # Root App component + JS concatenation
      assets.ts                 # Base64-embedded favicon + logo
      components/
        sidebar.ts              # Session list, chat browser, connection status
        terminal-view.ts        # XTerm container, activity log, status bar
        chat-view.ts            # Chat message viewer with bubbles
        modals.ts               # New terminal + delete chat modals
  utils/
    logger.ts                   # stderr-only JSON logger
    config.ts                   # CLI flags > env vars > defaults
    control-chars.ts            # Named key -> escape sequence map
    daemon.ts                   # Daemon lifecycle (PID, port, lock files)
desktop/
  main/
    index.ts                    # Electron main process entry
    daemon.ts                   # Forge server lifecycle (start/detect existing)
    window.ts                   # BrowserWindow + state persistence
    preload.ts                  # Context bridge (forgeDesktop API)
    tray.ts                     # System tray + context menu
    menu.ts                     # macOS application menu
    notifications.ts            # Native notification bridge
    auto-launch.ts              # Login item registration
    html-server.ts              # Lightweight HTTP server for desktop HTML
    daemon-bridge.ts            # WebSocket relay to existing daemon
    updater.ts                  # Auto-update placeholder
  electron-builder.yml          # Build config (DMG, universal binary)
  forge.entitlements.plist      # macOS entitlements
test/
  unit/                         # ring-buffer, config, control-chars, state-store, templates
  integration/                  # terminal-session, session-manager, mcp-tools E2E

Test Coverage

Requirements

• Node.js >= 18

• macOS, Linux, or Windows (anywhere node-pty builds)

License

MIT