Skip to main content
Flowfield works with your existing projects — it doesn’t scaffold a new app. You register a directory, install a skill file that teaches your coordinator how to use Flowfield, and configure how workers should build and verify your code. Once set up, your coordinator can manage tasks and workers can implement them in isolated Git checkouts without touching your main working files.

​
Prerequisites

Before registering a project, make sure you have:
  • Flowfield service running (flowfield serve) with the browser open at localhost:8765
  • Git installed and available on your PATH
  • Codex CLI installed and signed in

​
Register the Project

1

Open a terminal in your project directory

Navigate to the root of the existing repository you want to register with Flowfield. All project commands discover the project from the current directory via .flowfield/config.toml.
2

Run flowfield project init

This registers the directory with Flowfield and creates a .flowfield/config.toml file containing the project identity. You can customise the registration with optional flags:
  • --id — set an explicit project ID
  • --name — set a display name for the project
  • --prefix — set a three-letter task key prefix (for example, APP produces keys like APP-1)
The task key prefix locks after the first task is created and cannot be changed after that point. Choose it carefully before you add any tasks.
3

Preview the guidance files

This shows you exactly what files will be added to your repository before you commit to installing them. Review the proposed AGENTS.md section and the coordinator skill file content.
4

Install the guidance

This adds two things to your repository:
  • .agents/skills/flowfield-coordinator/SKILL.md — the skill file that teaches your coordinator how to use Flowfield’s MCP tools
  • A reference block in AGENTS.md — so Codex loads the skill in every session
If you already have an AGENTS.md, Flowfield inserts its section without removing your existing instructions. The install is safe to re-run if guidance is updated.To check the current installation state at any time, run:
This reports whether guidance is installed, the current baseline reference, and which instruction files are present.To remove guidance that has not been locally edited, run:
This removes only content that Flowfield owns and leaves any local edits in place.
5

Commit the added files

Review the files Flowfield added, then commit them using your normal Git workflow:
Workers need a usable committed Git baseline before they can run. Leaving these files untracked blocks code delivery.

​
Connect the Codex Integration

Register Flowfield’s MCP endpoint with the Codex CLI so your coordinator can read and update the project board from within a conversation:
Verify the connection once the command completes:
A successful status check confirms the MCP endpoint is reachable and lists the available tools. If the check fails, see the Codex integration guide for troubleshooting steps.

​
Configure the Worker Environment

Workers need to know how to set up dependencies, run your checks, and where to deliver finished code. The easiest way to configure this is to ask your coordinator in a Codex conversation — describe your target branch, dependency setup command, verification checks, and run command, and the coordinator will apply the settings through MCP. Alternatively, configure these settings directly from the CLI:
Repeat --check for each verification command you want workers to run:
  • --target — the branch workers deliver approved code to
  • --setup — a command to install dependencies before running checks
  • --check — a verification command; repeat the flag to add multiple checks
You can also adjust these settings at any time via the Workers and Integration panels in the browser.

​
Verify Setup

Start a fresh Codex conversation inside your project directory and ask:
Read this project’s Flowfield board and give me its link.
The agent should identify your project and return its board URL. This confirms that the skill file was loaded, the MCP connection is live, and the coordinator can see your project’s tasks. A new conversation is required — open sessions do not reload guidance after installation.
Commit the generated .flowfield/ and .agents/ files before running workers. Managed work needs a usable committed Git baseline to start from. Untracked adoption files block code delivery.
Use flowfield project show to confirm the project is registered and see its current board state. Use flowfield project list to see all projects registered with your running service.