Skip to content

README.ko.md

Latest commit

 

History

History
330 lines (245 loc) · 19.5 KB

README.ko.md

File metadata and controls

330 lines (245 loc) · 19.5 KB
Raw

CodexHost

Codex Desktop에서 Pi와 다른 Harness를 실행하세요

저희는 Codex Desktop이 현재 최고의 데스크톱 개발 경험을 제공한다고 생각합니다

하지만 Codex만이 뛰어난 Agent Harness는 아닙니다. Claude Code, Pi도 있습니다

CodexHost를 사용하면 Codex Desktop에서 다른 Harness를 네이티브로 사용하고, 서로 협업하게 할 수 있습니다

⭐ 이 프로젝트가 도움이 되었다면 Star를 눌러 주세요! ⭐

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


다운로드 · Agent 간 협업 · 원격 연결 · 微信交流群 · 简体中文 · English


후원

클릭하여 접기
VibeAPI 이 프로젝트를 후원해 주신 VibeAPI에 감사드립니다! VibeAPI는 AI를 집중적으로 활용하는 개발자와 팀을 위해 주요 AI 모델에 대한 통합 접근을 제공합니다. Codex와 Claude 시리즈를 중심으로, 출처를 추적할 수 있는 자체 구축 계정 풀을 운영합니다. 매우 빠른 첫 토큰 응답, 99.9% SLA 가용성, 95%+ 캐시 적중률을 제공하며, 연중무휴 24시간 전문 인력의 기술 지원과 법인 인보이스 발행 및 기업 협력을 지원합니다. 사이버 혜택 받으러 가기 →

인터페이스 미리보기

앱을 전환하지 않고도 Pi, Claude Code, Grok Build 등 10개 이상의 Harness를 하나의 Codex Desktop 창에서 바로 사용할 수 있습니다.

codexhost-demo-github.mp4

인터페이스

Codex Desktop에서 실행 중인 Claude Code, Pi, Grok Build, Oh My Pi 세션과 Diff 검토, Fork, Worktree, Agent 전환

빠른 시작

방법 1: npm (macOS / Windows / Linux)

npm install -g @codexhost/cli
codexhost

방법 2: 설치 프로그램 (macOS / Windows)

Releases에서 플랫폼에 맞는 설치 프로그램을 다운로드하세요.

Linux는 x64 / ARM64를 지원합니다. 자세한 내용은 Linux 안내를 참고하세요.

설치 문제 해결

codexhost가 시작되지 않거나, Codex는 열렸지만 codexhost 기능이 보이지 않는 경우

codexhost console(Windows: 시작 메뉴 → "codexhost console")을 실행하면 로컬 콘솔 http://127.0.0.1:4399/이 열립니다. 마지막 시작 실패 원인, Codex Desktop 버전, Host Runtime 로그를 확인할 수 있고, Codex가 실행 중이 아닐 때 codexhost를 업데이트할 수 있습니다. 콘솔은 codexhost와 함께 시작됩니다. 설치 패키지로 실행하면 브라우저에서 열리고, 터미널에서 실행하면 주소가 출력됩니다.

macOS: 처음 열 때 "앱을 확인할 수 없음" 메시지가 표시됨

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

Windows: 압축 해제형(포터블) Codex Desktop 사용

  1. CODEXHOST_INSTALL_ROOT를 Codex Desktop 압축 해제 디렉터리로 설정합니다:

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

  2. Codex Desktop을 완전히 종료하고 새 터미널을 연 뒤 codexhost를 실행합니다.

주요 기능

전체 작업 화면
여러 Harness의 세션이 하나의 사이드바에 모이고, 입력창 오른쪽 아래에서 언제든 Agent를 전환

Codex Desktop에서 실행 중인 codexhost 전체 작업 화면: 프로젝트 구조, 대화 영역, 여러 Agent 선택기

Diff 검토 패널
매 턴의 변경 사항을 자동으로 요약하고, 「검토」를 누르면 오른쪽에서 전체 Diff 확인

대화의 변경 요약 카드와 오른쪽 검토 패널의 Diff

아무 메시지에서나 Fork
현재 작업 공간에서, 또는 새 Worktree에서 병렬 개발

메시지에서 브랜치를 만드는 메뉴: 현재 작업 공간 또는 새 워크트리

