1
Install and start Flowfield
Install the Open localhost:8765 in your browser. You should see an empty board. Keep this terminal open — Ctrl-C stops the service. See Installation for the pip alternative and PATH troubleshooting.
flowfield-core package using uv with Python 3.12, then start the local service:2
Initialize your project
Open a second terminal and change to an existing project directory. Run the setup commands:
flowfield project init registers your directory with Flowfield and creates .flowfield/config.toml. flowfield project guidance install adds a coordinator skill reference at .agents/skills/flowfield-coordinator/SKILL.md, preserving any existing agent instructions alongside it.Review both generated files, then commit them to your project using your usual workflow:Commit the generated files before running workers. Workers check out your project from Git, so uncommitted changes will not be visible to them.
3
Connect Codex
Still in your project directory, connect the Codex integration and verify it:This registers the MCP connection that allows your Codex coordinator to read and write Flowfield data. Codex CLI must already be installed and you must be signed in — Flowfield uses your existing Codex login and does not manage credentials.To verify the connection end-to-end, start a fresh Codex conversation in your project directory and ask:
Read this project’s Flowfield board and give me its link.The coordinator should identify your project and return its board link. If it does not, see the Codex integration guide for connection checks and troubleshooting.
4
Configure workers
Before running tasks, your project needs a worker configuration: a target branch, a dependency setup command, verification commands (tests, linting), and a worker model. Ask your coordinator in the Codex conversation:
Configure Flowfield worker execution for this project. Set the target branch, dependency setup command, verification commands, and choose a worker model and reasoning effort.Alternatively, open the browser UI, find your project, and click the settings icon beside the project name to configure these values directly in the Workers settings panel.
5
Run your first task
Describe a small, self-contained change to your coordinator and ask it to capture the task:
Add a --quiet flag to the CLI that suppresses non-error output. Capture this as a Flowfield task with success criteria.
Open the task’s feed in the browser to read the agreed definition. When you are satisfied, move the task to Up Next using the board controls.Click Run Queue to enable the queue. The task will move to In Progress as a worker starts in an isolated Git checkout.Monitor progress in the task feed. If the worker posts a question, answer it directly in the feed — your saved answer lets the service continue automatically.When the task reaches In Review, read the result and its verification output. Inspect the diff, or click Try result to test an independent copy of that exact version. Record any testing observations in the feed. When you are satisfied, click Approve and Integrate.Flowfield delivers the approved code to your configured branch and marks the task Done.The worker queue starts paused — tasks will not run until you click Run Queue in the browser or run
flowfield project workers run from the CLI. The queue also starts paused after every service restart, giving you a chance to review the board before new work begins.What’s next?
Core Concepts
Understand tasks, feeds, the board, dependencies, results, and the review workflow in depth.
Codex Integration
Detailed connection setup, MCP configuration, troubleshooting, and coordinator prompting tips.
Running Workers
Configure worker models, parallel slots, dependency setup, and verification commands.
CLI Reference
Full reference for every
flowfield command and its flags.