Ferry

Keep Codex as the lead. Delegate bounded work to your own models.

English · 简体中文

Ferry adds controlled worker delegation to Codex. Your main Codex session keeps the project context, scopes the task, and judges the result. Bounded execution can stay on a native Codex worker or run on an explicitly selected custom model such as DeepSeek.

If you like the lead-and-worker feel of Claude Code agent teams, Ferry brings that delegation pattern to Codex while letting workers use providers already configured on your machine. Ferry is not a second agent harness or a shared peer-to-peer team runtime. Codex remains the lead and final judge.

Ferry work, not judgment.

Why Ferry

Frontier models are worth using for hard reasoning, planning, and review. They are not always the economical choice for a bounded implementation task.

Ferry lets you keep the Codex harness you already trust and spend expensive model capacity where judgment matters. A lower-cost custom model can implement a focused change; Codex then inspects the real diff, runs the checks, and decides whether to accept, steer, rework, interrupt, or stop.

Before you install: prove the provider in Codex

First, follow the official Codex custom-provider guide to configure and test your provider. Ferry does not configure models, endpoints, authentication, or credentials. The exact provider, model, and authentication must already work in Codex before Ferry uses them.

Ferry's SDK-launched App Server does not select a CLI profile. The provider and authentication it needs must therefore be available from the base user config, normally ~/.codex/config.toml. On Codex 0.134.0 and later, --profile name overlays ~/.codex/name.config.toml; a provider defined only in that profile may pass codex --profile name while remaining invisible to Ferry. A profile may still select the model, reasoning level, or model catalog, but keep the shared provider/auth definition in the base config.

For a guided handoff, give Codex this custom-provider setup prompt.

DeepSeek example

After following the Codex guide and the official DeepSeek Codex guide, if your base configuration exposes a provider named deepseek, verify the same unprofiled seam Ferry will use. Replace the model id if your configuration uses a different one, and supply authentication through your configured Codex auth mechanism.

codex exec -s read-only \
  -c 'model_provider="deepseek"' \
  -m deepseek-v4-pro \
  'Reply with exactly DEEPSEEK_CODEX_OK.'

Continue only after this command, without --profile, returns DEEPSEEK_CODEX_OK. Ferry will never silently fall back to the owner model when an explicitly requested provider is missing, misconfigured, or reports a different native provider identity.

Install

Requirements: Python 3.10+, uv, and an existing Codex CLI installation.

Use exactly one package manager for Ferry. uv tool is the default path:

uv tool install ferry-codex
ferry setup

pipx remains a supported alternative; do not install the same Ferry package with both managers.

pipx install ferry-codex
ferry setup

Start a fresh Codex session. Ferry reuses your host codex executable; it does not bundle Python or install a second Codex CLI.

Use

Ask Codex in natural language. There are no Ferry worker commands to learn.

Delegate to a native Codex worker:

Use Ferry to delegate this bounded task to a native worker: update the parser,
run its focused tests, and do not touch unrelated files.

Delegate to the DeepSeek provider you already proved in Codex:

Use Ferry with my configured DeepSeek provider and deepseek-v4-pro for this
bounded implementation. Keep this Codex thread as lead and independently verify
the resulting diff and tests.

Correct or stop live work in the same conversation:

Steer the Ferry worker: preserve the public API and limit the change to src/parser.py.

Interrupt the Ferry worker now.

The worker's report is delivery data. Codex checks the actual worktree and runs the real acceptance commands before accepting it.

Manage the integration

ferry status

Close every Codex session using Ferry before upgrading or uninstalling.

uv tool upgrade ferry-codex && ferry setup

ferry uninstall && uv tool uninstall ferry-codex

With the supported pipx alternative, use:

pipx upgrade ferry-codex && ferry setup

ferry uninstall && pipx uninstall ferry-codex

These commands manage only the Ferry package and Codex plugin integration. They do not delete Codex threads, provider configuration, credentials, or project files.

Support and security

Ferry's native-worker, OpenAI, DeepSeek, steer, interrupt, uv/pipx lifecycle, and Windows paths have versioned conformance evidence. See SUPPORT.md for the exact tested matrix.

Report security issues through SECURITY.md. Contributions are welcome after reading CONTRIBUTING.md.

License

MIT