Metadata-Version: 2.4
Name: ferry-codex
Version: 0.1.2
Summary: Keep Codex as the lead while bounded work runs on your own models.
License-Expression: MIT
Project-URL: Homepage, https://github.com/PunkGo/ferry
Project-URL: Repository, https://github.com/PunkGo/ferry
Project-URL: Issues, https://github.com/PunkGo/ferry/issues
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp==2.0.0
Requires-Dist: packaging>=24
Dynamic: license-file

# Ferry

<p align="center">
  <strong>Keep Codex as the lead. Delegate bounded work to your own models.</strong>
</p>

<p align="center">
  English · <a href="README.zh-CN.md">简体中文</a>
</p>

<p align="center">
  <a href="https://pypi.org/project/ferry-codex/"><img alt="PyPI" src="https://img.shields.io/pypi/v/ferry-codex"></a>
</p>

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.

![Codex leads while Ferry routes bounded work to a native or custom-model worker](diagrams/ferry-cost-control.svg)

## Before you install: prove the provider in Codex

First, follow the official
[Codex custom-provider guide](https://developers.openai.com/codex/config-advanced#custom-model-providers)
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](https://github.com/PunkGo/ferry/blob/main/CUSTOM_PROVIDER_SETUP.md).

### DeepSeek example

After following the Codex guide and the official
[DeepSeek Codex guide](https://api-docs.deepseek.com/quick_start/agent_integrations/codex),
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.

```sh
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:

```sh
uv tool install ferry-codex
ferry setup
```

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

```sh
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:

```text
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:

```text
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:

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

```text
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

```sh
ferry status
```

Close every Codex session using Ferry before upgrading or uninstalling.

```sh
uv tool upgrade ferry-codex && ferry setup
```

```sh
ferry uninstall && uv tool uninstall ferry-codex
```

With the supported `pipx` alternative, use:

```sh
pipx upgrade ferry-codex && ferry setup
```

```sh
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](SUPPORT.md) for the exact tested matrix.

Report security issues through [SECURITY.md](SECURITY.md). Contributions are
welcome after reading [CONTRIBUTING.md](CONTRIBUTING.md).

## License

[MIT](LICENSE)