# 입력으로 다른 Agent에 위임
여러 Agent가 각자 독립 세션에서 병렬 실행 · 자세히 보기

# 입력으로 Codex, Claude Code, Grok 등 Agent를 선택하고 각 작업이 독립 세션에서 병렬 실행

도구 호출과 사고 과정
모든 edit, 명령, 사고 과정을 펼쳐서 자세히 확인

편집 기록을 펼쳐 새로 만든 파일의 Diff 표시

Subagent 가시화
Subagent마다 고유 아이콘이 있고, 오른쪽에서 전체 대화 확인

메인 대화에 4개 Subagent 상태가 표시되고 오른쪽에 그중 하나의 전체 대화

원격 개발
VPS를 프로젝트로 추가하면 Agent가 원격 머신에서 바로 실행 · 자세히 보기

사이드바의 원격 VPS 프로젝트와 원격 머신의 작업 디렉터리를 반환하는 대화

사용량 한눈에 보기
캐시 적중률, 예상 비용, 컨텍스트 사용량을 실시간 표시

사용량 팝오버: 컨텍스트, 캐시 적중률, 캐시 읽기/쓰기, 총 Token, 예상 비용

계정 원클릭 가져오기
로컬에 로그인된 Codex, Grok 자격 증명을 Pi로 바로 복사하고 한도를 실시간 확인

계정 설정: 5시간·7일 남은 한도와 Pi로 가져온 계정

Mermaid 다이어그램 렌더링
왼쪽: Codex Desktop + Pi는 다이어그램을 바로 렌더링, 오른쪽: Pi TUI는 소스만 표시

Pi + Codex Desktop과 Pi Agent TUI의 Mermaid 다이어그램 렌더링 비교

기능 상태

모든 Harness에서 Codex Desktop 네이티브 Edit Diff, Fork, 메시지 수정, 슬래시 명령을 사용할 수 있습니다.

전체 기능 매트릭스 보기
기능 Pi Oh My Pi Claude Code OpenCode Grok DeepSeek Harness AGY CodeBuddy WorkBuddy Cursor Hermes Qoder
스트리밍 응답 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
도구 상태 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Edit Diff ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
질문 / 취소 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Model / Thinking 선택 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
도구 승인 ✅ ✅ ✅ ✅ ✅ ✅ — ✅ ✅ ✅ ✅ ✅
권한 모드 — ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
Agent 간 작업 협업 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ — ✅ ✅ ✅
Usage ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ — ✅ ✅
Fork ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
컨텍스트 압축 ✅ ✅ ✅ ✅ ✅ ✅ — ✅ ✅ — ✅ ✅
슬래시 명령 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
이전 메시지 수정 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅

Agent 간 협업

채팅 입력창에 #을 입력하면 작업을 위임할 Agent를 선택하거나 현재 선택한 Harness에서 사용할 수 있는 명령과 스킬을 찾을 수 있습니다.

현재 Agent에게 독립 작업을 다른 Harness로 넘기도록 요청할 수 있습니다. 예를 들면 다음과 같습니다.

claude-code에게 이 변경 사항을 독립적으로 검토하고 호환성 위험을 지적하도록 요청하세요.

pi에게 이 테스트가 간헐적으로 실패하는 원인을 조사하도록 요청하세요.

제가 문서를 정리하는 동안 omp에게 이 기능을 구현하도록 요청하세요.

opencode에게 독립 Thread에서 이 수정을 검증하고 관련 테스트를 실행하도록 요청하세요.

CodexHost는 대상 Harness를 위한 별도의 Native Session을 만듭니다. 위임된 Session은 Codex Desktop의 대화 목록에 표시되며, 언제든 열어서 진행 상황을 확인하거나 대화를 이어갈 수 있습니다.

원격 Harness

로컬 Codex Desktop에서 제어 대상 컴퓨터의 Harness를 사용합니다. 작업은 제어 대상 컴퓨터에서 실행되고 UI는 로컬에 그대로 있습니다. 양쪽에 동일한 버전의 codexhost를 설치해야 합니다.

제어 대상 컴퓨터 연결 방식
macOS / Linux SSH 원격
Windows Remote Control 원격(실험)

SSH 원격

전제 조건: Codex Desktop의 설정 → 연결 → SSH에 제어 대상 컴퓨터가 추가되어 있어야 합니다. 클라이언트는 macOS / Linux / Windows를 지원합니다.

