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

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

• loop-superpowers — pure Skill mini-loops for Claude Code
• loop-opencode — closed-loop driver for OpenCode CLI
• loop-copilot — closed-loop driver for GitHub Copilot SDK
• loop-cursor — closed-loop driver for Cursor IDE SDK
• loop-deepseek — self-built ReAct agent loop for DeepSeek API
• loop-ollama — self-built ReAct agent loop for local Ollama models
• loop-antigravity — closed-loop driver for Google Antigravity / Gemini
• loop-openclaw — multi-agent loop config generator for OpenClaw Gateway

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 以供审计。

相关项目

• loop-superpowers —— 面向 Claude Code 的纯 Skill 迷你循环
• loop-opencode —— OpenCode CLI 闭环驱动
• loop-copilot —— GitHub Copilot SDK 闭环驱动
• loop-cursor —— Cursor IDE SDK 闭环驱动
• loop-deepseek —— 面向 DeepSeek API 的自建 ReAct 代理循环
• loop-ollama —— 面向本地 Ollama 模型的自建 ReAct 代理循环
• loop-antigravity —— Google Antigravity / Gemini 闭环驱动
• loop-openclaw —— OpenClaw Gateway 多代理循环配置生成器

许可证

Apache License 2.0 —— 详见 LICENSE 文件。

Copyright 2026 Perry Link