Install FlowForge

FlowForge installs once per machine, not once per project. Register any number of repos — nothing lands in your customer repo except five inert Git hook shims and a small .claude/ directory. All session state, time tracking, and billing live under ~/.flowforge/, well outside your repo’s working tree. Install it once. Use it everywhere.

This guide takes you from “no FlowForge” to “registered first repo and TUI is up.” Plan on five minutes.

Prerequisites

Git — FlowForge is a Git-centric framework; every session is tied to a branch and the hook router runs from your repo’s .git/hooks/.
Bash — the hook shims are 29-line Bash scripts (13 effective lines of logic). FlowForge does not require Node.js, npm, or any JavaScript toolchain. The binary is Go, the hooks are Bash, period.
Linux or macOS — confirmed targets for v1.0. Windows users: run FlowForge under WSL2 (the binary is a Linux ELF).
Claude Code — FlowForge integrates with Claude Code via the home-level ~/.claude/ mirror. Install Claude Code separately from docs.anthropic.com/en/docs/claude-code.

You do not need Node.js, npm, npx, pnpm, yarn, or any JavaScript runtime. If a guide tells you otherwise, that guide is out of date.

Install

curl -fsSL https://get.flowforgesoft.com/install.sh | sh

This one command detects your OS and architecture, downloads the promoted flowforge binary, verifies its checksum, installs it to $PATH (/usr/local/bin by default — override with FLOWFORGE_INSTALL_DIR), and finishes by running flowforge install --global for you. A single curl reaches a working install.

macOS (Apple Silicon and Intel) and Linux (x86_64, arm64) are detected automatically. Windows: run this under WSL2 (the binary is a Linux ELF) — see the Windows note below.

If you already have the flowforge binary on your $PATH by other means (e.g. built from source) and just need to finish setup, run the global installer directly:

flowforge install --global

One command does two things:

(a) Populates ~/.flowforge/ — the global state and asset tree:

~/.flowforge/
├── VERSION                   # FF version of this install
├── bin/
│   ├── flowforge             # the binary (your $PATH symlink can target this)
│   └── flowforge-hook        # the hook router invoked by every shim
├── agents/                   # 41 fft-* agent specs (single source of truth)
├── slash-commands/           # /flowforge:* commands
├── hooks-templates/          # source-of-truth hook scripts + shim.tmpl
├── pubkey.asc                # FF release-signing public key
├── repos/                    # per-repo state (one subdir per registered repo)
│   ├── index.json            # registry: repo-id → worktree path
│   └── <repo-id>/            # per-repo state (abbreviated — also includes
│                             #   tasks.json, config.json, meta.json, plus
│                             #   billing/, developers/, sessions/, audit/)
└── logs/, cache/             # global logs and cache

(b) Mirrors FlowForge into ~/.claude/ — so Claude Code sees FF’s discipline regardless of which directory you open a session in. The mirror layer follows a contract of zero-destructive merge:

Path	Mode	What lands
`~/.claude/CLAUDE.md`	append-with-markers	A FlowForge section delimited by `<!-- FLOWFORGE BEGIN v<X.Y.Z> -->` and `<!-- FLOWFORGE END -->`. Your existing CLAUDE.md content outside the markers is byte-equivalent before and after.
`~/.claude/skills/flowforge-*/`	namespaced own-dirs	Each FF skill in its own `flowforge-<slug>/` directory. The `flowforge-` prefix is the namespace boundary; anything else under `~/.claude/skills/` is yours and FlowForge will not touch it.
`~/.claude/agents/fft-*.md`	namespaced files	Each FF agent under the `fft-` prefix.
`~/.claude/commands/flowforge/`	namespaced subdir	The `/flowforge:*` command tree under a single subdirectory.
`~/.claude/settings.json`	JSON deep-merge of `hooks` key	FF’s hook entries are tagged `_flowforge_managed: true` for clean uninstall. Other top-level keys you have set are untouched.

The install is idempotent — run it twice in a row and ~/.claude/ ends up byte-identical. If you have hand-written content at a path FlowForge intends to write (e.g., a directory you authored named ~/.claude/skills/flowforge-something/), the install errors out with a clear remediation hint rather than overwriting your work; FlowForge will detect the conflict and offer a backup-and-proceed remediation.

First-time setup — register your first repo

flowforge install --global does not register any repos for you. You opt each repo in.

cd /path/to/your/project
flowforge tui

Without an active repo, flowforge tui lands on the Repo Switcher panel — which is exactly what you want for your first registration. (If you’re already inside a registered repo and still land here, no session is active yet; pick the repo from the switcher and press Enter to activate.) Press r to open the Register Repo modal:

