Architecture

1. MCP Server src/server.ts

Single file, ~2100 lines. Registers all 23 tools and 1 resource template with the MCP SDK. Each tool follows the pattern:

server.tool("name", "description", { /* zod schema */ }, async (params) => {
  return { content: [{ type: "text", text: JSON.stringify(result) }] };
});

Error handling: try-catch per tool, returns { isError: true } on failure. Never throws.

2. Session Manager src/core/session-manager.ts

CRUD for terminal sessions. Enforces max session limit. Tracks stale entries from previous server runs. Emits events on session create/close for dashboard updates.

3. Terminal Session src/core/terminal-session.ts

Wraps a single PTY process. Each session has:

Listener pattern: onData(fn) and onExit(fn) — used by wait_for, subscribe_events, and templates.

4. Ring Buffer src/core/ring-buffer.ts

Circular byte buffer. The core differentiator over simple string concatenation.

• • Fixed size (default 1MB), old data silently overwritten
• • Per-consumer cursors: each read() returns only NEW data since that consumer's last read
• • droppedBytes tells the consumer how much was lost to wrapping
• • readFullBuffer() returns everything currently in the buffer (used by grep_terminal, wait_for backlog check)

5. Command History src/core/command-history.ts

Persists tool call events as JSONL to ~/.forge/history/{sessionId}.jsonl. Event types: session_init, tool_call, tool_result. For agent sessions, terminal output streams through StreamJsonParser which extracts internal JSON-RPC events.

Incremental Read

Agent calls read_terminal(id)
  -> SessionManager.get(id)
  -> TerminalSession.read()
  -> RingBuffer.read(consumerId)  // only bytes since last read
  -> { status, data, bytes }

Write

Agent calls write_terminal(id, input)
  -> SessionManager.get(id)
  -> TerminalSession.write(input + "\n")
  -> node-pty.write()
  -> PTY process receives input

wait_for (pattern mode)

1. Check backlog: session.readFullBuffer().match(regex) -> instant return if found
2. Subscribe: session.onData(chunk => accumulated.match(regex))
3. Subscribe: session.onExit() -> resolve as "session_exited"
4. setTimeout -> resolve as "timeout"
5. First to fire wins, cleanup unsubscribes all others

wait_for (exit mode)

1. Check: session.status === "exited" -> instant return with exitCode
2. Subscribe: session.onExit(exitCode) -> resolve
3. setTimeout -> resolve as "timeout"

spawn_claude / spawn_codex / spawn_gemini

1. Build args: ["--print", "-p", prompt] + model/budget/tools flags
2. If worktree: git worktree add -> set cwd to worktree path
3. Create: manager.create({ command: agentPath, args })
4. Wire: StreamJsonParser for history extraction
5. Return session info + worktree path