Skip to content

README.md

Latest commit

 

History

History
135 lines (93 loc) · 7.66 KB

README.md

File metadata and controls

135 lines (93 loc) · 7.66 KB

loop-codex — Dual-Channel Driver for Codex Desktop (CDP + JSON-RPC)

Version License GitHub stars

English | 中文

通过双通道(JSON-RPC + CDP)驱动 Codex Desktop,让 agent 既能操控文件系统又能阅读和交互 IDE 的 GUI 界面。

This project is an alternative to CLI-only IDE automation tools, but specifically optimized for GUI-aware autonomous development workflows using Chrome DevTools Protocol (CDP) and JSON-RPC over Unix Domain Sockets / Named Pipes.

English

Features

  • Dual-channel architecture — JSON-RPC for file ops and command execution, CDP for UI state awareness and interaction
  • 15 TypeScript modules — CDP connection, DOM selector engine, accessibility tree, screenshot capture, port discovery, dual-channel coordinator
  • Four-layer selector fallback — backendNodeId (preferred) -> Accessibility Tree -> CSS Selector -> XPath (last resort)
  • Cross-platform IPC — Unix Domain Sockets (macOS/Linux) + Named Pipes (Windows) via unified IPCTransport interface
  • DOM version drift detection — SHA-256 fingerprint comparison triggers selector rediscovery on IDE updates
  • CDP safety guard — allowed_dom_scope restricts accessible DOM regions; L0/L1/L2 dangerous-operation interception

Quick Start

# Clone and build
git clone https://github.com/PerryLink/loop-codex.git
cd loop-codex
bun install
bun run src/index.ts

# Or build standalone binaries
bun build --compile --target=bun src/index.ts --outfile loop-codex
./loop-codex --goal "Add dark mode toggle to settings UI"

# Run Phase 0 API probes
bash probes/probe-01-cdp-connect.sh
bash probes/probe-08-full-session.sh

Requirements: Bun >= 1.0.0, Codex Desktop running with --remote-debugging-port.

FAQ

Q: Why does loop-codex need two channels (CDP + JSON-RPC)?

A: JSON-RPC handles file creation, editing, and terminal commands via Codex's App Server. CDP handles GUI operations that a CLI can't see — reading terminal output panels, clicking IDE buttons, capturing screenshots of the IDE state, and accessing the DOM for real-time UI inspection. Together they provide full coverage of a GUI IDE.

Q: What happens if Codex Desktop updates and DOM selectors break?

A: loop-codex includes a DOM version drift detector. On startup, it computes a SHA-256 fingerprint of the DOM structure. If it differs from the cached fingerprint, the selector engine automatically triggers rediscovery via the four-layer fallback. A DOMVersionDetector module tracks version changes and logs selector migration events.

Q: Is this safe to run? Can CDP access my browser data?

A: Yes, safety is a first-class concern. CDP connections are scoped to allowed_dom_scope — only Codex Desktop's own WebContents, not arbitrary browser tabs. Dangerous CDP operations (like Runtime.evaluate with unrestricted expressions) pass through a three-level guard (L0/L1/L2) with expression whitelisting. All CDP commands are logged to cdp-session.log for auditability.

Related Projects

License

Apache License 2.0 — see LICENSE for full text.

Copyright 2026 Perry Link

中文

特性

  • 双通道架构 —— JSON-RPC 用于文件操作和命令执行，CDP 用于 UI 状态感知和交互
  • 15 个 TypeScript 模块 —— CDP 连接、DOM 选择器引擎、无障碍树、截图捕获、端口发现、双通道协调器
  • 四层选择器回退 —— backendNodeId（首选）-> 无障碍树 -> CSS 选择器 -> XPath（最后备选）
  • 跨平台 IPC —— Unix Domain Sockets（macOS/Linux）+ Named Pipes（Windows），通过统一的 IPCTransport 接口
  • DOM 版本漂移检测 —— SHA-256 指纹比对在 IDE 更新时触发选择器重新发现
  • CDP 安全守卫 —— allowed_dom_scope 限制可访问的 DOM 区域；L0/L1/L2 危险操作拦截

快速开始

# 克隆并构建
git clone https://github.com/PerryLink/loop-codex.git
cd loop-codex
bun install
bun run src/index.ts

# 或构建独立二进制
bun build --compile --target=bun src/index.ts --outfile loop-codex
./loop-codex --goal "Add dark mode toggle to settings UI"

# 运行第 0 阶段 API 探针
bash probes/probe-01-cdp-connect.sh
bash probes/probe-08-full-session.sh

依赖要求：Bun >= 1.0.0，Codex Desktop 以 --remote-debugging-port 参数运行。

常见问题

Q：为什么 loop-codex 需要两个通道（CDP + JSON-RPC）？

A：JSON-RPC 通过 Codex 的 App Server 处理文件创建、编辑和终端命令。CDP 处理 CLI 无法看到的 GUI 操作 —— 读取终端输出面板、点击 IDE 按钮、捕获 IDE 状态截图以及访问 DOM 进行实时 UI 检查。两者结合提供了对 GUI IDE 的全面覆盖。

Q：如果 Codex Desktop 更新导致 DOM 选择器失效怎么办？

A：loop-codex 内置了 DOM 版本漂移检测器。启动时，它会计算 DOM 结构的 SHA-256 指纹。如果与缓存的指纹不同，选择器引擎会通过四层回退自动触发重新发现。DOMVersionDetector 模块会追踪版本变化并记录选择器迁移事件。

Q：运行这个安全吗？CDP 能访问我的浏览器数据吗？

A：是的，安全性是首要关注点。CDP 连接限定在 allowed_dom_scope 内 —— 仅限 Codex Desktop 自身的 WebContents，而非任意浏览器标签页。危险的 CDP 操作（如无限制表达式的 Runtime.evaluate）会通过三级守卫（L0/L1/L2）进行表达式白名单过滤。所有 CDP 命令都会记录到 cdp-session.log 以供审计。

相关项目

许可证

Apache License 2.0 —— 详见 LICENSE 文件。

Copyright 2026 Perry Link