╭─ Register Repo ──────────────────────────────────────╮
│                                                      │
│  Path:    [/srv/projects/myproject_________________] │
│                                                      │
│  Remote:  github.com/myorg/myproject                 │
│  Repo ID: a3f2b8e91c4d                               │
│                                                      │
│  Will create:                                        │
│    ~/.flowforge/repos/a3f2b8e91c4d/                  │
│    .git/hooks/{pre-commit, pre-merge-commit,         │
│                post-commit, pre-push,                │
│                commit-msg, post-checkout}            │
│    .claude/{agents → ~/.flowforge/agents,            │
│             commands → ~/.flowforge/slash-commands,  │
│             settings.json (rendered)}                │
│                                                      │
│  [Enter] register  [Esc] cancel                      │
╰──────────────────────────────────────────────────────╯

The repo ID is the first 12 hex characters of sha256(canonical_remote_url). Press Enter and FlowForge:

Creates ~/.flowforge/repos/<repo-id>/ with the per-repo state subtree (billing/, developers/, sessions/, audit/, plus tasks.json, config.json, meta.json).
Writes five thin hook shims to <repo>/.git/hooks/<name> — byte-identical across every repo you ever register, for a given FF version.
Symlinks <repo>/.claude/agents → ~/.flowforge/agents and <repo>/.claude/commands → ~/.flowforge/slash-commands.
Renders <repo>/.claude/settings.json (per-repo because it references this worktree’s path).
Appends an entry to ~/.flowforge/repos/index.json.

That’s the entire structural floor in your customer repo: five Git hook shims plus a minimal .claude/ directory. Your repo’s existing files are not touched. If you git status after registering, the only changes you’ll see are the additions to .claude/ and .git/ — and .git/hooks/ is not tracked by Git anyway.

Verify the install

flowforge version

Prints the FF version that’s recorded in ~/.flowforge/VERSION. If this fails with “command not found”, your $PATH does not include the binary’s location.

flowforge tui

Should land on the Repo Switcher with your registered repo listed. Pressing Enter on the repo activates it and switches to the four-panel cockpit (workers, logs, merge queue, controller).

The hook router is exercised the next time Git fires a hook in the registered repo:

cd /path/to/your/project
git commit --allow-empty -m "verify: flowforge hooks fire"

If the FlowForge pre-commit and commit-msg hooks run, you’ll see their output.

Per-OS notes

Linux — confirmed primary target. The binary is a static Linux ELF; no shared library dependencies beyond glibc.

macOS — confirmed target, Apple Silicon and Intel both detected automatically by the installer. macOS may require you to grant Gatekeeper permission the first time you run the binary (System Settings → Privacy & Security).

Windows — run under WSL2 with a Linux distribution. The Linux binary is what ships; native Windows is not a v1.0 target. Your repo paths on the Windows side (C:\…) work fine via WSL2’s filesystem bridge, but FlowForge resolves repo identity from the Linux-side worktree path.

Offline-stable by design

Once flowforge install --global has run, the binary, agents, commands, hook router, and skills are local plain files in ~/.flowforge/ and ~/.claude/. FlowForge does not phone home for runtime operation. You can pull your laptop offline, fly across an ocean, and flowforge tui keeps working — your time tracking accumulates locally, your hooks fire, your audit log appends.

This is intentional. The binary, agents, hooks, and time tracking are yours — they work on your machine, offline, permanently. The dashboard, team workspace, and continuous updates are the paid layer. Same model as the tools you already use.

Next steps

Install once, use everywhere — register additional repos, switch between them in the TUI, and learn how FlowForge handles Git worktrees.
Migrating from a legacy install — already on a per-project .flowforge/ install? The migration guide walks you through the cutover with a dry run, automatic backup, and rollback support.

References

These decisions live in FlowForge’s internal architecture registry, which sits in the source repository — private by design, so there’s no public URL to link to. Citing them here anyway, for readers who work with the FlowForge team and can pull the source repo directly.

ADR-0025: Single-Install Architecture — the canonical decision (Accepted 2026-05-08). documentation/architecture/ADR-0025-single-install-architecture.md
ADR-0026: ~/.claude/ Mirror Layer — the home-layer integration contract (Accepted 2026-05-09). documentation/architecture/ADR-0026-claude-mirror-layer.md
HOOK-SHIM-CONTRACT.md — what’s in those five hook shims, why each line is load-bearing. documentation/v1.0/architecture/install/HOOK-SHIM-CONTRACT.md
TUI-PANELS-SPEC.md — Repo Switcher and Register Repo panel design. documentation/v1.0/architecture/install/TUI-PANELS-SPEC.md
OPTIONS.md — install architecture options analysis (Option α accepted). documentation/v1.0/architecture/install/OPTIONS.md