Codex Desktop 설정 → 연결 → SSH 페이지에 추가된 SSH 연결

  1. 제어 대상 컴퓨터에서 설치하고 시작합니다:

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

  2. 로컬에서 codexhost로 Codex Desktop을 시작하고 SSH 작업 공간을 엽니다.

  3. 입력창의 Agent / Model 선택기에서 대상 Harness를 선택합니다.

SSH 설정, 진단 및 제거 →

Remote Control 원격 (실험)

Codex Desktop 공식 Remote Control의 페어링과 인증을 재사용하여, 다른 컴퓨터에서 Windows의 Harness를 사용합니다.

전제 조건: 공식 Remote Control에서 Codex 작업이 정상적으로 실행되어야 합니다. 공개 서비스나 포트를 추가하지 않으며, Harness 자격 증명은 Windows에만 유지됩니다.

Remote Control 설정, 전송 경계 및 진단 →

작동 방식

대부분의 멀티 에이전트 클라이언트는 자체 채팅 UI를 새로 만들고, 공통 프로토콜로 여러 Harness를 연결합니다.

CodexHost는 다른 방식을 택합니다.

  • Desktop 측: CDP / Electron Inspector로 공식 Codex Desktop을 확장하며, 채팅 UI를 다시 만들거나 공식 설치 프로그램을 수정하지 않습니다
  • 프로토콜 측: CLI Shim으로 공식 app-server에 연결하며, 네이티브 Codex 요청은 그대로 전달되어 영향을 받지 않습니다
  • Harness 측: 각 Harness의 네이티브 인터페이스를 우선 사용하고(Pi는 RPC, Claude Code는 Agent SDK), 네이티브 인터페이스가 없으면 ACP로 연결합니다. 스트리밍 출력, 도구 상태, Diff, 승인, 질문은 모두 Codex Desktop 네이티브 UI에 투영됩니다
  • 오케스트레이션 측: 위임된 작업은 대상 Harness에서 독립적인 네이티브 세션으로 실행되며, 시작한 쪽은 결과를 기다리거나 백그라운드에서 실행하도록 선택할 수 있습니다

微信交流群

微信交流群
CodexHost 사용법과 기능에 관심 있는 개발자는 QR 코드를 스캔해 위챗 그룹에 참여할 수 있습니다.
  • 설치 문제는 그룹에서 질문할 수 있습니다
  • 기능 제안과 피드백
  • 개발 관련 논의
  • 버그는 issue로 제출해 주세요
함께 기여해 주세요. 		위챗 그룹 QR 코드

개발

Issue나 PR을 제출하기 전에 기여 안내를 읽어 주세요. PR 제목 라벨, 간단한 CI 결과, 릴리스 전 검증은 저장소 유지 관리 자동화를 참고하세요.

환경 요구 사항: 공식 Codex Desktop, Node.js 22.19+ 또는 24, Rust.

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

실행 아키텍처

Pi를 예로 듭니다. 왼쪽에서 오른쪽이 한 번의 요청 호출 체인입니다: Desktop → 공용 계층 → Pi 플러그인 → 네이티브 프로세스.

Pi를 예로 든 실행 아키텍처: Desktop에서 공용 계층, 이어서 Pi 플러그인과 네이티브 프로세스

Harness 추가

주요 작업은 플러그인의 Manifest, 팩토리, Adapter, Session 및 네이티브 통신과 변환 로직을 구현하는 것입니다. 현재 Renderer에는 여전히 정적 연결이 있어, 완전한 Desktop 연동은 별도로 처리해야 합니다. Harness를 추가할 때는 코딩 Agent가 저장소의 codexhost-add-harness Skill을 사용하도록 할 수 있습니다. 플러그인 구조, 공용 Adapter 인터페이스, 기능 구현과 테스트 요구 사항을 설명합니다.

감사의 글

  • 지속적인 지원을 보내 주신 LINUX DO 커뮤니티에 감사드립니다.
  • 멀티 Harness 통합 방식과 아키텍처에 영감을 주고 참고가 된 Paseo 프로젝트에 감사드립니다.

기여자

CodexHost에 기여해 주신 모든 분께 감사드립니다.

CodexHost 기여자

Star History

Star History Chart