First Session

A FlowForge session is a scoped unit of work tied to a git branch. Every session tracks time, enforces rules, and wraps up with a summary. This page walks through bootstrapping a project and completing one full session loop.

Bootstrap the project

FlowForge bootstrapping is a two-step flow handled entirely by the flowforge Go binary. There is no flowforge init subcommand — the install step replaces it.

Step 1 — install FlowForge globally (one time per machine):

flowforge install --global

This creates the global FlowForge home at ~/.flowforge/ (override with FLOWFORGE_HOME=<absolute-path>). It writes the shared asset bundle — agents, slash commands, hook templates, scripts, docs — and a self-copy of the binary at ~/.flowforge/bin/flowforge. State files (config.json, repos/index.json) are preserved across re-runs; asset directories are fully re-extracted so stale entries cannot linger.

--global is required in v1.0 (the only supported install mode); per-project install lands in a future milestone.

Step 2 — register your repository:

From the root of any project where you want to use FlowForge:

flowforge register-repo

This records the current directory in ~/.flowforge/repos/index.json under a stable repo id derived from the git remote (use --id-salt <name> to disambiguate when two clones share the same remote). FlowForge tracks per-repo state (sessions, time entries, rule audits) under ~/.flowforge/repos/<repo-id>/ — your project tree itself stays untouched.

After these two steps, Claude Code sessions opened in the registered repo discover the FlowForge integration through the global hook and slash-command surface installed in step 1.

Review the assets installed under ~/.flowforge/ once before relying on them — especially the agent definitions, which will participate in every Maestro-orchestrated session you run.

Start a session

Every piece of tracked work begins with session:start. Pass a branch name; FlowForge validates the name, confirms no other session is active, and persists session state to .claude/session.json.

flowforge session:start feature/user-profile

What happens internally:

1. Verifies the current directory is a git repository.
2. Aborts if .claude/session.json already records an active session (only one at a time).
3. Validates the branch name. Allowed characters: letters, digits, underscore, dash, slash, and dot. Names cannot be empty, contain .., start with ., -, or /, or end with / or .
4. Creates the branch if it does not exist, or checks it out if it does.
5. Writes a session record with the fields id, startedAt, branch, and status. After session:end runs, the record also gains endedAt and durationMs.
6. Starts the time tracker — this is the single most important step, because unlogged work is unpaid work.

Note

The CLI session:start handler stores only the generic session fields above. The higher-level SessionManager API (provider-aware, used by integrations that bind work to external tickets from GitHub, Linear, Notion, and so on) layers ticket IDs on top of this record. Do not confuse the two: the CLI command does not persist a ticket ID by itself.

Monitor progress

At any point during the session, check health with:

flowforge dev:status

The status report shows the active branch, elapsed session time, current rule compliance, and any outstanding warnings (for example, uncommitted changes or missing tests).

To run the full rule audit before committing, use:

flowforge dev:checkrules

End the session

When the work is ready to hand off, close the session:

flowforge session:end

FlowForge prints a summary — total time, commits made on the branch, files changed — then marks the session completed. You are now free to start a new session on a different branch.

Behind the scenes

Two mechanisms make this loop reliable:

• Hooks: pre-tool and post-tool hooks registered in Claude Code intercept every tool invocation to validate rule compliance (no direct commits to main, tests before code, no AI references in git messages, and so on). Violations either block the action or surface a warning.
• Session state: The JSON record at .claude/session.json is the single source of truth. If your shell crashes or Claude Code restarts, the session survives because state is on disk, not in memory. The branch-name character restrictions prevent shell-injection when that file is later read by scripts.

Next steps

• Run the end-to-end Tutorial to ship a small feature with the Maestro orchestration pattern.
• Read Core Concepts: Sessions for session lifecycle details.
• Read Core Concepts: Rules to understand the full rule set the hooks enforce.