# ferodrigop/forge [Health: Active]

**Category:** 🖥️ Command Line  
**Repository:** https://github.com/ferodrigop/forge  
**GitHub Stars:** 23  
**npm Downloads (last month):** 85  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/ferodrigop-forge

## Description
Terminal MCP server for AI coding agents with persistent PTY sessions, ring-buffer incremental reads, headless xterm screen capture, multi-agent orchestration, and a real-time web dashboard.

## Tools
Capabilities this server exposes over MCP:

- **create_terminal** — Spawn a new PTY terminal session. Returns session ID for subsequent operations.
- **revive_terminal** — Recreate a previously exited terminal session with the same command, working directory, name, tags, and dimensions. The old session is removed and a fresh one is spawned.
- **create_from_template** — Create a terminal session from a pre-configured template (e.g., shell, next-dev, vite-dev, npm-test).
- **list_templates** — List all available session templates.
- **spawn_claude** — Spawn a Claude Code agent in a new terminal session. IMPORTANT: cwd must be set explicitly — there is no session inheritance. By default runs in interactive mode — the session stays alive and accepts follow-up messages via the dashboard. Use oneShot: true for autonomous --print mode. Use worktree + branch to run in an isolated git worktree.
- **spawn_codex** — Spawn a Codex agent in a new terminal session. By default runs in interactive mode — the session stays alive and accepts follow-up messages via the dashboard. Use oneShot: true for autonomous `codex exec` mode (requires prompt).
- **spawn_gemini** — Spawn a Gemini CLI agent in a new terminal session. By default runs in interactive mode — the session stays alive and accepts follow-up messages via the dashboard. Use oneShot: true for headless mode (requires prompt).
- **write_terminal** — Send input to a terminal session. Appends newline by default. Use submit=true for Claude Code sessions (sends Escape+Enter to exit multi-line mode and submit).
- **read_terminal** — Read NEW output from a terminal since last read (incremental). Token-efficient — only returns what changed.
- **read_screen** — Read the current terminal viewport as rendered text (no ANSI codes). Shows what a human would see on screen.
- **grep_terminal** — Search terminal output buffer with a regex pattern. Returns matching lines with optional context.
- **wait_for** — Wait for a regex pattern to appear in terminal output, OR wait for the process to exit. Checks existing buffer/status first, then watches live. Use waitForExit: true for commands that terminate (builds, tests, installs).
- **subscribe_events** — Subscribe to session events (exit, pattern_match). Notifications are sent as MCP logging messages.
- **unsubscribe_events** — Unsubscribe from session events by subscription ID.
- **list_terminals** — List all terminal sessions with their status, PID, and activity time. Optionally filter by tag.
- **close_terminal** — Kill a terminal session and release its resources.
- **close_group** — Close all terminal sessions with a matching tag.
- **read_multiple** — Read output from multiple terminal sessions in a single call. Returns per-session results with inline errors.
- **send_control** — Send a control sequence to a terminal (e.g., ctrl+c, ctrl+d, up, down, tab, enter). Available: 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** — Change the terminal dimensions (columns and rows).
- **health_check** — Returns server health info: version, uptime, session count, and memory usage.
- **get_session_history** — Get the command/tool call history for a Claude or Codex agent session. Returns timestamped tool calls.
- **clear_history** — Clear persisted session history (stale entries from previous runs).
- **run_command** — Run a command to completion and return its output. Creates a terminal, waits for exit, returns output, and auto-cleans up. Ideal for build/test/install commands. Tip: chain commands with && (e.g., 'npm install && npm run build').
- **delegate_task** — Delegate a task to another AI agent (Claude, Codex, or Gemini). Supports two modes:
- **oneshot** (default): Agent processes the prompt and exits. Output returned directly.
- **interactive**: Agent stays alive between turns. Use `sessionId` for follow-up messages to review, push back, or guide the agent's work.

For interactive multi-turn conversations, the first call spawns the agent and returns a sessionId. Subsequent calls with that sessionId send follow-up messages. Use `from` to label which orchestrator is speaking.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "forge": {
    "command": "npx",
    "args": ["-y","forge-terminal-mcp"]
  }
}
```

## Documentation

## What ferodrigop/forge MCP server does

The ferodrigop/forge MCP server exposes real terminal sessions through the Model Context Protocol. Each session runs in a pseudo-terminal, allowing interactive programs, colored output, and terminal user interfaces to operate as they would in a normal terminal. Agents can create sessions with commands, working directories, names, tags, dimensions, and buffer settings, then reuse the returned session IDs for later operations.

It supports both long-lived workflows and disposable commands. `run_command` creates a session, waits for the process to finish, returns its output, and cleans up automatically. Persistent sessions are suited to development servers, test watchers, shells, and other processes that need follow-up input.

## How it works

The ferodrigop/forge MCP server keeps terminal output in a ring buffer and tracks read positions per consumer. `read_terminal` therefore returns output added since the previous read rather than repeatedly returning the complete buffer. `read_screen` instead returns the current viewport as rendered text without ANSI escape sequences. `grep_terminal` searches buffered output with a regular expression, while `wait_for` can block until a pattern appears or a process exits.

Sessions can be monitored individually or in batches with `read_multiple`, filtered by tags, and grouped for cleanup. Event subscriptions emit MCP logging notifications when a session exits or matches a pattern. Terminal input can be written as text or sent as control sequences such as Ctrl+C, arrow keys, Enter, and Tab. The server also reports uptime, version, session count, and memory usage through `health_check`.

## Setup and configuration

Install the published package with a package manager that provides `npx`, then start the local daemon:

```bash
npx forge-terminal-mcp start -d
```

The documented HTTP endpoint is `http://127.0.0.1:3141/mcp`. Clients connect to that endpoint after the daemon starts. The README also documents global npm or Bun installation and a standalone install script. A dashboard can be enabled with `--dashboard`, and the listening port can be changed with `--port`; the MCP client URL must match the selected port.

The project requires Node.js 18 or newer when using its npm installation path. MCP clients load server configuration at process startup, so clients need to be restarted after adding or removing the server.

## Tools and capabilities

The tool set covers:

- Creating, reviving, listing, resizing, writing to, and closing PTY sessions.
- Starting sessions from templates such as shell, Next.js development, Vite development, and npm test.
- Launching Claude Code, Codex, and Gemini CLI agents in interactive or one-shot modes.
- Running delegated tasks in one-shot or multi-turn interactive mode.
- Monitoring output with incremental reads, screen capture, regex searches, waits, and event subscriptions.
- Reviewing or clearing persisted Claude and Codex session history.
- Running a real-time browser dashboard for terminal activity and past chat sessions.

When launching an agent session, the working directory must be supplied explicitly. Claude Code sessions can use a worktree and branch for isolated Git work; one-shot modes require the relevant prompt where documented.

## Limitations and notes

The material describes a local daemon and local HTTP MCP endpoint rather than a hosted service. It does not document authentication, remote hosting, or environment variables. Commands executed through terminal sessions depend on the tools and permissions available in the host environment. Interactive agent sessions remain alive for follow-up work, while one-shot execution exits after processing its prompt. Forge is MIT-licensed.

The ferodrigop/forge MCP server is intended for MCP-compatible clients, with setup examples for Claude Code, Codex, and Gemini CLI. Those clients must be restarted when their MCP configuration changes.

_Full upstream README: https://allmcps.com/mcp/ferodrigop-forge/readme_