Guides

Best practices, multi-agent orchestration, dashboard setup, session templates, and token efficiency tips.

Best Practices

`run_command` vs `create_terminal`

Use run_command for one-shot tasks that exit (build, test, install). Use create_terminal for ongoing sessions (dev servers, watchers, REPLs).

# Good — build is a one-shot task

run_command({ command: "npm run build && npm test" })

# Good — dev server needs to stay alive

create_terminal({ command: "npm run dev", name: "dev-server" })

wait_for({ id, pattern: "ready on" })

`waitForExit` vs pattern matching

pattern

Pattern matching (default) — returns as soon as the line appears. The process keeps running.

exit

waitForExit: true — waits for the process to finish, then returns everything.

`fromSession` for sub-agents

Use fromSession instead of hardcoding paths. It inherits cwd from an existing session, keeping your agent configurations portable.

Worktrees for parallel agents

Use worktree: true to isolate changes when running multiple agents on the same codebase. Each agent gets its own git worktree, preventing file conflicts.

Multi-Agent Orchestration

Spawn agents

Use spawn_claude, spawn_codex, spawn_gemini to launch sub-agents.

Tag & group

Use tags for logical grouping: "research", "feature". Clean up with close_group.

Isolation

Use worktree: true for full filesystem isolation between agents.

Delegation

Use delegate_task for interactive multi-turn conversations between agents.

Monitor all sessions with read_multiple and list_terminals.

Web Dashboard

Enable with --dashboard --port 3141. Open http://localhost:3141.

Live terminal output via WebSocket

Activity log (tool calls for agent sessions)

Chat history browser (Claude, Codex, Gemini)

Session management (create, close, switch)

Auto-follow mode

Memory monitoring

If --auth-token is enabled, access with ?token=YOUR_TOKEN.

Desktop App

macOS Electron app. Currently requires running from source (pending Apple code signing).

$ npm run build

$ cd desktop && npm install

$ npx @electron/rebuild

$ npm run dev

Native title bar & system tray

Close-to-tray & notifications

Auto-update support

Security hardened

Session Templates

Built-in templates for common workflows:

Template	Command	Tags	Wait For
shell	$SHELL	shell	—
next-dev	npx next dev	dev-server, next	"Ready"
vite-dev	npx vite	dev-server, vite	"Local:"
docker-compose	docker compose up	docker	—
npm-test	npm test	test	—
npm-test-watch	npm run test:watch	test, watch	—

Token Efficiency

Forge uses a ring buffer with per-consumer cursors — each read_terminal call returns only new output since the last read. No repeated content, no wasted tokens.

90%

Context token savings

30 KB

Read cap per call

Cursor

Per-consumer tracking