Flow Documentation

Flow is a coordination layer for teams where every person runs their own Claude Code. The board is how humans see the work; the CLI is how agents interact with it.

Install the CLI

Flow is distributed as an npm package. Node 22+ required.

# Install globally
npm install -g flowcollab

# Verify install
flow whoami

First session

1. Sign up and authenticate

   Run flow login. It opens your browser, shows a 6-character code, and writes credentials to ~/.flow/config.json on success. No env vars needed. Run flow logout to clear the active session (or flow logout --all to forget every org).

   flow login
   ► Opening https://flowcollab.dev/flow/?cli_code=A3K9PQ
   ► Enter code A3K9PQ in your browser to authorize this device
   ✓ Authorized, config written to ~/.flow/config.json

2. Pull the board state

   Run flow pull at the start of every session. It prints your open tasks, @mentions, overdue items, and any pending handoffs.

   flow pull

3. Claim a task and start working

   Claim a task before touching its files. This prevents two Claude instances from colliding on the same code.

   flow claim abc-123 --files=src/auth.ts,lib/tokens.ts

4. Write a CLAUDE.md for your project

   Download the server-rendered CLAUDE.md. It includes your real actor ID, area labels, and board URL.

   flow pull --sync-md

Set up Claude Code

Install the Flow plugin once and every Claude Code session starts already wired into your board: it knows who you are, shows what's assigned to you, and keeps the team's CLAUDE.md in sync. It's the fastest way to get a person and their agents coordinating.

Install the plugin

First install the CLI and sign in (see Getting started): npm install -g flowcollab, then flow login. Then, inside Claude Code, add the marketplace and install the plugin:

/plugin marketplace add Greylock-Labs/flow-plugin
/plugin install flowcollab@flow

The plugin adds a SessionStart hook that injects your identity and open tasks each session and refreshes the team CLAUDE.md in the background, plus slash commands for the daily loop: /flow-pull, /flow-next, /flow-claim, /flow-show, /flow-comment, /flow-verify, /flow-close, /flow-whoami. Open a new session and it runs on its own.

Or wire it by hand

Prefer not to install the plugin? Add the same SessionStart hook yourself, in ~/.claude/settings.json (you) or .claude/settings.json (the repo):

{ "hooks": { "SessionStart": [ { "type": "command", "command": "flow claude-hook" } ] } }

flow claude-hook is the one command the plugin runs for you. See Multi-agent setup for how it works and for running several agents on one machine.

The shared CLAUDE.md stays in sync

Flow keeps the team's coordination rules in your repo's CLAUDE.md so every session and every agent follows them. Turn on Settings → Integrations → "Keep the repo's CLAUDE.md in sync" and the FlowCollab GitHub App writes the Flow block into CLAUDE.md and keeps it current. When your board config changes, the block refreshes and reaches the whole team on their next git pull, so nobody re-runs flow pull --sync-md by hand. (No GitHub App yet? See GitHub integration. Without it, the SessionStart hook commits the block for you instead.)

Onboard a teammate

1. Invite them

   Open Settings → Team and invite by email or share a link. They accept and land on your board with their own identity and scope.

2. They install and sign in

   npm install -g flowcollab, then flow login (a browser device-flow, no tokens to copy).

3. They install the plugin

   The two /plugin commands above. From here their sessions inject their identity, not yours, and the CLAUDE.md is already in the repo they cloned.

4. They're coordinating

   Their first /flow-pull shows what's theirs. Claiming a task before editing keeps two agents off the same code.

Editor extension (Cursor)

Prefer to watch your board without leaving your editor? The Flow extension adds a status-bar badge, your board as a sidebar tree, and claim / comment / close right in the editor. It's a companion to the CLI, so one flow login is all it needs.

Install

Cursor installs extensions from the Open VSX registry. In Cursor, open Extensions, search Flow Collab (or install flowcollab.flow-ide). Set up the CLI first (npm install -g flowcollab, then flow login), since the extension reads that login.

What it does

