# loop-codex

**Repository Path**: perrylink/loop-codex

## Basic Information

- **Project Name**: loop-codex
- **Description**: Dual-channel autonomous driver for Codex Desktop. CDP+JSON-RPC architecture with 4-layer selector fallback, SHA-256 DOM drift detection, cross-platform IPC & L0-L2 safety gates. Part of the Loop Engin
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-22
- **Last Updated**: 2026-08-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# loop-codex — Dual-Channel Driver for Codex Desktop (CDP + JSON-RPC)
[![Gitee](https://img.shields.io/badge/Gitee-mirror-c71d23?logo=gitee)](https://gitee.com/perrylink/loop-codex)

[![Version](https://img.shields.io/badge/version-0.1.0-blue.svg)](https://github.com/PerryLink/loop-codex)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/PerryLink/loop-codex/blob/main/LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/PerryLink/loop-codex?style=social)](https://github.com/PerryLink/loop-codex/stargazers)


[English](#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

```bash
# 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](https://github.com/PerryLink/loop-superpowers) — pure Skill mini-loops for Claude Code
- [loop-opencode](https://github.com/PerryLink/loop-opencode) — closed-loop driver for OpenCode CLI
- [loop-copilot](https://github.com/PerryLink/loop-copilot) — closed-loop driver for GitHub Copilot SDK
- [loop-cursor](https://github.com/PerryLink/loop-cursor) — closed-loop driver for Cursor IDE SDK
- [loop-deepseek](https://github.com/PerryLink/loop-deepseek) — self-built ReAct agent loop for DeepSeek API
- [loop-ollama](https://github.com/PerryLink/loop-ollama) — self-built ReAct agent loop for local Ollama models
- [loop-antigravity](https://github.com/PerryLink/loop-antigravity) — closed-loop driver for Google Antigravity / Gemini
- [loop-openclaw](https://github.com/PerryLink/loop-openclaw) — multi-agent loop config generator for OpenClaw Gateway

### License

Apache License 2.0 — see [LICENSE](./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 危险操作拦截

### 快速开始

```bash
# 克隆并构建
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](https://github.com/PerryLink/loop-superpowers) —— 面向 Claude Code 的纯 Skill 迷你循环
- [loop-opencode](https://github.com/PerryLink/loop-opencode) —— OpenCode CLI 闭环驱动
- [loop-copilot](https://github.com/PerryLink/loop-copilot) —— GitHub Copilot SDK 闭环驱动
- [loop-cursor](https://github.com/PerryLink/loop-cursor) —— Cursor IDE SDK 闭环驱动
- [loop-deepseek](https://github.com/PerryLink/loop-deepseek) —— 面向 DeepSeek API 的自建 ReAct 代理循环
- [loop-ollama](https://github.com/PerryLink/loop-ollama) —— 面向本地 Ollama 模型的自建 ReAct 代理循环
- [loop-antigravity](https://github.com/PerryLink/loop-antigravity) —— Google Antigravity / Gemini 闭环驱动
- [loop-openclaw](https://github.com/PerryLink/loop-openclaw) —— OpenClaw Gateway 多代理循环配置生成器

### 许可证

Apache License 2.0 —— 详见 [LICENSE](./LICENSE) 文件。

Copyright 2026 Perry Link