forgev0.19
Docs pages

Install

Two commands put forge into every agent CLI on your machine. A third tells you which of them it can actually reach.

What you need

  • macOS or Linux, with bash, git and Python 3.9 or later.
  • At least one agent CLI to send work to: Claude Code (claude), Codex (codex), OpenClaude, OpenCode, Antigravity (agy) or Grok. forge uses the ones you already have; npm installs none of them.

From npm

$ npm install -g @giamme/forge
$ forge install

forge install links forge into each agent CLI it finds, so /forge works inside them. It's a separate step rather than an npm install script, so it works where scripts are turned off. Restart any agent session that was already open.

Using Foundry? Foundry's command is also called forge, and whichever comes first on your PATH wins. Runs start from your agent CLI, so this only matters for forge install and the helper commands. Keep Foundry first if you like, and run ours as "$(npm root -g)/@giamme/forge/forge".

From a git checkout

Handy if you want to read or change forge itself.

$ git clone https://github.com/Giamme/forge.git ~/.claude/skills/forge
$ bash ~/.claude/skills/forge/scripts/forge-install.sh

Clone it anywhere; ~/.claude/skills/forge is just the tidiest home, because Claude Code reads it directly. --dry-run shows what the installer would do. It never overwrites a real folder.

Check which CLIs forge can reach

$ bash "$(npm root -g)/@giamme/forge/scripts/forge-dispatch.sh" doctor
HARNESS      STATUS     DETAIL
codex        found      /Users/you/.nvm/versions/node/v24.18.0/bin/codex
claude       found      /Users/you/.local/bin/claude
openclaude   found      /Users/you/.nvm/versions/node/v24.18.0/bin/openclaude
opencode     found      /Users/you/.opencode/bin/opencode
antigravity  MISSING    agy not on PATH
grok         found      /Users/you/.grok/bin/grok

MISSING is fine for any CLI you won't use. But found isn't the same as working: a CLI can be installed and still fail on sign-in or billing mid-run. To prove one model end to end before a real run:

bash "$(npm root -g)/@giamme/forge/scripts/forge-dispatch.sh" dwarf sol \
  --prompt-file /dev/stdin --repo /tmp/scratch <<< 'Reply with exactly: FORGE_OK'

Keep it current

forge checks for a new release at most once a day, silently offline and in CI, and prints one line when there is one.

# installed from npm
npm install -g @giamme/forge@latest && forge install

# installed from a git checkout
./forge update

forge version shows what you have; forge version --check asks for the newest release now. Restart open agent sessions afterwards.

Antigravity keeps a copy. It copies forge's files into its plugin rather than linking them. Run forge install again after every update, or it keeps running the old version.

Optional add-ons

forge works fully without these. The installer offers them and declines by default.

  • Ripwire adds repository evidence to every planner, dwarf and reviewer prompt. Turn it off with --no-ripwire.
  • Decision gates (forge decide) let a small external model advise on things like scope drift or a vague prompt. Off by default; each gate you enable sends a narrow slice of the run to an external API, so read what it sends first.
  • Fractal lets a dwarf split its own task into child tasks. It's being replaced by native decomposition (see What's coming), so new setups can skip it.

Full reference Every flag and edge case: docs/install.md