codex-host README

The project's README from github.com/BytePioneer-AI/codex-host. As one markdown file: README.md.

CodexHost

Run Pi and other Harnesses inside Codex Desktop

We believe Codex Desktop offers the best desktop development experience today.

But Codex isn't the only great Agent Harness — Claude Code and Pi are great too.

CodexHost lets you run other Harnesses natively inside Codex Desktop and have them work together.

⭐ If CodexHost is useful to you, please give it a star! ⭐

Pi Codex Claude Code OpenCode Grok Oh My Pi
DSH AGY Kiro CLI CodeBuddy WorkBuddy Cursor Hermes Qoder Kimi Code


Download · Cross-Agent Collaboration · Remote · Community · 简体中文 · 한국어


Interface Preview

No more switching apps: Pi, Claude Code, Grok Build, and ten-plus other Harnesses all run right inside the same Codex Desktop window.

https://github.com/user-attachments/assets/c48192d7-23ff-4f6e-b61a-6345a655bb76

Interface

Claude Code, Pi, Grok Build, and Oh My Pi sessions running in Codex Desktop, with Diff review, Fork, Worktree, and Agent switching

Quick Start

Option 1: npm (macOS / Windows / Linux)

npm install -g @codexhost/cli
codexhost

Option 2: Installer (macOS / Windows)

Grab the installer for your platform from Releases.

Linux is supported on x64 and ARM64. See the Linux guide.

Installation troubleshooting

macOS: "App can't be verified" on first launch

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

Windows: using a portable Codex Desktop

  1. Point CODEXHOST_INSTALL_ROOT at the folder where you extracted Codex Desktop:

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

  2. Quit Codex Desktop completely, open a new terminal, and run codexhost.

Highlights

Full workspace
Sessions from different Harnesses share one sidebar; switch Agents from the bottom-right of the composer

The complete CodexHost workspace in Codex Desktop, showing the project tree, conversation area, and multiple Agent selectors

Diff review panel
Every turn summarizes its changes; click Review to open the full Diff on the right

Change summary card in the conversation and the full Diff in the review panel

Fork from any message
Branch in the current workspace, or in a new Worktree for parallel work

Menu for creating a branch from a message, in this workspace or a new worktree

Delegate to other Agents with #
Each Agent runs in its own session, in parallel · Learn more

Typing # to pick Codex, Claude Code, Grok and other Agents, each task running in its own session

Tool calls and thinking
Expand any edit, command, or thinking step to see the details

An expanded edit entry showing the Diff of a newly created file

Visible Subagents
Each Subagent has its own icon; open its full conversation on the right

Status of 4 Subagents in the main conversation, with one opened on the right

Remote development
Add a VPS as a project and run Agents directly on the remote machine · Learn more

A remote VPS project in the sidebar, with the conversation returning the remote working directory

Usage at a glance
Cache hit rate, cost estimate, and context usage, live

Usage popover: context, cache hit rate, cache reads and writes, total tokens, cost estimate

One-click account import
Copy your locally signed-in Codex and Grok credentials to Pi, with live quota

Account settings: 5-hour and 7-day remaining quota, and accounts imported into Pi

Mermaid diagram rendering
Left: Codex Desktop + Pi renders the diagram; right: the Pi TUI only shows the source

Comparison of Mermaid diagram rendering between Pi with Codex Desktop and the Pi Agent TUI

Feature Status

Every Harness gets Codex Desktop's native Edit Diff, Fork, message editing, and slash commands.

Show full feature matrix
Capability Pi Oh My Pi Claude Code OpenCode Grok DSH AGY CodeBuddy WorkBuddy Cursor Hermes Qoder Kimi Code
Streaming responses ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Tool status ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Edit Diff ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Questions / cancellation ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Model / Thinking selection ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Tool approvals ✅ ✅ ✅ ✅ ✅ ✅ — ✅ ✅ ✅ ✅ ✅ ✅
Permission modes — ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Cross-Agent task collaboration ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ — ✅ ✅ ✅ ✅
Usage ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ — ✅ ✅ ✅
Fork ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ◐
Context compaction ✅ ✅ ✅ ✅ ✅ ✅ — ✅ ✅ — ✅ ✅ ✅
Slash commands ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Edit previous message ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅

Cross-Agent Collaboration

Type # in the chat input to choose an Agent to delegate a task to, or to find commands and skills available for the selected Harness.

Ask the current Agent to hand off a self-contained task to another Harness. For example:

Have #claude-code review this change on its own and flag any compatibility risks.

Have #pi figure out why this test is flaky.

Have #omp implement this feature while I keep working on the docs.

Have #opencode verify this fix in a separate Thread and run the related tests.

CodexHost spins up a separate Native Session in the target Harness. It shows up in the Codex Desktop conversation list, so you can open it anytime to check progress or pick up the conversation.

Remote Harness

Drive Harnesses on another machine from your local Codex Desktop: tasks run remotely, the UI stays local. Both machines need the same codexhost version.

Remote machine How to connect
macOS / Linux SSH
Windows Remote Control (experimental)

SSH

Before you start, add the remote machine in Codex Desktop under Settings → Connections → SSH. Your local machine can run macOS, Linux, or Windows.

