Roles
Flowfield keeps three roles clearly separated so that intent, execution, and approval never get conflated. You shape the direction of work. You set priorities on the board, answer questions workers raise, inspect results, and make the final call on what gets delivered. You interact through the browser UI, the CLI, or directly inside your coding conversation — but the decisions are always yours. The coordinator is your primary coding conversation — Codex, for example. You describe what you want, the coordinator captures the agreed work as tasks, reads the board to understand what’s ready, and helps you reason through results when review time comes. The coordinator connects to the Flowfield service over MCP. It maintains task intent; you control priorities and review. Workers are bounded agents that implement individual tasks. Each worker runs in its own isolated Git checkout, follows the task’s agreed definition, and submits a result when finished. The Flowfield service manages worker lifecycle — starting, monitoring, and stopping workers according to your queue settings.The Local Service
Runflowfield serve to start the Flowfield service on your machine. The service stores everything — projects, tasks, feeds, results, worker settings — in ~/.flowfield/. Nothing leaves your machine.
Once running, the service exposes two endpoints:
- Browser UI at localhost:8765 — your real-time board, task feeds, review controls, and queue management
- MCP endpoint at
http://127.0.0.1:8765/mcp/— the connection point for your coordinator agent
flowfield serve open while you work. Ctrl-C stops the service; the queue pauses automatically on restart.
Projects
A project is an existing directory that you register with Flowfield. Runningflowfield project init in that directory adds a .flowfield/config.toml file that identifies the project and stores its settings.
Project settings control the key details of how workers operate:
- Worker environment — how the worker checks out and sets up the codebase
- Model and reasoning effort — which AI model workers use and at what effort level
- Checks — commands that verify the worker’s output before it reaches review
- Delivery branch — the Git branch where approved code is integrated
The Task Lifecycle
Tasks move through five stages from capture to completion.1
Backlog
The coordinator captures new tasks here. Backlog tasks are defined but not yet prioritized for execution. Spend time here refining definitions and success criteria before moving work forward.
2
Up Next
Tasks you’ve decided to run move to Up Next. The order here drives the worker queue — tasks higher in the list start first when a worker slot is available.
3
In Progress
The service has started a worker for the task. The task feed shows live worker activity, questions, and stage updates. You can answer questions or stop the worker from here.
4
In Review
The worker has submitted a result. The task is waiting for your review — you’ll see it in Needs You. Read the report, inspect the diff, optionally try the result, then approve or request changes.
5
Done
You approved the result and Flowfield delivered the code to your configured checkout. Done is a strong signal: the agreed outcome is complete, including delivery.
Quick Links
Tasks & Milestones
How tasks express agreed outcomes, how milestones group work, and how dependencies control execution order.
Board & Queue
How the board organizes stages, how the worker queue works, and how Needs You surfaces required input.
Results & Review
What’s in a worker result, how the review workflow proceeds, and what Approve and Integrate does.
Integrations
Connect your coordinator agent and configure the MCP integration for your coding environment.