ferodrigop/forge

Terminal MCP server for AI coding agents. Spawn, manage, and monitor real PTY sessions via the Model Context Protocol.
forgemcp.dev
---
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, Gemini CLI, 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, Codex, and Gemini 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
Install
After install, the forge command is available globally:
Update
Quick Start
1. Add to Your Agent
Claude Code
> **Note:** Always use HTTP transport so Claude Code connects to the running daemon. This ensures sessions appear in the dashboard and avoids conflicts from isolated processes.
Codex
Codex stores this in ~/.codex/config.toml:
Gemini CLI
HTTP MCP (any client)
Start the daemon (choose one launch mode), then point any MCP client at the HTTP endpoint:
Restart your agent and Forge tools are available.
Important: Claude Code, Codex, and Gemini CLI load MCP servers at process start. If you add/remove servers, restart the current agent session.
2. Smoke Test (60s)
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**
**I/O**
**Search & Wait**
**Execution**
**Events**
**Agent Delegation**
**Ops**
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