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.

DeepSeek example

After following the Codex guide, if your working provider is named deepseek, verify it directly through Codex. Replace the model id if your configuration uses a different one.

export DEEPSEEK_API_KEY="YOUR_KEY"

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

Continue only after Codex 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+, pipx, and an existing Codex CLI installation.

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.

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, 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