[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-11721":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":16,"stars7d":16,"stars30d":13,"stars90d":16,"forks30d":16,"starsTrendScore":16,"compositeScore":17,"rankGlobal":10,"rankLanguage":10,"license":10,"archived":18,"fork":18,"defaultBranch":19,"hasWiki":20,"hasPages":18,"topics":21,"createdAt":10,"pushedAt":10,"updatedAt":22,"readmeContent":23,"aiSummary":24,"trendingCount":16,"starSnapshotCount":16,"syncStatus":15,"lastSyncTime":25,"discoverSource":26},11721,"codexflow","hebicheng\u002Fcodexflow","hebicheng","Go Agent：Windows、Linux、macOS (go原生支持多端) 客户端支持平台：Windows、Linux、macOS、iOS、Android、Web","",null,"Dart",146,22,119,2,0,4.09,false,"main",true,[],"2026-06-12 02:02:33","# CodexFlow\n\nCodexFlow 是一个面向 Codex CLI 的控制台客户端。\n\n它的目标不是“远程看终端”，而是把 Codex 的会话、turn、diff、审批、状态流，整理成一套适合手机和轻量客户端管理的控制平面。\n\n当前已经支持两条主要 Agent 链路：\n\n- `Codex`\n- `Claude Code`\n\n当前仓库包含三部分：\n\n- `Go Agent`：运行在本地电脑上的服务，负责接入 Codex CLI\n- `iOS App`：运行在 iPhone 上的 SwiftUI 客户端，负责监控、审批和继续指挥\n- `Flutter App`：新的跨平台客户端，负责 Android \u002F Web \u002F 桌面端接入同一套 Agent API\n\n## 工作原理\n\nCodexFlow 不依赖 OCR，也不是去截图识别终端。\n\n它直接接在 `codex app-server` 之上，通过结构化协议拿到真实的会话和执行状态，再转成适合移动端消费的 API。\n\n整体链路如下：\n\n```text\nCodex CLI \u002F codex app-server\n        │\n        │ JSON-RPC over stdio\n        ▼\nGo Agent\n  - 启动并持有本地 codex app-server\n  - 发现已有 session \u002F loaded session\n  - 接收通知、diff、plan、审批请求\n  - 暴露 HTTP API + SSE\n        │\n        │ HTTP \u002F SSE\n        ▼\nClient Apps\n  - iOS SwiftUI App\n  - Flutter App\n  - 会话总览 \u002F 会话详情 \u002F 审批中心\n  - 继续下一步 \u002F steer \u002F interrupt\n```\n\n这套设计的核心点是：\n\n- `Go Agent` 负责把 Codex 的原始协议适配成稳定的应用层接口\n- 客户端不直接操纵终端，而是操纵会话本身\n- “自动发现已有会话”和“受控管理新会话”可以同时存在\n- 对 `Claude Code` 会额外区分 `历史导入` 和 `可接管 runtime`\n\n## 当前已实现的功能\n\n### Go Agent\n\n- 直接启动并连接本机 `codex app-server`\n- 自动发现真实的 Codex 历史会话\n- 自动发现 Claude 历史 transcript 与本机 live runtime\n- 读取 `thread\u002Flist`、`thread\u002Fread`、`thread\u002Floaded\u002Flist`\n- 支持新建受控会话\n- 支持重新接管历史会话\n- 支持开始新 turn、steer 当前 turn、interrupt 当前 turn\n- 支持结束会话、归档会话\n- 捕获命令审批、文件变更审批、权限审批、结构化用户输入请求\n- 对外提供 HTTP API 和 SSE 事件流\n\n### iOS App\n\n- 会话总览页\n- 已接管 \u002F 已结束 \u002F 可接管 Runtime \u002F 历史导入分组\n- 总会话、已加载、运行中、待审批统计\n- 会话详情页\n- plan \u002F diff \u002F timeline 展示\n- 继续下一步、steer、interrupt\n- 审批中心\n- Agent 地址配置\n- 只显示真实数据，不再回退 mock 数据\n\n### Flutter App\n\n- 复用同一套 Agent HTTP API\n- 会话总览页\n- 会话详情页\n- 审批中心\n- 设置页 \u002F Agent 地址配置\n- Claude 会话显示 `History \u002F Runtime` 与 `现有 Runtime \u002F 历史新开 \u002F 新建 Runtime` 状态\n- Android \u002F Web \u002F 桌面端 runner 已补齐\n- 已适配浏览器跨域访问本地 Agent\n\n## 当前支持的端\n\n- `Go Agent`：Windows、Linux、macOS (go原生支持多端)\n- `客户端支持平台`：Windows、Linux、macOS、iOS、Android、Web\n- `iOS SwiftUI App`：iOS\n- `Flutter App`：Windows、Linux、macOS、iOS、Android、Web\n\n## 当前已验证可用的端\n\n- `Go Agent`（macOS）\n- `iOS SwiftUI App`\n- `Flutter Web (Chrome)`\n- `Flutter Android`（MuMu 模拟器）\n\n## 发布产物\n\n- Android 安装包已经发布在 GitHub Releases\n- Web 构建产物也已经发布在 GitHub Releases\n- 如果你只是想直接试用，可以优先从 GitHub Releases 下载对应版本\n\n## 当前状态\n\n项目已经能跑通真实链路：\n\n- Agent 可以连上本机 Codex CLI\n- `dashboard` API 能返回真实会话数据\n- Claude 会话生命周期已经拆分为 `managed \u002F runtime_available \u002F history_only \u002F ended`\n- iOS 客户端可以消费真实数据并进行操作\n- Flutter Web 客户端可以通过浏览器访问本地 Agent\n- Flutter Android 客户端可以在模拟器中访问局域网 Agent\n\n最近这次更新主要包括：\n\n- Claude 会话分层：把 `历史导入` 和 `可接管 runtime` 正式拆开\n- 新建 \u002F 接管 \u002F 结束会话统一进入明确的生命周期阶段\n- Agent 三端打包、Flutter Web \u002F Android 打包、iOS `unsigned ipa` 导出流程验证\n\n当前还没有做的部分：\n\n- 远程 relay\n- 登录与设备配对\n- APNs 推送\n- macOS 菜单栏 Launcher\n- 自动审批策略引擎\n- 完整的 SSE 实时刷新体验\n\n## 快速开始\n\n### 1. 环境要求\n\n- Windows \u002F Linux \u002F macOS（运行 Agent）\n- 已安装并可用的 `codex` CLI\n- 已完成 Codex 登录\n- Go 1.26+\n- Xcode（仅在运行 iOS App 时需要）\n- Flutter（仅在运行 Flutter App 时需要）\n\n### 2. 启动 Go Agent\n\n在仓库根目录执行：\n\n```bash\ngo run .\u002Fcmd\u002Fcodexflow-agent\n```\n\n默认监听地址：\n\n```text\n127.0.0.1:4318\n```\n\n可选环境变量：\n\n- `CODEXFLOW_LISTEN_ADDR`\n- `CODEXFLOW_CODEX_PATH`\n- `CODEXFLOW_REFRESH_INTERVAL`\n- `CODEXFLOW_STATE_DB_PATH`\n\n如果你的 `codex` 不在系统 `PATH` 里，可以显式指定它：\n\n```bash\nCODEXFLOW_CODEX_PATH=\u002Fpath\u002Fto\u002Fcodex go run .\u002Fcmd\u002Fcodexflow-agent\n```\n\n例如：\n\n- macOS \u002F Linux：`CODEXFLOW_CODEX_PATH=\u002Fusr\u002Flocal\u002Fbin\u002Fcodex`\n- Windows：`CODEXFLOW_CODEX_PATH=C:\\path\\to\\codex.exe`\n\n如果你想先编译再运行：\n\n```bash\ngo build -o codexflow-agent .\u002Fcmd\u002Fcodexflow-agent\n.\u002Fcodexflow-agent\n```\n\n在 Windows 上可执行文件会是：\n\n```text\ncodexflow-agent.exe\n```\n\n### 3. Agent 多端使用方式\n\n推荐的部署方式是：\n\n1. 在安装了 `codex` CLI 的那台主机上运行 `Go Agent`\n2. 让 Agent 暴露一个本机或局域网可访问的 HTTP 地址\n3. 用 iOS \u002F Android \u002F Web \u002F 桌面客户端去连接这个地址\n\n同机使用：\n\n```text\nAgent: 127.0.0.1:4318\nClient: http:\u002F\u002F127.0.0.1:4318\n```\n\n跨设备使用：\n\n```bash\nCODEXFLOW_LISTEN_ADDR=0.0.0.0:4318 go run .\u002Fcmd\u002Fcodexflow-agent\n```\n\n然后在客户端里填写运行 Agent 那台机器的局域网 IP，例如：\n\n```text\nhttp:\u002F\u002F192.168.1.10:4318\n```\n\n#### 通过 Tailscale Service 远程访问（可选）\n\n如果你希望在局域网外用 Android \u002F iOS \u002F Web 客户端访问 CodexFlow，可以把 Agent 和 Web 客户端只绑定到本机回环地址，再通过 Tailscale Service 暴露一个 tailnet 内部 HTTPS 入口。这样不需要把 CodexFlow 直接暴露到公网，也不需要在手机上记端口。\n\n示例拓扑：\n\n```text\nhttps:\u002F\u002Fcodexflow.\u003Ctailnet>.ts.net\u002F\n  \u002Fhealthz -> http:\u002F\u002F127.0.0.1:4318\u002Fhealthz\n  \u002Fapi     -> http:\u002F\u002F127.0.0.1:4318\u002Fapi\n  \u002F        -> http:\u002F\u002F127.0.0.1:8088\n```\n\n先启动 Agent：\n\n```bash\nCODEXFLOW_LISTEN_ADDR=127.0.0.1:4318 go run .\u002Fcmd\u002Fcodexflow-agent\n```\n\n再启动一个静态文件服务承载 Flutter Web 构建产物，例如：\n\n```bash\ncd flutter\u002Fcodexflow\u002Fbuild\u002Fweb\npython3 -m http.server 8088 --bind 127.0.0.1\n```\n\n然后配置 Tailscale Service。下面假设 service 名称是 `svc:codexflow`：\n\n```bash\ntailscale serve --service svc:codexflow --bg --https 443 http:\u002F\u002F127.0.0.1:8088\ntailscale serve --service svc:codexflow --bg --https 443 --set-path \u002Fapi http:\u002F\u002F127.0.0.1:4318\u002Fapi\ntailscale serve --service svc:codexflow --bg --https 443 --set-path \u002Fhealthz http:\u002F\u002F127.0.0.1:4318\u002Fhealthz\n```\n\n如果 Tailscale 提示需要管理员批准，需要先在 Tailscale 控制台批准这台机器作为 `svc:codexflow` 的 service proxy。批准后，在客户端里填写：\n\n```text\nhttps:\u002F\u002Fcodexflow.\u003Ctailnet>.ts.net\n```\n\n安全提醒：当前 CodexFlow Agent 还没有内置登录和设备配对机制。远程访问时建议只使用 tailnet 内部的 Tailscale Service，并配合 Tailscale ACL 限制可访问设备；不要用 Funnel 或公网反向代理直接公开 CodexFlow。\n\n### 4. 验证 Agent 是否正常\n\n```bash\ncurl http:\u002F\u002F127.0.0.1:4318\u002Fhealthz\ncurl http:\u002F\u002F127.0.0.1:4318\u002Fapi\u002Fv1\u002Fdashboard\n```\n\n如果正常，你会拿到健康检查结果和真实会话列表。\n\n### 5. 运行 iOS App\n\n用 Xcode 打开：\n\n```text\nios\u002FCodexFlow\u002FCodexFlow.xcodeproj\n```\n\n然后运行 `CodexFlow` target。\n\n### 6. 运行 Flutter App\n\nFlutter 项目目录：\n\n```text\nflutter\u002Fcodexflow\n```\n\n在该目录执行：\n\n```bash\ncd flutter\u002Fcodexflow\nflutter pub get\nflutter run\n```\n\n如果要指定设备，例如：\n\n```bash\nflutter run -d chrome\nflutter run -d emulator-5554\n```\n\n### 7. 运行 Web 版本\n\n先构建 Web（已上传到release，可以直接下载使用）：\n\n```bash\ncd flutter\u002Fcodexflow\nflutter build web --release\n```\n\n构建产物目录：\n\n```text\nflutter\u002Fcodexflow\u002Fbuild\u002Fweb\n```\n\n本地运行最推荐直接用 Python：\n\n```bash\ncd flutter\u002Fcodexflow\u002Fbuild\u002Fweb\npython3 -m http.server 8080\n```\n\n然后浏览器打开：\n\n```text\nhttp:\u002F\u002F127.0.0.1:8080\n```\n\n其他方式也可以，例如：\n\n- `npx serve build\u002Fweb`\n- `busybox httpd`\n- `Nginx \u002F Caddy \u002F Apache`\n- 任意静态站点托管服务\n\n### 8. 在 App 里配置 Agent 地址\n\n如果是同一台 Mac 上跑模拟器：\n\n```text\nhttp:\u002F\u002F127.0.0.1:4318\n```\n\n如果是 `iPhone 真机`、`Android 模拟器`、`Android 真机`，或者你要给其他设备访问，建议让 Agent 监听局域网：\n\n```bash\nCODEXFLOW_LISTEN_ADDR=0.0.0.0:4318 go run .\u002Fcmd\u002Fcodexflow-agent\n```\n\n然后在 App 的 `Settings` 页面填入你 Mac 的局域网 IP，例如：\n\n```text\nhttp:\u002F\u002F192.168.1.10:4318\n```\n\n补充说明：\n\n- `Flutter Web \u002F Chrome`：如果页面和 Agent 在同一台 Mac 上，通常可直接使用 `http:\u002F\u002F127.0.0.1:4318`\n- `Android 模拟器 \u002F 真机`：不要填 `127.0.0.1`，要填你 Mac 的局域网 IP\n- 当前 Agent 已加入浏览器跨域支持，Flutter Web 可以直接访问本地 Agent\n- 如果 Android release APK 报 `ClientException with SocketException: Failed host lookup`，请确认 `android\u002Fapp\u002Fsrc\u002Fmain\u002FAndroidManifest.xml` 声明了 `android.permission.INTERNET`。Debug\u002FProfile manifest 中的权限不会自动覆盖 release 包。\n\n## 基本使用方式\n\n1. 打开 `会话` 页面，查看当前真实会话。\n2. 对历史会话点击“接管到 CodexFlow”，将其转为受控会话。\n3. 在受控会话详情页查看 plan、diff、timeline。\n4. 在受控会话详情页发送下一轮 prompt，或 steer 当前执行中的 turn。\n5. 对正在执行的 turn，可以直接 interrupt。\n6. 打开 `Approvals` 页面，处理等待中的审批请求。\n7. 对不再需要的会话，可以结束或归档。\n\n补充说明：\n\n- `Codex` 会话可以直接按 `已接管 \u002F 已结束 \u002F 历史会话` 理解。\n- `Claude Code` 会话会进一步区分：\n  - `可接管 Runtime`：当前本机还能接入 live runtime\n  - `历史导入`：当前只发现 transcript，可查看历史\n  - `已接管`：已经由 CodexFlow 托管\n\n## API 概览\n\n- `GET \u002Fhealthz`\n- `GET \u002Fapi\u002Fv1\u002Fdashboard`\n- `GET \u002Fapi\u002Fv1\u002Fsessions`\n- `POST \u002Fapi\u002Fv1\u002Fsessions`\n- `GET \u002Fapi\u002Fv1\u002Fsessions\u002F:id`\n- `POST \u002Fapi\u002Fv1\u002Fsessions\u002F:id\u002Fresume`\n- `POST \u002Fapi\u002Fv1\u002Fsessions\u002F:id\u002Fend`\n- `POST \u002Fapi\u002Fv1\u002Fsessions\u002F:id\u002Farchive`\n- `POST \u002Fapi\u002Fv1\u002Fsessions\u002F:id\u002Fturns\u002Fstart`\n- `POST \u002Fapi\u002Fv1\u002Fsessions\u002F:id\u002Fturns\u002Fsteer`\n- `POST \u002Fapi\u002Fv1\u002Fsessions\u002F:id\u002Fturns\u002Finterrupt`\n- `GET \u002Fapi\u002Fv1\u002Fapprovals`\n- `POST \u002Fapi\u002Fv1\u002Fapprovals\u002F:id\u002Fresolve`\n- `GET \u002Fapi\u002Fv1\u002Fevents`\n\n## 仓库结构\n\n```text\ncmd\u002Fcodexflow-agent        Go Agent 启动入口\ninternal\u002Fcodex            Codex app-server 协议适配\ninternal\u002Fruntime          会话管理、统计、审批编排\ninternal\u002Fhttpapi          HTTP API 与 SSE\ninternal\u002Fstore            本地状态存储\nios\u002FCodexFlow             iOS SwiftUI 客户端\nflutter\u002Fcodexflow         Flutter 跨平台客户端\ndocs                      架构与路线文档\nassets                    README 截图资源\n```\n\n## 截图\n\n### iOS\n\n\u003Ctable>\n  \u003Ctr>\n    \u003Ctd>\u003Cimg src=\"assets\u002Fscreenshot-01.jpeg\" alt=\"Screenshot 01\" width=\"240\">\u003C\u002Ftd>\n    \u003Ctd>\u003Cimg src=\"assets\u002Fscreenshot-02.jpeg\" alt=\"Screenshot 02\" width=\"240\">\u003C\u002Ftd>\n  \u003C\u002Ftr>\n  \u003Ctr>\n    \u003Ctd>\u003Cimg src=\"assets\u002Fscreenshot-03.jpeg\" alt=\"Screenshot 03\" width=\"240\">\u003C\u002Ftd>\n    \u003Ctd>\u003Cimg src=\"assets\u002Fscreenshot-04.jpeg\" alt=\"Screenshot 04\" width=\"240\">\u003C\u002Ftd>\n  \u003C\u002Ftr>\n  \u003Ctr>\n    \u003Ctd>\u003Cimg src=\"assets\u002Fscreenshot-05.jpeg\" alt=\"Screenshot 05\" width=\"240\">\u003C\u002Ftd>\n    \u003Ctd>\u003Cimg src=\"assets\u002Fscreenshot-06.jpeg\" alt=\"Screenshot 06\" width=\"240\">\u003C\u002Ftd>\n  \u003C\u002Ftr>\n  \u003Ctr>\n    \u003Ctd>\u003Cimg src=\"assets\u002Fscreenshot-07.jpeg\" alt=\"Screenshot 07\" width=\"240\">\u003C\u002Ftd>\n    \u003Ctd>\u003Cimg src=\"assets\u002Fscreenshot-08.jpeg\" alt=\"Screenshot 08\" width=\"240\">\u003C\u002Ftd>\n  \u003C\u002Ftr>\n  \u003Ctr>\n    \u003Ctd>\u003Cimg src=\"assets\u002Fscreenshot-09.jpeg\" alt=\"Screenshot 09\" width=\"240\">\u003C\u002Ftd>\n    \u003Ctd>\u003C\u002Ftd>\n  \u003C\u002Ftr>\n\u003C\u002Ftable>\n\n### Claude\n\n\u003Ctable>\n  \u003Ctr>\n    \u003Ctd>\u003Cimg src=\"assets\u002Fscreenshot_claude_01.jpeg\" alt=\"Claude Screenshot 01\" width=\"240\">\u003C\u002Ftd>\n    \u003Ctd>\u003Cimg src=\"assets\u002Fscreenshot_claude_02.jpeg\" alt=\"Claude Screenshot 02\" width=\"240\">\u003C\u002Ftd>\n  \u003C\u002Ftr>\n\u003C\u002Ftable>\n\n### Android\n\n\u003Ctable>\n  \u003Ctr>\n    \u003Ctd>\u003Cimg src=\"assets\u002Fscreenshot_android_01.png\" alt=\"Android Screenshot 01\" width=\"240\">\u003C\u002Ftd>\n    \u003Ctd>\u003Cimg src=\"assets\u002Fscreenshot_android_02.png\" alt=\"Android Screenshot 02\" width=\"240\">\u003C\u002Ftd>\n  \u003C\u002Ftr>\n\u003C\u002Ftable>\n\n### Web\n\n\u003Ctable>\n  \u003Ctr>\n    \u003Ctd>\u003Cimg src=\"assets\u002Fscreenshot_web_01.png\" alt=\"Web Screenshot 01\" width=\"240\">\u003C\u002Ftd>\n    \u003Ctd>\u003Cimg src=\"assets\u002Fscreenshot_web_02.png\" alt=\"Web Screenshot 02\" width=\"240\">\u003C\u002Ftd>\n  \u003C\u002Ftr>\n\u003C\u002Ftable>\n\n## 说明\n\n下一阶段计划：\n\n- SSE 实时刷新\n- macOS Launcher\n- 局域网外的安全 relay\n- 推送通知\n- 自动审批策略\n","CodexFlow 是一个面向 Codex CLI 的控制台客户端，旨在将 Codex 的会话、turn、diff、审批和状态流整理成适合移动端和轻量级客户端管理的控制平面。其核心功能包括通过 Go Agent 适配 Codex 的原始协议为稳定的 HTTP API 和 SSE 事件流，支持自动发现和管理历史会话，并提供 iOS 和 Flutter 跨平台客户端来监控、审批和指挥会话。该工具适用于需要在多端（Windows、Linux、macOS、iOS、Android、Web）上管理和操作 Codex 会话的场景，特别适合开发者或团队希望通过移动设备进行远程协作和任务管理的情况。","2026-06-11 03:32:25","CREATED_QUERY"]