SSH connections added under Settings → Connections → SSH in Codex Desktop

  1. Install and start codexhost on the remote machine:

    npm install -g @codexhost/cli
codexhost remote install
codexhost remote start
codexhost remote status

  2. On your local machine, launch Codex Desktop through codexhost and open the SSH workspace.

  3. Pick a Harness from the composer's Agent / Model selector.

SSH setup, diagnostics, and uninstall →

Remote Control (Experimental)

Use Harnesses on a Windows machine from another computer, built on the pairing and sign-in of Codex Desktop's official Remote Control.

Before you start, make sure official Remote Control can already run Codex tasks. No public services or ports are opened, and Harness credentials never leave the Windows machine.

Remote Control setup, transport boundary, and diagnostics →

How it works

Most multi-agent clients build their own chat UI and plug Harnesses in through a common protocol.

CodexHost does it differently:

  • Desktop: extends the official Codex Desktop via CDP / Electron Inspector — no rebuilt chat UI, no patched installer.
  • Protocol: a CLI Shim sits in front of the official app-server and passes native Codex requests through untouched.
  • Harnesses: each Harness is integrated through its own native interface where one exists (Pi over RPC, Claude Code via the Agent SDK), falling back to ACP otherwise. Streaming, tool status, diffs, approvals, and questions all render in Codex Desktop's native UI.
  • Orchestration: delegated tasks run as independent native sessions in the target Harness; the caller can wait for the result or let it run in the background.

Join the Community

Join the Community
Scan the QR code to join our WeChat group and chat about CodexHost.
  • Get help with installation
  • Share feature ideas and feedback
  • Talk about development
  • For bugs, please open an issue
Contributions are welcome. 		WeChat group QR code

Development

Please read the contributing guide before opening an issue or PR. See repository maintenance automation for PR title labels, CI summaries, and pre-release checks.

Requirements: the official Codex Desktop, Node.js 22.19+ or 24, and Rust.

git clone https://github.com/BytePioneer-AI/codex-host
cd codex-host
npm ci
npm start

Runtime Architecture

Using Pi as an example, here is how a single request flows from left to right: Desktop → shared layer → Pi plugin → native process.

Runtime architecture using Pi: Desktop to the shared layer, then the Pi plugin and native process

Adding a Harness

Most of the work is implementing the plugin's Manifest, factory, Adapter, and Session, plus the native communication and translation logic. The Renderer still has some hard-coded wiring, so full Desktop integration takes extra work.

Tip: point your coding Agent at the in-repo codexhost-add-harness Skill. It covers plugin structure, the shared Adapter interface, capability implementation, and testing requirements.

Acknowledgements

Star History

Star History Chart

codex-host (BytePioneer-AI/codex-host)

Searching Database…

2.9K ·GitHub
Codex-host
Что это?CodexHost позволяет запускать другие агентские харнессы, вроде Pi и Claude Code, нативно внутри приложения Codex Desktop, чтобы пользоваться ими вместе без переключения окон.
Это отдельное приложение или оно встраивается в Codex Desktop?Это не переписанный чат-клиент — он расширяет официальное приложение Codex Desktop через CDP/Electron Inspector, поэтому нативный интерфейс остаётся нетронутым, а пропатченный установщик не нужен.
Нужно ли, чтобы Codex Desktop уже был установлен?Да, CodexHost оборачивает официальное приложение Codex Desktop, так что оно должно быть установлено заранее; для сборки из исходников дополнительно нужны Node.js 22.19+ или 24 и Rust.
Все харнессы поддерживают одинаковый набор функций?Нет, матрица функций показывает, что у некоторых харнессов нет подтверждения инструментов, режимов разрешений, межагентского сотрудничества, отслеживания использования или сжатия контекста, а Windows-режим удалённой работы всё ещё помечен как экспериментальный.
На каких операционных системах его можно запускать?Установка через npm работает на macOS, Windows и Linux, причём Linux — и x64, и ARM64; готовые установщики есть только для macOS и Windows.
Как заставить одного агента передать задачу другому?Введите '#' в поле чата, чтобы выбрать харнесс и делегировать, например 'Пусть #claude-code сам проверит это изменение'. Он развернёт отдельную нативную сессию в этом харнессе, состояние которой можно проверить в любой момент.
Можно запускать харнессы на удалённой машине или VPS?Да, можно добавить удалённую машину как проект. Удалённые машины macOS/Linux подключаются по SSH, Windows использует экспериментальный режим Remote Control, и в обоих случаях интерфейс остаётся локальным, а задачи выполняются удалённо.
Какие агентские харнессы он реально поддерживает?Pi и Claude Code получают нативные интеграции (Pi по RPC, Claude Code через Agent SDK), а в README упомянуто ещё более десяти харнессов, включая Grok Build и OpenCode, — при отсутствии нативного хука используется протокол ACP.
What are similar projects?munder-difflin, shipyard, pi-harness, openrig, ruflo, PI-Desktop, deer-flow, qwen-code
Which topics is it in?pi-agent, lgpl, remote-access, vps, agent-harness, agentic, ai-tools, ssh, harness, orchestration, agent-orchestration, electron
Creator
BytePioneer-AI
Size
46.7 MB
Stars
2.9K
Updated
CommitOct 13Releasev0.13.2Oct 11
Age
2mo
Commits · 90 Days