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 does not ship a flowforge init shell command today. The .flowforge/ directory is normally bootstrapped by the Claude Code hook integration the first time a FlowForge-aware session runs in a repository. If you need to create it by hand, the minimum useful layout is:

.flowforge/
├── config.json        # project configuration (language, provider, rule overrides)
├── RULES.md           # project copy of the FlowForge rule set
└── tasks.json         # local task store
.claude/
└── session.json       # session state written at session:start (see below)
CLAUDE.md              # shared context the Maestro reads at session start

If you are writing your own tooling, @flowforge/core exposes an initProject() library API (from @flowforge/core/init) that creates this layout programmatically. It is a library entry point, not a CLI subcommand.

Review the generated files before committing them — especially CLAUDE.md, which becomes the shared context for every future session.

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.