ForgeFlow / Reference

Quick Start

Upgrading from legacy agent names: follow the source-checkout migration procedure before using an old installed updater. It explains how to preserve edited legacy agents and recover the previous installation.

Install ForgeFlow into Claude Code or Codex, then use it inside the application repository you want to improve. For screenshots and a complete walkthrough, use the visual guide or PDF.

Prerequisites

Use a working host installation, Git, Node.js, npm, and Bash in the same environment. Use Node 24 for this repository's local validation. With WSL, keep the host and runtime paths in the same WSL environment. Check that the models named by the installed agents are available to your account; a file being installed does not prove the host can run its model.

Clone The Source

git clone https://github.com/BrandedTamarasu-glitch/ForgeFlow.git
cd ForgeFlow

Install Into Your Host

Run the matching commands from the ForgeFlow checkout.

Codex

node scripts/forgeflow/install-template.js --target codex --dry-run --json
node scripts/forgeflow/install-template.js --target codex

The installer respects CODEX_HOME and preserves unrelated configuration. Restart Codex, then confirm it discovers $quick or $consult. See Codex First Run for custom home directories and model troubleshooting.

Claude Code

node scripts/forgeflow/install-template.js --target claude --dry-run --json
node scripts/forgeflow/install-template.js --target claude

Restart Claude Code. The installer registers Ember's UserPromptSubmit hook and backs up changed settings while preserving unrelated entries. Follow Settings and Recovery to merge the other hooks and the status line manually.

After the legacy-name migration, /update-forgeflow is the normal Claude updater. --repair restores managed files; --rollback uses a previous managed-file snapshot when one exists. The source updater supports both host targets; see Settings and Recovery for Codex recovery and Template Installer for other installer options, including --target both.

Set The Runtime Path

Choose the runtime for the host you installed, and keep this shell open for the following steps:

# Codex:
FF_RUNTIME="${CODEX_HOME:-$HOME/.codex}/forgeflow"

# Or Claude Code:
# FF_RUNTIME="$HOME/.claude/forgeflow"

For a custom Claude home, use that directory's forgeflow subdirectory.

Enable The Dashboard

The installer prepares locked service dependencies automatically. If it reports a setup warning, repair missing dependencies with:

npm ci --prefix "$FF_RUNTIME/services/dashboard" --ignore-scripts --no-audit --no-fund
npm ci --prefix "$FF_RUNTIME/services/agent-chat" --ignore-scripts --no-audit --no-fund

On the first eligible ForgeFlow workflow invocation in a desktop session, the workflow helper starts or reuses the services, reports the phase, and opens http://127.0.0.1:4003/. Later invocations reuse the session without opening more tabs. Startup never installs dependencies automatically. Headless sessions and FORGEFLOW_DASHBOARD_AUTO_OPEN=off skip automatic launch.

Dashboard and Ember covers manual startup, animation states, empty panels, and stopping the services.

Open Your Application Project

Replace the example path with the project you want to work on:

cd /path/to/your-project
git status --short
bash "$FF_RUNTIME/scripts/forgeflow/ensure-forgeflow-state.sh"
node "$FF_RUNTIME/scripts/forgeflow/seed-budget-config.js" --json
node "$FF_RUNTIME/scripts/forgeflow/health-check.js" --json

The bootstrap creates local .forgeflow/<project-name>/ state and git-ignore entries; the budget helper preserves an existing config. Inspect the resulting changes and choose a suitable working branch. If health reports missing project state, inspect its proposed action; health-check.js --fix --json repairs supported local-state gaps. Optional profiles, benchmarks, and outcome history can be absent in a new project.

Run One Small Task

Add your task after the command. For example: design a helpful empty state for the task list, reuse the existing Create task action, and include keyboard behavior. Run each phase separately, inspect its result, and steer the assistant before continuing. Request any commit, push, PR, or deployment explicitly.

Use $forge-review in Codex; its built-in /review is a different command. The extended Claude catalog is larger than the Codex skill set. Workflow Commands distinguishes those surfaces.

Understand The First Results

Ember shows reported activity. Project Readiness identifies actionable checks separately from optional evidence. Review Outcomes and Review Trends need real verdict records; Live Activity needs the activity service and emitted events. Empty panels are explained in Dashboard.

For deeper context, memory, failures, or release work, choose a path in User Paths. Lean Evidence and Release Gate are advanced validation references, not prerequisites for trying a first task.