Forge

Terminal MCP server for AI coding agents. Spawn, manage, and monitor real PTY sessions via the Model Context Protocol.

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

Claude Code

# 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"]
    }
  }
}

Codex

# 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"

HTTP MCP (any client)

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

Symptom	Fix
`forge: command not found`	Use `node dist/cli.js ...` from the repo root, or `npx forge-terminal-mcp ...`.
`No MCP servers configured yet` in Codex	Run `codex mcp add forge --url http://127.0.0.1:3141/mcp`, then restart Codex.
`listen EPERM ... 127.0.0.1:3141`	Run Forge in an environment that allows local port binding, or use a different port with `--port` and update the MCP URL to match.
A message appears typed but agent does not answer	The input may be queued; press `Enter` (or use `submit=true` when writing programmatically).
MCP server is configured but tools do not appear	Restart the current agent session so MCP servers reload.

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 create_from_template with "next-dev", wait_for "Ready", then creates a second session for npm test, uses read_multiple to poll both)

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

Agent: (uses spawn_claude three times with tag "research", monitors with list_terminals filtered by tag, cleans up with close_group)

You: Build and test, just give me the result

Agent: (uses run_command with npm run build && npm test — creates terminal, waits for exit, returns output, auto-cleans up)

Best Practices

`run_command` vs `create_terminal`

Use run_command when you want a result and don't need the session afterwards:

Build steps (npm run build, cargo build)
Test runs (npm test, pytest)
Install commands (npm install, pip install)
One-off scripts that exit cleanly

Use create_terminal when you need an ongoing session:

Dev servers (npm run dev, vite, next dev)
Watchers (npm run watch, tsc --watch)
REPLs or interactive processes
Long-running processes you'll poll with read_terminal

# Good — build is a one-shot task
run_command({ command: "npm run build && npm test" })

# Good — dev server needs to stay alive
create_terminal({ command: "npm run dev", name: "dev-server" })
wait_for({ id, pattern: "ready on" })

`waitForExit` vs pattern matching

Use pattern matching (default) when the process stays alive after printing the signal:

wait_for({ id, pattern: "Server running on port 3000" })
# returns as soon as the line appears — process keeps running

Use waitForExit: true when the process exits naturally and you want all output:

wait_for({ id, pattern: ".", waitForExit: true })
# waits for the process to finish, returns everything

`fromSession` for sub-agents

When spawning a sub-agent to work on the same project, use fromSession instead of hardcoding paths:

# Instead of this (brittle):
spawn_claude({ prompt: "...", cwd: "/Users/me/projects/my-app" })

# Do this (inherits cwd from current session):
spawn_claude({ prompt: "...", fromSession: currentSessionId })

This ensures the sub-agent works in the correct directory even when Forge is used across different machines or worktrees.

Worktrees for parallel agents

When running multiple agents on the same codebase, use worktree: true to isolate changes:

spawn_claude({ prompt: "Add auth", worktree: true, branch: "feature/auth" })
spawn_claude({ prompt: "Add payments", worktree: true, branch: "feature/payments" })
# Both agents work in parallel without stepping on each other

Tools Reference

`create_terminal`

Parameter	Type	Default	Description
`command`	string	User's `$SHELL`	Command to run
`args`	string[]	`[]`	Command arguments
`cwd`	string	Process cwd	Working directory
`env`	object	`{}`	Additional env vars (merged with process env)
`cols`	number	120	Terminal width
`rows`	number	24	Terminal height
`name`	string	—	Human-readable session name
`tags`	string[]	—	Tags for filtering/grouping (max 10)
`bufferSize`	number	Server default	Ring buffer size in bytes (1 KB – 10 MB)

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

`create_from_template`

Parameter	Type	Default	Description
`template`	string	required	Template name (see `list_templates`)
`cwd`	string	—	Working directory override
`env`	object	—	Additional env vars
`name`	string	Template name	Session name override

Built-in templates:

Template	Command	Tags	Wait For
`shell`	`$SHELL`	shell	—
`next-dev`	`npx next dev`	dev-server, next	"Ready"
`vite-dev`	`npx vite`	dev-server, vite	"Local:"
`docker-compose`	`docker compose up`	docker	—
`npm-test`	`npm test`	test	—
`npm-test-watch`	`npm run test:watch`	test, watch	—

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

`spawn_claude`

Parameter	Type	Default	Description
`prompt`	string	required	Prompt to send to Claude
`cwd`	string	—	Working directory (explicit path)
`fromSession`	string	—	Copy `cwd` from an existing session ID (alternative to setting `cwd` manually)
`model`	string	—	Model (e.g., "sonnet", "opus")
`name`	string	Auto from prompt	Session name
`tags`	string[]	`["claude-agent"]`	Tags (claude-agent always included)
`maxBudget`	number	—	Max budget in USD
`bufferSize`	number	Server default	Ring buffer size
`worktree`	boolean	`false`	Create a git worktree (isolates file changes)
`branch`	string	—	Branch name for worktree (required when worktree: true)
`oneShot`	boolean	`false`	Run in `--print` mode (process prompt and exit)

`run_command`

Parameter	Type	Default	Description
`command`	string	required	Command to run (supports `&&` chaining)
`cwd`	string	—	Working directory
`timeout`	number	300000	Timeout in ms (max 5 minutes)

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`

Parameter	Type	Default	Description
`id`	string	required	Session ID
`input`	string	required	Text to send
`newline`	boolean	`true`	Append `\n` after input

`read_terminal`

Parameter	Type	Default	Description
`id`	string	required	Session ID

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`

