Installation & Quickstart

Install Forge, connect it to your AI coding agent, and run your first command in under 60 seconds.

Installation

Four ways to use Forge:

1. npx (no install)

$ npx forge-terminal-mcp

2. Standalone binary (no Node.js required)

$ curl -fsSL https://forgemcp.dev/install.sh | sh

Downloads a prebuilt binary for macOS (arm64/x64) or Linux (x64/arm64) to ~/.local/bin.

3. Global install (npm)

$ npm install -g forge-terminal-mcp

4. From source

$ git clone https://github.com/ferodrigop/forge.git
$ cd forge
$ npm install
$ npm run build

Connect Your Agent

Claude Code (HTTP)

Add Forge via the CLI:

# Basic

$ claude mcp add --transport http forge http://127.0.0.1:3141/mcp

# Or use forge setup (auto-starts daemon)

$ forge setup --agent claude-code

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

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

Codex (HTTP)

# Start Forge daemon first
$ npx forge-terminal-mcp start -d --dashboard --port 3141

# Register with Codex
$ codex mcp add forge --url http://127.0.0.1:3141/mcp

Gemini CLI (HTTP)

# Start Forge daemon first
$ npx forge-terminal-mcp start -d --dashboard --port 3141

# Register with Gemini CLI
$ gemini mcp add --transport http forge http://127.0.0.1:3141/mcp

Any MCP Client (HTTP)

$ npx forge-terminal-mcp start -d --port 3141
# MCP endpoint: http://127.0.0.1:3141/mcp

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

Smoke Test

Verify everything is working:

$ codex mcp list
$ codex mcp get forge
$ node dist/cli.js status

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`	Use a different port with `--port` and update the MCP URL to match.
A message appears typed but agent does not answer	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.

Example Conversations

Here are some things you can ask your agent once Forge is connected:

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

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

"Build and test, just give me the result"