shemarlindie/subagent-extension-for-codex

Prompt: Chat, build something that lets Claude keep you in line.

Delegate tasks to Claude from Codex through a local MCP service, then follow, steer and review them in the Delegated Work panel. Claude runs through the Claude Agent SDK and the Claude Code harness.

And yes, some of us still use Codex.

Is this allowed? Yes, when you run it on your own computer for your own work. It uses your local copy of Claude Code and your own sign-in, and it never collects or stores your Claude credentials. Anthropic's usage policy for Claude Code and the Agent SDK covers this kind of individual use.

Note

Windows support is in progress and not ready for use yet.

This is an early release. Expect rough edges, and settings or behavior may change between versions. Please report problems in Issues.

Install

You need:

• Claude Code 2.1.285 or later, signed in. Run claude once and complete sign-in. See Claude Code CLI for how the extension finds it.
• Node.js 24 or later, with npm, on the PATH Codex starts with. Codex downloads the plugin with npm.
• Git.
• Codex CLI 0.162.1 or later, or a Codex desktop app with plugin marketplaces. CI installs the plugin with 0.162.1, and older builds are untested.

macOS is the primary platform. CI runs the full test suite on macOS and Linux. Windows CI covers builds, plugin installation, packaged-service checks and settings file exports.

Add the marketplace, then install the plugin:

codex plugin marketplace add shemarlindie/subagent-extension-for-codex
codex plugin add subagent-extension-for-codex@shemarlindie

After the first command, the plugin also appears in the Plugins directory of the Codex desktop app. You can also ask Codex to install it: "Install the Codex plugin subagent-extension-for-codex from the marketplace at github.com/shemarlindie/subagent-extension-for-codex."

Then approve a Git repository root with at least one commit. Use Add chat project in a chat's Delegated Work panel, or Manage projects… → Add project in the global panel. The plugin starts its local service the first time Codex connects.

While the service runs, you can also use the standalone console at http://127.0.0.1:17317. If that port is taken, see Service address to find the console. Sign in with the token in ~/.local/share/subagent-extension-for-codex/admin-token. Treat the token as a credential and keep it out of chats and commits.

Claude uses the host's Claude Code credentials. By default, it also loads user, project and local settings, including instructions, skills, hooks and MCP servers. The extension doesn't manage provider credentials. Read Configuration and permissions before changing execution authority or session restrictions.

Start a task

Start a task in any of these ways:

1. Ask Codex. Describe the work in a chat, for example "Have Claude review my uncommitted changes." Codex starts the task and, when the host supports it, opens Delegated Work on the task's Chat.
2. Open the chat's panel. Ask Codex to open Delegated Work. The panel lists the chat's tasks and offers Add chat project when the chat's repository isn't approved yet.
3. Use the sidebar. In the Codex desktop app, select Delegated Work in the sidebar to see tasks from every chat. New task starts one there.

Before you start:

• Tasks work in your checkout by default, including uncommitted changes. A worktree keeps a task's changes separate but isn't a security sandbox. The service never merges changes.
• The researcher, reviewer and security reviewer profiles only inspect by default.
• Usage and billing follow your Claude Code sign-in. A set ANTHROPIC_API_KEY takes priority over a subscription login. Shown costs are estimates at API list prices, and cost limits apply to these estimates. See authentication and costs.

See How tasks run for details.

Update

Codex checks the marketplace when it starts and installs new releases on its own. To check now:

codex plugin marketplace upgrade shemarlindie

The new version takes over from the running service once its running turns finish, and queued tasks carry over. See Updates and service handoff. Startup backs up the database before applying migrations. See Restore a backup.

To pin a version, add the marketplace at its release tag. A tag never moves, so Codex keeps that version:

codex plugin marketplace remove shemarlindie
codex plugin marketplace add shemarlindie/subagent-extension-for-codex@v0.1.0
codex plugin add subagent-extension-for-codex@shemarlindie

To follow new releases again, remove the marketplace and add it without a tag.

Prereleases such as v0.2.0-beta.1 are marked as prereleases on GitHub, and the repository's marketplace never lists them. To try one, add the marketplace at its tag.

Uninstall

codex plugin remove subagent-extension-for-codex@shemarlindie
codex plugin marketplace remove shemarlindie

The service exits once Codex stops the plugin and its tasks finish. To stop it sooner, run kill "$(cat ~/.local/share/subagent-extension-for-codex/service.pid)", which interrupts running turns.

Tasks, settings and worktrees stay in ~/.local/share/subagent-extension-for-codex. Delete that directory to remove them. Branches that tasks created stay in their repositories.

Troubleshooting

To connect a checkout over stdio or Streamable HTTP instead of installing the plugin, see Connect Codex from a checkout.

Documentation

Before working on the codebase, read in this order:

1. Architecture for runtime ownership and code boundaries.
2. Local development for choosing a development tool, and its checks.
3. The guide for the area you are changing, listed below.

Use and operate the extension

Develop and verify changes

Integrate providers and hosts

License

MIT. See LICENSE.