Getting Started

There are two ways into FlowForge, and you should take the one that fits you.

• Never written code? Start with the desktop app and the 90-second walkthrough below. No setup, no jargon, nothing to install by hand.
• Already using Claude Code? Skip ahead to Install alongside Claude Code and run your first tracked session from the terminal.

Your first project in 90 seconds

You don’t need to know anything technical to begin. Open the FlowForge desktop app and you land on a calm welcome screen. From there it’s about a minute and a half to a working project — two clicks and a couple of plain-language answers.

1. Open the app. Double-click FlowForge. The welcome screen appears — no accounts to wire up first, nothing to configure.

2. Choose “Start something new”. On the welcome screen, pick + Start something new. That’s the door for beginning from scratch: you don’t need an existing folder or anything prepared.

3. Say what you want to build. FlowForge asks, in plain words, What do you want to build? Answer in a sentence or two — “a booking page for my studio,” “something to track my plants.” Whatever it is, plain words are perfect.

4. Add a few details. A second question — What should it do? — lets you say a little more. Keep it short; you can refine it later, and you can even leave it blank for now.

5. Let FlowForge build it. FlowForge sets up a project for you — a single folder on your computer that holds everything for this idea. You never had to create or name any of the technical pieces; FlowForge handled all of that quietly in the background.

6. Choose whether to keep a backup online. FlowForge offers to save a private copy online, kept with your own GitHub account, so your work is safe even if something happens to your computer. It’s optional — “Not now, keep it on this computer” is a first-class choice, and you can turn on a backup later, anytime.

7. You’re ready. Your project opens and FlowForge guides you from there — you are never alone. From this moment every hour you spend is tracked, and your work is saved as you go.

That’s the whole journey: describe your idea → answer two plain questions → your project is ready. Everything technical — making the project folder, saving your progress, keeping the online backup in sync — FlowForge does for you, out of sight.

A note on words. In FlowForge a project is simply a folder you work in, and keeping a backup online means a private copy lives with your account. You never have to learn the plumbing underneath — hiding it is the point.

Install alongside Claude Code

This path is for people who already use Claude Code; FlowForge installs alongside it. The one-line installer downloads the released binary and wires it into your environment:

curl get.flowforgesoft.com/install.sh | sh

The installer places the binary and then runs flowforge install --global, which registers FlowForge with Claude Code — the hooks, the slash commands, the MCP server, and the managed section of your global CLAUDE.md.

Restart Claude Code after the first install so it picks up the FlowForge MCP server.

The binary layout (why there are two copies)

A correct install has two byte-identical copies of the same released binary:

• /usr/local/bin/flowforge — the copy the installer downloads and puts on your PATH.
• ~/.flowforge/bin/flowforge — a self-copy at a stable absolute path that hooks and the MCP server call without fighting $PATH.

Both must be the same version — that is “one version.” You never hand-build or copy a binary into place; new versions arrive only through the release pipeline (flowforge version update or re-running the installer). The golden rule is that your machine stays identical to a customer’s install, so the bugs you see are the bugs they see — no more, no fewer.

Verify the install

flowforge version        # prints the installed version
flowforge doctor         # self-heals stale paths, missing hooks, config drift

flowforge doctor is safe to run anytime. FlowForge is designed to self-heal: customer-visible breakage (a stale path, a missing hook) repairs itself on install, upgrade, and cockpit start, because the person who could hand-fix it usually won’t be there.

Your first session

Every piece of work begins the same way — start a session on a ticket:

/flowforge:session:start 123

That single command does everything the disciplined path requires:

1. Verifies the ticket exists and is open (GitHub, Linear, Jira, or local).
2. Starts the timer — the billable record begins here.
3. Puts you on a feature branch — never main, never develop.
4. Restores context from any prior session on the same ticket.

When it returns, you are on the right branch, the clock is running, and you’re ready to build. If you don’t pass a ticket number, FlowForge tries to detect one from your current session or your assigned open issues.

The cockpit (optional but recommended)

For an interactive view of your work — timers, ticket state, and agent dispatch — launch the terminal cockpit:

flowforge tui

The cockpit is covered in ForgePlay & the Cockpit. You can do everything from slash commands alone, but the cockpit is where the workflow becomes visible.

Why it matters

Whichever door you came in — the desktop walkthrough or the terminal install — you end up in the same place: work that is tracked, saved, and tied to a project from the very first minute. That’s the point of Getting Started. Everything else in this manual builds on it.