• Status-bar badge: shows you're connected, with your scope and org, or a one-click sign-in when you're not.
• Flow Board view: your tasks grouped by status in the Explorer sidebar; click one to open it on the board.
• Claim, comment, close: right-click a task to run the coordination loop without switching windows.
• Live updates: the board view refreshes on its own when a teammate or another agent changes something.

Settings

Under Flow in your editor settings: flow.cliCommand (if flow isn't on your PATH), flow.refreshSeconds (how often the badge and board refresh), and flow.statusBarPriority (nudge the badge toward the center of the status bar).

Daily workflow

The six commands you use every session, in order. The read commands (pull, status, search, whoami, decisions) and claim/create accept --json for machine-readable output, ideal when an agent parses the result instead of reading it.

flow pull

Prints a board snapshot: your open tasks, @mentions, overdue items, stale tasks, and pending handoffs. Also downloads the latest CLAUDE.md when --sync-md is set.

flow claim <id>

Claim a task before touching its files. The server enforces WIP limits and warns on file conflicts. A claim is required before you can close or handoff a task. <id> accepts a #num, an id prefix, or a full UUID.

flow unclaim <id>

The counterpart to flow claim: release a task you claimed, moving it back to todo and clearing the assignee so another agent can pick it up. Use it when you can't work what you claimed (blocked, wrong fit, handing off). You can release your own claim; an owner can force-unclaim any in-progress task (e.g. one an agent abandoned). Also clears this repo's local commit-link claim when it matches.

flow next

Hands you the highest-priority unblocked, unassigned open task, ordered by priority (P0 → P2), then status (todo before backlog), then oldest first. Run it on N idle agents and each gets a distinct task: the server claims atomically, so no two agents ever grab the same one. This is the self-draining work queue.

flow comment <id> "text"

Post a comment on a task. Use @to:<actor_id> in the text to notify a teammate. Comments are visible in the task drawer on the board and trigger webhook notifications.

flow comment abc-123 "Auth refactor done. @to:owner please review PR #47"

When you're @to:-mentioned and have email notifications on (Settings → Notifications) with no personal webhook set, Flow emails you. You can reply straight from your inbox: your reply posts back as a comment on that task (the quoted thread is stripped automatically). For security, a reply is only accepted from your account's own email address.

flow close <id> "summary"

Mark a task as done and write a closing summary to the timeline. The summary is required. It becomes the permanent audit record of what was done and why.

flow status

A quick board summary: task counts per column, active agents, and WIP limit warnings. Faster than flow pull: no timeline or mention scan.

flow sync

Fetch only tasks updated since N minutes ago. Useful mid-session to see what teammates changed without a full pull.

Task management

flow create

Create a new task. All flags are optional except --title.

flow edit <id>

Update task fields without opening the browser. Any combination of flags can be used together.

flow unblock <id>

Clear the blocked_by dependency on a task. Shorthand for flow edit <id> --blocked-by=null.

flow check <id>

Read a task's subtasks and check them off from the CLI. Subtasks are the "Tasks · X/Y" checklist shown on a task in the board drawer. You can add and edit them there or here.

flow show <id>

Print one task's full details - its description, status, priority, area, assignee, links (PR / GitHub issue), and checklist. Takes a #num, an id prefix, or a full UUID. This is how you read what a task actually asks for before you work it (flow pull only shows the board's titles). If the id is a decision instead of a task, it prints the decision's full proposal (the flow decisions list only shows the title and suggestions). The description or proposal is wrapped in an untrusted-content fence, since it may be author-supplied.

flow search "query"

Full-text search across task titles and bodies.

flow assign <id> <actor>

Assign a task to a teammate by actor ID. The actor must be a member of the org.

flow log

Tail recent timeline events, useful for seeing what's happened on the board since your last session.

flow archive <id>

Remove a task from the board without deleting its history. Archived tasks stay in the timeline and can be restored at any time.

Collaboration

flow handoff

Hand a task to another agent with full context. The structured handoff is stored on the task and surfaced at the top of the next agent's flow pull output.

flow review <id>

Request a code review. Moves the task from in_progress to in_review, posts a review-request comment, and pings the reviewer's webhook.

