Forge runs looped AI coding agents per repository.

Forge focuses on a simple loop runtime instead of tmux- or node-managed agents. Each loop:

• resolves a base prompt
• applies queued messages/overrides
• runs a harness command (pi, opencode, codex, claude)
• appends logs + ledger entries
• sleeps and repeats
• injects runtime env: FORGE_LOOP_ID, FORGE_LOOP_NAME (FMAIL_AGENT defaults to loop name)

Key features:

• Loops: background processes per repo
• Profiles + Pools: harness + auth homes with concurrency caps
• Queue: message, pause, stop, kill, next-prompt override
• Persistent agents: parent-oriented delegated work via forge agent run / forge agent send
• Smart stop: quantitative (command-based) + qualitative (judge iteration) stop rules
• Logs + Ledgers: logs centralized in the data dir, ledgers committed per repo
• TUI: themed loop dashboard with tabs (Overview, Logs, Runs, Multi Logs), harness-aware log highlighting, and configurable multi-log layouts up to 4x4

Homebrew (macOS/Linux):

brew install trmdy/tap/forge

Linux script (x86_64/arm64):

curl -fsSL https://raw.githubusercontent.com/trmdy/forge/main/scripts/install-linux.sh | bash

Optional overrides:

FORGE_VERSION=v0.0.0 FORGE_INSTALL_DIR="$HOME/.local/bin" FORGE_BINARIES="forge" \
  bash -c 'curl -fsSL https://raw.githubusercontent.com/trmdy/forge/main/scripts/install-linux.sh | bash'

# 1) Initialize repo scaffolding
forge init

# 2) Import aliases (or add a profile manually)
# Scans common shell alias files and detects installed harnesses (claude/codex/opencode/pi/droid).
forge profile init
# forge profile add pi --name local

# 3) Create a pool and add profiles
forge pool create default
forge pool add default oc1
forge pool set-default default

# 4) Start a loop
forge up --count 1
# optional: explicit local ownership (default)
# forge up --count 1 --spawn-owner local
# optional: force daemon ownership (fails if forged unavailable)
# forge up --count 1 --spawn-owner daemon
# Optional: smart stop rules
# forge up --name review --quantitative-stop-cmd 'sv count --epic | rg -q "^0$"' --quantitative-stop-exit-codes 0
# forge up --name review --qualitative-stop-every 5 --qualitative-stop-prompt stop-judge

# 5) Send a message and watch logs
forge msg <loop-name> "Review the PRD and summarize next steps"
forge logs <loop-name> -f

# 6) Launch the TUI
forge

Use persistent agents when parent wants to delegate one task, then re-engage same child later.

# Recipe 1: fastest path (spawn/reuse + send + wait)
forge agent run "Review PR #42 and list blockers" --agent reviewer-1 --type codex --wait idle

# Recipe 2: reuse same child for follow-up task
forge agent run "Now propose fix order with risk levels" --agent reviewer-1 --wait idle

# Recipe 3: include parent correlation metadata
forge agent run "Draft release notes from latest commits" \
  --agent writer-1 \
  --task-id forge-ftz \
  --tag docs \
  --label epic=M10 \
  --wait idle

Harness mode guidance:

• Persistent delegation requires an interactive harness session.
• If spawn fails with a mode/capability mismatch, switch to an interactive harness command/profile.

Forge keeps committed repo state in .forge/:

.forge/
  forge.yaml
  prompts/
  templates/
  sequences/
  ledgers/

Runtime data (sqlite, logs, pids) stays in the machine-local data dir.

Code layout:

• Rust primary workspace at repo root (Cargo.toml, crates/*)
• Legacy Go tree under old/go/

Global config lives at ~/.config/forge/config.yaml. Repo config lives at .forge/forge.yaml. See docs/config.md for details.

Install repo skills for configured harnesses with:

forge skills bootstrap

If a profile has no auth_home, skills are installed into repo-local harness folders (for example .codex/skills/). When .agent-skills/ is missing, the CLI falls back to the embedded skills.

Install skills into harness-specific locations with:

scripts/install-skills.sh

See docs/skills.md for details.

See docs/cli.md for the full CLI surface.

Legacy command group forge subagent ... is replaced by forge agent ....

# old
forge subagent spawn reviewer-1 --command codex
forge subagent send reviewer-1 "Summarize open issues"
forge subagent wait reviewer-1 --until idle

# new
forge agent spawn reviewer-1 --command codex
forge agent send reviewer-1 "Summarize open issues"
forge agent wait reviewer-1 --until idle

Loop runners can be spawned with explicit ownership:

• local (default): detached local process
• daemon: owned by forged daemon
• auto: daemon first, local detached fallback if daemon unavailable

Commands supporting owner selection:

• forge up --spawn-owner ...
• forge scale --spawn-owner ...
• forge resume --spawn-owner ...