CodexHost: Running Pi, Claude Code and Other Harnesses Inside Codex Desktop

The problem CodexHost solves is harness lock-in inside one window

Codex Desktop is a single application with a single agent behind it. The README states the project's premise plainly: Codex Desktop offers what the authors consider the best desktop development interaction experience, but Codex is not the only good agent harness, and some developers prefer Claude Code or Pi Agent. Those preferences normally cost you the interface. You either stay in Codex and give up the other harness, or you leave Codex Desktop and run the other agent in its own terminal.

CodexHost removes that choice. It presents itself as a layer that lets you select which agent actually executes a task while keeping the Codex native experience, and it adds the ability for those agents to hand work to each other. The target reader is someone who already lives in Codex Desktop and has a reason to use more than one harness: a model that behaves differently on a class of problem, a harness with a feature the default lacks, or a second opinion on a change. If you have no such reason, the project has nothing to offer you.

How the adapter architecture routes a task to a different harness

The repository layout shows the mechanism. The npm workspace declares packages/* and packages/adapters/* as workspaces, so each supported harness lives in its own adapter package. The build script named build:plugins runs scripts/release/harness-plugins.mjs and writes its output to packages/host-runtime/dist/plugins. A separate Rust workspace builds four crates named codexhost-launcher, codexhost-platform, codexhost-shim and codexhost-updater.

That split suggests where each concern sits. The Rust launcher and shim sit between Codex Desktop and the host process, which is consistent with the Windows portable-build instructions that point the launcher at an extracted Codex Desktop directory. The TypeScript side holds the harness adapters and the host runtime. A renderer extension package, built by the build:renderer script, supplies the in-app UI.

When you delegate, the README says CodexHost creates a separate Native Session for the target harness. That session appears in the Codex Desktop session list, so you can open it, watch progress, or continue the conversation later. Delegation is not a background function call that returns a string; it is a first-class thread you can inspect.

Installing CodexHost on macOS and Windows

The README documents a packaged installer rather than a source build. Go to the latest release and download the asset matching your operating system and CPU architecture: a DMG for macOS, an EXE for Windows. There is no npm install command in the quick-start section, and the package.json is marked private, so the published npm scripts are for building the project from source, not for end users.

On macOS, the README notes that the first launch may report that the app cannot be verified and gives this command to clear the quarantine attribute:

xattr -dr com.apple.quarantine /Applications/codexhost.app

After that, launching the app should open Codex Desktop with the harness selection available. If you are on Windows and use the portable extracted build of Codex Desktop rather than an installed one, set the CODEXHOST_INSTALL_ROOT environment variable to the extraction directory before starting anything:

[Environment]::SetEnvironmentVariable("CODEXHOST_INSTALL_ROOT", "D:\CodexPortable", "User")

The README is explicit about the sequence: fully quit Codex Desktop, reopen the terminal, then start codexhost. Setting the variable while Codex Desktop is running will not take effect.

The first real use is delegation. Open a thread and ask the current agent to hand a task to another harness by name, for example asking claude-code to review a change independently and flag compatibility risks, pi to investigate a flaky test, omp to implement a feature, or opencode to verify a fix in a separate thread and run the related tests. The result should appear as a new session in the session list.

The feature matrix is honest about what each harness loses

The README includes a capability table covering Codex, Pi, Oh My Pi, Claude Code, OpenCode, Grok, DeepSeek Harness, AGY, CodeBuddy, Cursor, Hermes and Qoder. Reading it as a buyer rather than a marketer is worthwhile, because the gaps are specific.

Oh My Pi is marked as lacking question prompts and tool approval. Cursor and Hermes are marked as lacking Edit Diff. AGY, CodeBuddy, DeepSeek Harness and Qoder are marked as lacking agent-to-agent task collaboration. Context compaction is absent for AGY, CodeBuddy, Cursor and Qoder. Slash commands and message revision are absent for those same four. Permission modes are the one row where Pi is marked as unsupported while most others are supported.

So the claim that you keep the Codex native experience holds for the interface, not for every capability of every harness. If your workflow depends on tool approval prompts, delegating to Oh My Pi removes them. If it depends on slash commands, four of the listed harnesses will not give you that. Codex itself is marked native across every row, which is the correct baseline: the fallback is always the unmodified experience.

Remote harness connections and the limits of the quick-start guide

The README's navigation lists a section on remote harness connections, which implies a harness does not have to run on the same machine as Codex Desktop. That is the extent of what the quick-start section shows; the README does not include the configuration format for a remote target, so there is no command or config key to reproduce here. Anyone planning a remote setup should read that section in full before assuming the local install steps carry over.

The larger limitation is platform coverage. The install instructions name macOS and Windows only. The package.json engine field requires Node 22.19 or newer below 23, or Node 24 below 25, and the Cargo workspace pins Rust 1.97.1 with edition 2024, so building from source is possible but demands a current toolchain. There is no documented Linux installer, and the release assets described are DMG and EXE.

The second limitation is that CodexHost is a layer on top of another application. The Windows instructions for the portable build show how tightly it is coupled to a specific Codex Desktop installation directory. If that directory moves or the desktop app changes its layout, the launcher's assumptions about it can break. The project ships a codexhost-updater crate, which suggests updates are handled in-process, but the README does not document rollback to a previous version.

CodexHost compared with running each harness in its own terminal

The alternative most readers already use is running each agent separately: Codex Desktop for Codex, a terminal for Claude Code, another terminal for Pi. The difference is not the agent, it is where the session lives.

In the separate-terminal approach, each harness owns its own window, its own scrollback, and its own session history. Nothing is shared. You copy a diff from one to the other by hand. CodexHost instead creates the delegated session inside Codex Desktop's session list and keeps it there, which is what makes the cross-agent handoff in the README possible: one agent asks another to review a change, and the review shows up next to the work it reviews.

The trade-off is dependency. A separate terminal has no coupling to Codex Desktop at all. CodexHost only works when Codex Desktop is installed and the launcher can find it, which is why the portable-build instructions exist. If you value harness isolation over shared session history, the terminal approach is simpler and has fewer moving parts. If you value seeing every agent's work in one list, CodexHost is the only one of the two that offers it.

Licence, maintenance and what an upgrade costs you

CodexHost is MIT licensed, and the package.json carries the same MIT identifier. That is a permissive licence: you can use, modify and redistribute the code, including in commercial settings, provided the copyright notice and permission notice are retained. The repository also contains a third-party directory, which is the place to look for bundled dependencies that may carry their own terms. Nothing here is legal advice; if you redistribute a packaged build, read the third-party directory yourself.

The last push to the main branch was on 2026-09-17, and releases v0.8.0, v0.8.2 and v0.9.0 appeared on 2026-09-13, 2026-09-14 and 2026-09-16. The version number is duplicated across package.json and the Cargo workspace at 0.9.0, and there is a release:prepare script that runs scripts/release/prepare-version.mjs, so version bumps are scripted rather than manual. That matters for upgrade cost: a single command updates both the npm and Rust version fields, which reduces the chance of the two drifting apart.

Upgrading the packaged app is not documented in the README. The presence of a codexhost-updater crate indicates updates are handled by the application, but the README does not describe how to pin a version or revert one. If you need reproducible builds across a team, plan to track the release tags directly.

Editorial conclusion

Adopt CodexHost if you already work in Codex Desktop and want to route individual tasks to Pi, Claude Code, OpenCode, Grok or another harness without leaving that window. Do not adopt it if you want a headless CLI, a Linux build, or a single agent you never switch away from; the README documents macOS and Windows installers only, and the feature matrix shows several harnesses missing tool approval or edit diff support. Verify your OS and CPU architecture against the release assets, and on macOS run the xattr command from the troubleshooting section if the first launch is blocked.

Frequently asked questions

Official sources

1. BytePioneer-AI/codex-host on GitHub
2. Issues
3. License: MIT
4. README
5. Releases