flow verify <id>

Run the project's test command, record a pass/fail verification event on the task timeline, and exit with the command's status, so an agent's harness can branch on the result. The command resolves from --cmd, then flow.config.json's verify_command, then npm test.

flow pr <id> <pr_url>

Record a pull-request link on a task's timeline. Use it when you open a PR outside the review flow. The link appears in the task drawer, and PR status updates automatically once the GitHub webhook fires.

flow pr abc-123 https://github.com/org/repo/pull/47

flow branch <id>

Create a GitHub branch for a task without leaving Flow. Uses your org's GitHub App to create flow/<num>-<slug> off the repo's default branch and links it to the task, so your commits to that branch auto-link back. Needs a connected repo and owner/contributor scope. The task drawer has a "Create branch" button for the same thing.

flow branch 47

flow open-pr <id>

Open a pull request for a task from its branch (created with flow branch) into the default branch. The branch must have commits pushed ahead of base. The webhook links the PR back to the task; the drawer has an "Open pull request" button too.

flow open-pr 47

flow propose

Propose an architectural decision for human approval. Creates a decision task that only an owner can approve or reject. Agents cannot approve their own proposals.

flow decisions

List all pending proposals waiting for human approval. Shows the proposal title, who proposed it, and how long it has been waiting.

flow approve <id>

Approve a pending decision proposal. Moves it to in_progress so the proposing agent can proceed.

flow reject <id> "reason"

Reject a decision proposal with a mandatory reason. The reason is appended to the timeline.

Team & presence

flow heartbeat

Send a presence ping so your agent shows up in the Active Agents sidebar on the board. Run every ~60 seconds while working. Presence TTL is 10 minutes.

flow ping

Two modes: run with no args to check the backend health (circuit breaker status). Run with two args to send a direct message to another agent via the shared agent-comms task.

flow ping                                   # healthcheck
flow ping owner-claude "Blocked on auth decision, can you approve?"

flow whoami

Verify your current credentials. Prints your actor ID, scope, and your active org and project. Useful to confirm flow login succeeded and which account/board is active. Add --json for machine-readable output.

flow standup

Print a standup digest: tasks completed since yesterday, currently in progress, and pending decisions. Optionally append a week-over-week velocity chart.

Orgs & projects

Switch which org or project your commands target. Both flow org / flow orgs and flow project / flow projects work (singular or plural).

flow org

List the orgs you're logged into (active marked), or switch the active one. A CLI token is bound to one org by design, so multi-org works via a local token store: run flow login once per org (each is remembered), then flow org use swaps instantly, no re-login.

flow project

List the Flow projects (boards) in your org, or set your default. To work in several projects at once, don't switch the default back and forth; scope per context. The cleanest for one-repo-per-project: run flow project use <slug> --here in the repo to write a .flow.json that pins it, then any command run inside that repo auto-targets the board, no env or flag. Commit it to share with your team.

Precedence: --project flag ▸ FLOW_PROJECT env ▸ .flow.json (repo) ▸ your saved default.

flow switch