Parameter	Type	Default	Description
`id`	string	required	Session ID

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`

Parameter	Type	Default	Description
`ids`	string[]	required	Session IDs (1–20)
`mode`	string	`"incremental"`	`"incremental"` or `"screen"`

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`

Parameter	Type	Default	Description
`id`	string	required	Session ID
`pattern`	string	required	Regex pattern
`context`	number	0	Lines of context around each match (0–10)

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

`wait_for`

Parameter	Type	Default	Description
`id`	string	required	Session ID
`pattern`	string	—	Regex pattern to wait for
`timeout`	number	30000	Timeout in ms (100–300000)
`waitForExit`	boolean	`false`	Wait for process to exit instead of pattern match

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

`subscribe_events`

Parameter	Type	Default	Description
`id`	string	required	Session ID
`events`	string[]	required	`["exit"]` and/or `["pattern_match"]`
`pattern`	string	—	Regex (required if `pattern_match` in events)

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

`unsubscribe_events`

Parameter	Type	Default	Description
`subscriptionId`	string	required	Subscription ID from `subscribe_events`

`list_terminals`

Parameter	Type	Default	Description
`tag`	string	—	Filter sessions by tag

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

`close_terminal`

Parameter	Type	Default	Description
`id`	string	required	Session ID

`close_group`

Parameter	Type	Default	Description
`tag`	string	required	Tag to match

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

`send_control`

Parameter	Type	Default	Description
`id`	string	required	Session ID
`key`	string	required	Control key name

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`

Parameter	Type	Default	Description
`id`	string	required	Session ID
`cols`	number	required	New width (1–500)
`rows`	number	required	New height (1–200)

`health_check`

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

`get_session_history`

Parameter	Type	Default	Description
`id`	string	required	Session ID

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)

Note: The pre-built macOS app is currently unavailable for general download. macOS requires apps to be code-signed with an Apple Developer certificate ($99/year) before they can be opened without security warnings. We're working on getting this set up — in the meantime, you can run the desktop app from source (see below) or use the CLI via npx forge-terminal-mcp.

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
Automatic updates via GitHub Releases (downloads silently, installs on restart)
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.

Flag	Env Var	Default	Description
`--max-sessions`	`FORGE_MAX_SESSIONS`	10	Max concurrent PTY sessions
`--idle-timeout`	`FORGE_IDLE_TIMEOUT`	1800000	Session idle timeout in ms (30 min)
`--buffer-size`	`FORGE_BUFFER_SIZE`	1048576	Ring buffer size per session (1 MB)
`--shell`	`SHELL`	`/bin/bash`	Default shell for `create_terminal`
`--claude-path`	`FORGE_CLAUDE_PATH`	`claude`	Path to Claude CLI binary
`--auth-token`	`FORGE_AUTH_TOKEN`	unset	Require Bearer token for `/mcp`, `/api`, and `/ws`
`--dashboard`	`FORGE_DASHBOARD`	off	Enable web dashboard
`--port`	`FORGE_DASHBOARD_PORT`	3141	Dashboard port
`--verbose`	—	off	Enable debug logging to stderr

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 via GitHub Releases
  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

Suite	Tests	Covers
Ring Buffer	13	Circular writes, multi-consumer, wrap-around, dropped bytes
Config	10	CLI parsing, env vars, defaults, precedence, codex path
Control Chars	6	Key resolution, case insensitivity, unknown keys
State Store	4	Load/save round-trip, corruption handling
Templates	3	Lookup, unknown template, list all
Stream JSON Parser	11	Claude event parsing, tool use extraction
Terminal Session	8	PTY spawn, read/write, screen render, resize, exit
Session Manager	7	CRUD, max limit, close all, stale entries
MCP Tools E2E	51	All 23 tools end-to-end via MCP client
Forge 0.7 Features	28	Codex spawn, worktree, dashboard API, chat history
Command History	6	Event tracking, retrieval, cleanup
Claude Chats	14	Session discovery, message parsing, search
Total	161

Requirements

Node.js >= 18
macOS, Linux, or Windows (anywhere node-pty builds)

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 79 Commits
.claude		.claude
.github		.github
assets		assets
desktop		desktop
docs		docs
landing		landing
src		src
test		test
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY-ROADMAP.md		SECURITY-ROADMAP.md
SECURITY.md		SECURITY.md
forge-logo-docs.png		forge-logo-docs.png
package-lock.json		package-lock.json
package.json		package.json
server.json		server.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

Forge

Why

Quick Start

1. Add to Your Agent

2. Smoke Test (60s)

Troubleshooting

3. Use It

Example Conversations

Best Practices

run_command vs create_terminal

waitForExit vs pattern matching

fromSession for sub-agents

Worktrees for parallel agents

Tools Reference

create_terminal

create_from_template

spawn_claude

run_command

write_terminal

read_terminal

read_screen

read_multiple

grep_terminal

wait_for

subscribe_events

unsubscribe_events

list_terminals

close_terminal

close_group

send_control

resize_terminal

health_check

get_session_history

clear_history

MCP Resources

Web Dashboard

Desktop App (macOS)

Running in Development

Features

Packaging

Configuration

Architecture

Development

Project Structure

Test Coverage

Requirements

License

About

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`run_command` vs `create_terminal`

`waitForExit` vs pattern matching

`fromSession` for sub-agents

`create_terminal`

`create_from_template`

`spawn_claude`

`run_command`

`write_terminal`

`read_terminal`

`read_screen`

`read_multiple`

`grep_terminal`

`wait_for`

`subscribe_events`

`unsubscribe_events`

`list_terminals`

`close_terminal`

`close_group`

`send_control`

`resize_terminal`

`health_check`

`get_session_history`

`clear_history`

Packages