> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowfield.sh/llms.txt
> Use this file to discover all available pages before exploring further.
# Flowfield Quick Start: Install, Connect, and Run a Task
> Install Flowfield, connect Codex, set up your first project, and run your first AI worker task — from zero to a reviewed result in one walkthrough.
This guide walks you through the complete first-use flow — installing Flowfield, connecting your Codex coordinator via MCP, initializing a project, configuring workers, and running your first task all the way through to an approved, integrated result. By the end you will have a working local Flowfield setup ready for day-to-day use.
Install the `flowfield-core` package using `uv` with Python 3.12, then start the local service:
```sh theme={null}
uv tool install --python 3.12 flowfield-core
flowfield serve
```
Open [localhost:8765](http://127.0.0.1:8765) in your browser. You should see an empty board. Keep this terminal open — Ctrl-C stops the service. See [Installation](/installation) for the pip alternative and PATH troubleshooting.
Open a second terminal and change to an existing project directory. Run the setup commands:
```sh theme={null}
flowfield project init
flowfield project guidance preview
flowfield project guidance install
```
`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:
```sh theme={null}
git add .flowfield/config.toml .agents/
git commit -m "Add Flowfield project config and coordinator skill"
```
Commit the generated files before running workers. Workers check out your project from Git, so uncommitted changes will not be visible to them.
Still in your project directory, connect the Codex integration and verify it:
```sh theme={null}
flowfield integration connect codex
flowfield integration status codex
```
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](/integrations/codex) for connection checks and troubleshooting.
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.
Start with a conservative model and one worker slot. You can increase **Maximum parallel workers** to 2 or more once you are comfortable with how tasks run.
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?
Understand tasks, feeds, the board, dependencies, results, and the review workflow in depth.
Detailed connection setup, MCP configuration, troubleshooting, and coordinator prompting tips.
Configure worker models, parallel slots, dependency setup, and verification commands.
Full reference for every `flowfield` command and its flags.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.