Tools Reference
Complete reference for all 23 MCP tools exposed by Forge, organized in 7 categories.
Categories
create_terminal, create_from_template, spawn_claude, spawn_codex, spawn_gemini, close_terminal, close_group, list_terminals, list_templates
write_terminal, read_terminal, read_screen, read_multiple, send_control, resize_terminal
grep_terminal, wait_for
run_command
subscribe_events, unsubscribe_events
delegate_task
health_check, get_session_history, clear_history
Session Lifecycle
create_terminal
Create a new persistent terminal session. Returns session info including the id used by all other tools.
| 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 |
| cols | number | 120 | Terminal width |
| rows | number | 24 | Terminal height |
| name | string | — | Human-readable name |
| tags | string[] | — | Tags for filtering (max 10) |
| bufferSize | number | Server default | Ring buffer size (1KB–10MB) |
create_from_template
Create a terminal session from a predefined template.
| Parameter | Type | Default | Description |
|---|---|---|---|
| template | string | required | Template name |
| cwd | string | — | Working directory override |
| env | object | — | Additional env vars |
| name | string | Template name | Session name override |
spawn_claude
Spawn a Claude Code sub-agent in its own terminal session.
| Parameter | Type | Default | Description |
|---|---|---|---|
| prompt | string | required | Prompt to send |
| cwd | string | — | Working directory |
| fromSession | string | — | Copy cwd from existing session |
| model | string | — | Model (e.g. "sonnet", "opus") |
| name | string | Auto | Session name |
| tags | string[] | ["claude-agent"] | Tags |
| maxBudget | number | — | Max budget in USD |
| bufferSize | number | Server default | Ring buffer size |
| worktree | boolean | false | Create git worktree |
| branch | string | — | Branch name for worktree |
| oneShot | boolean | false | Run in --print mode |
spawn_codex
Spawn a Codex sub-agent. Same parameters as spawn_claude but for Codex. Tags default to ["codex-agent"].
| Parameter | Type | Default | Description |
|---|---|---|---|
| prompt | string | required | Prompt to send |
| cwd | string | — | Working directory |
| fromSession | string | — | Copy cwd from existing session |
| model | string | — | Model override |
| name | string | Auto | Session name |
| tags | string[] | ["codex-agent"] | Tags |
| maxBudget | number | — | Max budget in USD |
| bufferSize | number | Server default | Ring buffer size |
| worktree | boolean | false | Create git worktree |
| branch | string | — | Branch name for worktree |
| oneShot | boolean | false | Run in --print mode |
spawn_gemini
Spawn a Gemini CLI sub-agent. Same parameters as spawn_claude but for Gemini CLI. Tags default to ["gemini-agent"].
| Parameter | Type | Default | Description |
|---|---|---|---|
| prompt | string | required | Prompt to send |
| cwd | string | — | Working directory |
| fromSession | string | — | Copy cwd from existing session |
| model | string | — | Model override |
| name | string | Auto | Session name |
| tags | string[] | ["gemini-agent"] | Tags |
| maxBudget | number | — | Max budget in USD |
| bufferSize | number | Server default | Ring buffer size |
| worktree | boolean | false | Create git worktree |
| branch | string | — | Branch name for worktree |
| oneShot | boolean | false | Run in --print mode |
close_terminal
Close a terminal session and clean up its resources.
| Parameter | Type | Default | Description |
|---|---|---|---|
| id | string | required | Session ID |
close_group
Close all terminal sessions matching a tag.
| Parameter | Type | Default | Description |
|---|---|---|---|
| tag | string | required | Tag to match |
list_terminals
List all active terminal sessions, optionally filtered by tag.
| Parameter | Type | Default | Description |
|---|---|---|---|
| tag | string | — | Filter by tag |
list_templates
List all available session templates. No parameters.
I/O
write_terminal
Send text input to a terminal session.
| Parameter | Type | Default | Description |
|---|---|---|---|
| id | string | required | Session ID |
| input | string | required | Text to send |
| newline | boolean | true | Append \n |
read_terminal
Read incremental output from a terminal session. Returns { status, data, bytes, droppedBytes? }.
| Parameter | Type | Default | Description |
|---|---|---|---|
| id | string | required | Session ID |
read_screen
Read the current rendered viewport as plain text (no ANSI escape codes).
| Parameter | Type | Default | Description |
|---|---|---|---|
| id | string | required | Session ID |
read_multiple
Read output from multiple sessions in a single call.
| Parameter | Type | Default | Description |
|---|---|---|---|
| ids | string[] | required | Session IDs (1–20) |
| mode | string | "incremental" | "incremental" or "screen" |
send_control
Send a control key or special key to a terminal session.
| Parameter | Type | Default | Description |
|---|---|---|---|
| id | string | required | Session ID |
| key | string | required | Control key name |
resize_terminal
Resize a terminal session's viewport.
| Parameter | Type | Default | Description |
|---|---|---|---|
| id | string | required | Session ID |
| cols | number | required | New width (1–500) |
| rows | number | required | New height (1–200) |
Search & Wait
grep_terminal
Search terminal output with regex. Returns { matches: [{ lineNumber, text, context? }], totalMatches }.
| Parameter | Type | Default | Description |
|---|---|---|---|
| id | string | required | Session ID |
| pattern | string | required | Regex pattern |
| context | number | 0 | Context lines (0–10) |
wait_for
Wait for a pattern to appear in terminal output or for the process to exit. Returns { matched, data?, reason?, elapsed }.
| Parameter | Type | Default | Description |
|---|---|---|---|
| id | string | required | Session ID |
| pattern | string | — | Regex pattern |
| timeout | number | 30000 | Timeout ms (100–300000) |
| waitForExit | boolean | false | Wait for exit instead |
Execution
run_command
Run a command and wait for it to complete. Creates a temporary session, executes, and returns the output.
| Parameter | Type | Default | Description |
|---|---|---|---|
| command | string | required | Command to run |
| cwd | string | — | Working directory |
| timeout | number | 300000 | Timeout ms (max 5min) |
Events
subscribe_events
Subscribe to terminal events (exit, pattern match).
| Parameter | Type | Default | Description |
|---|---|---|---|
| id | string | required | Session ID |
| events | string[] | required | ["exit"] and/or ["pattern_match"] |
| pattern | string | — | Regex (required if pattern_match) |
unsubscribe_events
Remove an event subscription.
| Parameter | Type | Default | Description |
|---|---|---|---|
| subscriptionId | string | required | Subscription ID |
Agent Delegation
delegate_task
Delegate a task to a sub-agent (Claude or Codex) with optional git worktree isolation.
| Parameter | Type | Default | Description |
|---|---|---|---|
| prompt | string | required | Task prompt |
| agent | string | "claude" | "claude" or "codex" |
| mode | string | "oneshot" | "oneshot" or "interactive" |
| sessionId | string | — | Existing session for follow-ups |
| cwd | string | — | Working directory |
| fromSession | string | — | Copy cwd from session |
| worktree | boolean | false | Git worktree isolation |
| branch | string | — | Branch for worktree |
| model | string | — | Model override |
| from | string | — | Orchestrator attribution |
Ops
health_check
Check server health. No parameters.
Returns { version, uptime, sessions: { active, max }, memory: { rss, heapUsed, heapTotal } }.
get_session_history
Get the command history for a session.
| Parameter | Type | Default | Description |
|---|---|---|---|
| id | string | required | Session ID |
clear_history
Clear all session history. No parameters.
MCP Resources
Sessions are also exposed as MCP resources, allowing clients to read session data through the standard resource protocol.