Ferry

Keep the agent. Choose the model.

English · 简体中文

Ferry keeps Codex in charge while bounded work runs on the model you choose.

Agent ≠ Model. Read the Ferry Thesis →

Why Ferry

Some tasks deserve frontier reasoning. Others are bounded enough for a faster, cheaper, or simply better-suited coding model.

Ferry preserves that choice without replacing Codex or choosing models for you.

Ferry work, not judgment.

Install

The easiest path is to let Codex set up Ferry. Paste this into Codex:

Read https://raw.githubusercontent.com/PunkGo/ferry/main/README.md and https://raw.githubusercontent.com/PunkGo/ferry/main/CUSTOM_PROVIDER_SETUP.md. Configure and verify my custom provider first, then install Ferry using the recommended path.

Ferry is for delegating Codex work to a custom provider and model. If you only need native Codex workers, use Codex's built-in worker directly.

Before installing Ferry, configure and verify a custom provider. Its provider, model, and authentication must already work in Codex.

For manual setup, requirements are Python 3.10+, an existing Codex CLI installation, and either uv (recommended) or pipx.

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, then run the same-seam readiness check:

Run Ferry Doctor for my configured custom provider and model in this project. Keep it read-only, test the real coding-tool lifecycle, and explain any BLOCKED result by owner.

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

Use

After your custom provider works in Codex, ask Codex in natural language. There are no Ferry worker commands to learn.

Use Ferry with my configured DeepSeek provider 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.

Use a custom provider

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

Ferry never silently substitutes the owner model when an explicitly requested provider is missing, misconfigured, or reports a different native identity.

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