Skip to content
FlowForge Logo FlowForge

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

Section titled “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 — flowforge install --global

Section titled “Install — flowforge install --global”

The install path has two steps: get the binary onto your $PATH, then run the global installer.

1. Download the binary

Section titled “1. Download the binary”

Download the flowforge binary for your OS from the latest GitHub Release. Place it on your $PATH (e.g., /usr/local/bin/flowforge or ~/bin/flowforge) and make it executable:

Terminal window
chmod +x /usr/local/bin/flowforge
flowforge version

macOS (Apple Silicon): download flowforge-darwin-arm64. macOS (Intel): download flowforge-darwin-amd64. Linux (x86_64): download flowforge-linux-amd64. Windows: see the Windows note below — run under WSL2 using the Linux binary.

(For Windows-specific setup, see Per-OS notes below.)

The binary is signed via Sigstore attestations from GitHub Actions. Verify the attestation if your security policy requires it.

2. Run the global installer

Section titled “2. Run the global installer”
Terminal window
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/                   # 33 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:

PathModeWhat lands
~/.claude/CLAUDE.mdappend-with-markersA 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-dirsEach 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-*.mdnamespaced filesEach FF agent under the fft- prefix.
~/.claude/commands/flowforge/namespaced subdirThe /flowforge:* command tree under a single subdirectory.
~/.claude/settings.jsonJSON deep-merge of hooks keyFF’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

Section titled “First-time setup — register your first repo”

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

Terminal window
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, 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:

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

Section titled “Verify the install”
Terminal window
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.

Terminal window
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:

Terminal window
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

Section titled “Per-OS notes”

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

macOS — confirmed target. Use the darwin-arm64 or darwin-amd64 release asset matching your Mac’s architecture. 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

Section titled “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

Section titled “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

Section titled “References”