Forge

Forge runs looped AI coding agents per repository.

Overview

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

Key features:

• Loops: background processes per repo
• Profiles + Pools: harness + auth homes with concurrency caps
• Queue: message, pause, stop, kill, next-prompt override
• Logs + Ledgers: logs centralized in the data dir, ledgers committed per repo
• TUI: 2x2 grid of active loops with log tails

Core Concepts

Concept	Description
Loop	Background process that repeatedly runs a harness against a prompt
Profile	Harness + auth config (pi/opencode/codex/claude)
Pool	Ordered list of profiles used for selection
Prompt	Base prompt content or file used each iteration
Queue	Per-loop queue of messages and control items
Ledger	Markdown log of loop iterations stored in the repo

Install

Linux (x86_64/arm64):

curl -fsSL https://raw.githubusercontent.com/tOgg1/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/tOgg1/forge/main/scripts/install-linux.sh | bash'

Homebrew (macOS) can be wired once a tap repo is chosen.

Quick Start

# 1) Initialize repo scaffolding
forge init

# 2) Import aliases (or add a profile manually)
# Scans common shell alias files for claude/codex/opencode/pi aliases.
forge profile import-aliases
# 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

# 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

Repo Layout

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.

Configuration

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

CLI Reference

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