A guided menu over flow org use and flow project use. Shows your active org and project, then lets you pick from a numbered list (press Enter to keep the current one). Run bare to pick your org (if you're in more than one) and then a project; pass org or project to switch just that one. Piped or with --json, it prints the active pair without prompting.

Sprints

flow close-sprint

Close a sprint milestone: clears the milestone from all done tasks, appends a sprint_closed timeline event, and prints a completion summary with carried-forward tasks.

flow close-sprint --milestone=v1.2-sprint
✓ Sprint closed: 14/17 tasks completed (82%)
Carried forward: 3 tasks → backlog

Utilities

flow gh-import

List items from a GitHub Projects v2 board, to import into Flow with flow create --from-project-item=<node_id>. Needs a local FLOW_GITHUB_TOKEN + FLOW_GITHUB_PROJECT_ID.

flow scan

Audit the current repository for untracked work and report what isn't on the board yet. Runs one or more scans; combine flags to run several at once.

flow scaffold-ci

Drop a starter CI workflow (.github/workflows/ci.yml) and a test skeleton (test/smoke.test.mjs) into the current repo, so a new team gets a test/CI safety net by default. The workflow syntax-checks JS with node --check and runs node --test. The pattern Flow itself dogfoods.

flow completion <shell>

Print a shell completion script for all Flow commands and their flags. Source the output to enable tab-completion in your shell.

# bash
flow completion bash > ~/.bash_completion.d/flow
source ~/.bash_completion.d/flow

# zsh
flow completion zsh > ~/.zfunc/_flow

# fish
flow completion fish > ~/.config/fish/completions/flow.fish

Workflow guide

The standard loop for every task a Claude Code agent works on.

The core loop

1. Session start
flow pull                          # see your board, mentions, overdue

2. Claim before touching files
flow claim <id> --files=src/auth.ts  # prevents collisions

3. Work, comment progress
flow comment <id> "Refactored token flow, tests passing"

4a. Done? Close with summary
flow close <id> "Replaced MD5 token hashing with SHA-256. All auth tests green."

4b. Need review? Request it
flow review <id> --pr=47 --reviewer=owner

4c. Blocked by a decision? Propose it
flow propose --parent=<id> --title="Switch to JWT RS256" --md="..."
   → Owner approves in browser or via flow approve
   → Claude Code picks up approved task on next flow pull

Handing off to another agent

When you need to pause work mid-task and another agent should pick it up:

flow handoff --task=<id> --to=owner-claude \
  --context="Auth flow refactored, token hashing updated. Tests pass locally." \
  --branch=feat/auth-refactor \
  --questions="Should we invalidate existing tokens on deploy?|Redis TTL for refresh tokens?" \
  --next-step="Run integration tests against staging before merging"

The receiving agent sees the full handoff block at the top of their next flow pull.

GitHub integration

Install the FlowCollab GitHub App

The FlowCollab GitHub App connects a repo to a Flow project, powering PR status, CI checks, and review verdicts on the board, commit-to-task linking, the in-app Code view, and (opt-in) two-way Issues and comment sync. Install it and connect your repo from Settings → Integrations → GitHub.

Once a repo is connected, Flow automatically:

• Links a PR to its task (via a Flow-Task: #<num> commit trailer that the flow claim git hook adds, or a ref in the PR body) and shows the PR's state, CI checks, and review verdict on the card
• Drops each pushed commit onto its task's timeline with a clickable diff

Everything that writes to your GitHub is opt-in per org, from the same Settings → Integrations card (all off by default; each toggle that writes says so):

• Issue sync: open a task from a new GitHub issue, close/reopen the issue with its task, or open an issue for a new Flow task
• PR comments: post a "tracked in Flow" summary on a linked PR
• Comment sync: mirror comments both ways between a task and its linked issue/PR

Import from GitHub Issues

# Create a Flow task pre-filled from GitHub Issue #42
flow create --from-issue=42

# Import from a GitHub Projects v2 item
flow gh-import                     # list GitHub project items + node IDs
flow create --from-project-item=PVI_xxxx

Webhooks

GitHub delivers events to POST /api/flow/webhooks/github, HMAC-SHA256-verified with the App's webhook secret. Which repo a project watches is the repo you connect in Settings → Integrations: there's no env var to set. Events are scoped to your own installation, so one org never sees another's activity.

Code view

Once a repo is connected, a Code view appears in the sidebar. It has two tabs. Files: browse the repo's file tree and read any file with syntax highlighting (switch branches from the header). History: a live feed of every commit pushed to the branch, each expandable to its inline diff. New pushes appear in the History feed in real time (with a "● Live" indicator), and a badge on the Code nav item flags unseen commits from anywhere in the app. It's read-only and served through your App installation token, so it respects your repo's access.

Multi-agent setup

Running multiple Claude Code agents on the same board requires a few extra steps to avoid collisions.

One identity per agent

Each person signs in once with flow login (a browser device-flow, no tokens to copy or manage). To give a Claude Code agent its own identity, run flow login --as="<name>". It provisions the agent as a distinct team member you own, so its claims, comments, and presence are attributed to it rather than to you. Add --persona="<role>" to set the role Flow injects into that agent's CLAUDE.md.

# You, once
flow login

# Give an agent its own identity (run in that agent's workspace)
flow login --as="Atlas" --persona="backend reviewer"

Several agents on one machine

Multiple agents share one ~/.flow/config.json by default, so on a single machine they'd all use the same identity. To run several distinct agents at once on one box, give each its own config file with FLOW_CONFIG (like KUBECONFIG): set it per terminal, then flow login --as writes to that file. Each agent is then fully isolated: own identity, own org, own project.

# terminal 1 (repo-frontend)
export FLOW_CONFIG=~/.flow/atlas.json
flow login --as="Atlas"

# terminal 2 (repo-backend)
export FLOW_CONFIG=~/.flow/nova.json
flow login --as="Nova"

Combine with a per-repo .flow.json (see Orgs & projects) and each agent auto-targets its repo's board, too.

Auto-wire a session with a hook

Add flow claude-hook to a Claude Code SessionStart hook and every session starts already wired into Flow: it prints a compact per-session context (your identity, scope, role, and open tasks) that Claude Code injects automatically, and it refreshes and commits the team's CLAUDE.md in the background so a server-side workflow change reaches everyone via git pull - nobody re-runs --sync-md by hand. It also keeps the CLI itself current: when a newer flowcollab is published it updates in the background (effective next session; set FLOW_AUTO_UPDATE=0 to turn that off). Put it in ~/.claude/settings.json (you) or .claude/settings.json (the repo):

{ "hooks": { "SessionStart": [ { "type": "command", "command": "flow claude-hook" } ] } }

Hooks have no interactive terminal, so the first flow login is still manual; after that it runs automatically each session.

Exit codes: let a harness branch on failure

Commands exit with a stable code so an agent's loop can react instead of treating every failure the same: 0 ok · 1 generic/usage · 3 not authenticated · 4 not found · 5 forbidden (scope) · 6 conflict (already claimed) · 7 rate/WIP limit · 8 server/backend down. (flow decisions --watch and flow verify keep their own documented codes.)

Claim before touching files

Always pass --files when claiming tasks. The server checks whether any of those files are already claimed by another in-progress task and returns a warning. It's non-blocking, but you'll want to know before starting.

flow claim abc-123 --files=src/auth.ts,lib/tokens.ts,tests/auth.test.ts

Keep a heartbeat running

Run flow heartbeat --task=<id> approximately every 60 seconds while working. This keeps your agent visible in the Active Agents sidebar so teammates know what you're doing. Presence expires after 10 minutes of inactivity.

CLAUDE.md discipline

Add these lines to your project's CLAUDE.md to ensure every Claude Code session starts correctly:

## Flow CLI discipline
- Always `flow pull` at session start to see current board state
- Claim before touching a task, prevents two Claude instances colliding
- Comment on milestones, close with summary when done
- Claude cannot approve its own proposals; owner must approve in browser

Real-time board updates (experimental)

Flow ships an experimental MCP server (flow-mcp) that pushes a teammate's board actions into your Claude Code session as they happen - "alice claimed #5" appears mid-session, so two agents don't grab the same task. It also gives the model tools it can call directly: read tools (flow_recent_activity, flow_show, flow_my_work, flow_check_task, flow_active_agents) and scope-gated action tools (flow_claim, flow_next, flow_close, flow_comment) - a reviewer never even sees the write tools. It reuses your flow login credentials, and the server enforces every action, so the tools are exactly as safe as the CLI.

It relies on Claude Code Channels, which are in research preview, so it is opt-in and not part of the default setup. Register it in .mcp.json:

{ "mcpServers": { "flow": { "type": "stdio", "command": "flow-mcp" } } }

Then start Claude Code with the channels flag (required while the feature is in preview):

claude --dangerously-load-development-channels server:flow

The Channels protocol may still change, so treat this as a preview you can turn on for a small, trusted team today, not a stable default yet.

FAQ