> ## 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.

# Codex Integration: MCP Coordinator and Managed Workers

> Install and connect the Codex CLI to Flowfield as an MCP coordinator, install project guidance, and configure managed workers for automated task execution.

Install the [Codex CLI](https://developers.openai.com/codex/cli/) and sign in before
starting. Make sure `codex` is available in the terminal where you run Flowfield. The
integration saves a native MCP connection pointing to `http://127.0.0.1:8765/mcp/` (or
the port you specify) in Codex's user settings.

## Connect the coordinator

<Steps>
  <Step title="Start Flowfield and connect">
    With `flowfield serve` running, register the MCP connection and verify it:

    ```sh theme={null}
    flowfield integration connect codex
    flowfield integration status codex
    ```

    `connect` verifies the service and saves a native MCP connection in Codex's user
    settings. The default connection name is `flowfield`. Repeated connections are
    idempotent. `status` checks reachability and tool discovery without starting a model
    turn. Other configured MCP connections remain intact.
  </Step>

  <Step title="Install project guidance">
    In your existing project's directory, preview and install its coordinator guidance:

    ```sh theme={null}
    flowfield project guidance preview
    flowfield project guidance install
    ```

    This adds `.agents/skills/flowfield-coordinator/SKILL.md` and a short reference in
    `AGENTS.md`, preserving any existing instructions. Review and commit the adoption
    files under your project's rules.
  </Step>

  <Step title="Verify the connection in Codex">
    Start a fresh Codex conversation in the project, inspect `/mcp`, and ask it to read
    your Flowfield board. This confirms the coordinator can use the connection and
    identify the correct project.
  </Step>
</Steps>

## Configure workers

Ask the coordinator to configure the project's target branch, dependency setup,
verification and run commands, then validate setup. Choose a model and reasoning effort
from the available catalog with `flowfield project workers models`, or use the **Reload
models** button if the service cannot find the latest available models. You can also use
the project's **Workers** and **Integration** settings in the browser.

Managed execution requires a usable committed Git baseline. Each worker receives an
isolated checkout and runtime environment. Keep project and service state outside shared
temporary directories for managed work. Workers can install project dependencies within
the configured environment; machine-wide tools and credentials are configured separately.

<Note>
  If the service cannot find Codex, restart it from a terminal with the correct `PATH`,
  then use **Reload models**. A missing executable and a missing login are separate setup
  problems — check both independently.
</Note>

## Disconnect

```sh theme={null}
flowfield integration disconnect codex
```

Restart Codex to unload the connection. Project state and saved work remain intact.

For a custom connection name or service port, pass the same options to `connect`,
`status`, and `disconnect`:

```sh theme={null}
flowfield --port 8770 integration connect codex --name flowfield-local
flowfield --port 8770 integration status codex --name flowfield-local
flowfield --port 8770 integration disconnect codex --name flowfield-local
```

<Tip>
  Use `--name` when you run multiple Flowfield instances or want to distinguish this
  connection from others in Codex's MCP list. The `--port` value must match the port
  passed to `flowfield serve`.
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.