Lumen Bridge

Connect external AI and MCP clients to native Codex sessions through the official codex app-server.

Current test candidate / 当前测试候选版本：V3.0.0

MCP client -> Lumen Bridge (JSON-RPC stdio) -> codex app-server --listen stdio:// -> native Codex sessions

Quick Start · Zero-code install · Public API · Troubleshooting

Lumen Bridge lets an MCP client start, observe, steer, pause, and continue native Codex work without introducing a second job queue, transcript database, retry loop, or authority layer. Codex still owns its threads, turns, history, permissions, and execution.

GitHub is where the source code and download live: open the public repository. You install and run Lumen Bridge locally on your own computer; it is not installed “into GitHub.”

Contents

• Main Features

• 60-second Quick Start

• Zero-code install with Codex

• What happens during installation?

• Managing extra Codex conversations

• Important Notes

• Manual setup (Windows/macOS)

• Public API

• Privacy & Security

• Troubleshooting

• Uninstall/cleanup

• Migrating from legacy Local Codex Bridge

• Contributing

• Acknowledgements

• License

Related MCP server: codex-mcp-server

Main Features

• Uses the official codex app-server --listen stdio:// protocol.

• Works with persistent native Codex threads instead of copying conversations into another store.

• Starts or resumes work, observes progress, steers an active turn, responds to real pending requests, and interrupts safely.

• Provides bounded checkpoints and explicit, recovery-verified task rollover across native threads.

• Keeps direct local MCP setup small: node plus one absolute path.

• Supports Windows and macOS.

• Exposes exactly 11 focused codex_* MCP tools.

• Keeps Tunnel and durable remote hosting optional and operator-owned.

60-second Quick Start

Requirements

Before starting, install:

1. Open Terminal, PowerShell, or another shell.

2. Clone, build, and test Lumen Bridge:

git clone https://github.com/diabetic0/lumen-bridge.git
cd lumen-bridge
npm ci
npm run build
npm test

3. Find the absolute path to the built entry point:

<absolute-path-to-lumen-bridge>/dist/src/index.js

4. Add a local stdio MCP server to your MCP client. A typical JSON-style configuration is:

{
  "mcpServers": {
    "lumen-bridge": {
      "command": "node",
      "args": ["<absolute-path-to-lumen-bridge>/dist/src/index.js"]
    }
  }
}

Replace the placeholder with a real absolute native path. On Windows, use a drive-letter path; on macOS, use an absolute POSIX path. Restart or reload the MCP client, then confirm that all 11 tools in Public API appear.

That is the complete direct local setup. It does not require a Tunnel, a Windows scheduled task, a background service, or the macOS app launcher.

Zero-code install with Codex

If you prefer, paste one of the following complete prompts into Codex. Review every requested approval: Codex may need to install files, update your MCP client configuration, or request genuine operating-system elevation.

English prompt

Help me install and verify Lumen Bridge from its public repository:
https://github.com/diabetic0/lumen-bridge

Work carefully and explain each material action before taking it.

1. Detect whether this computer is running Windows or macOS. Stop if it is another operating system.
2. Verify that Node.js 24 or newer, Git, the Codex CLI, and the official `codex app-server --listen stdio://` capability are available. If any prerequisite is missing or too old, stop and clearly explain what I need to install or update. Do not silently substitute another runtime or work around a missing prerequisite.
3. Ask me to choose or confirm a user-owned installation directory, then clone https://github.com/diabetic0/lumen-bridge.git there. Do not place it in a system-owned or protected directory.
4. Before executing project scripts, inspect README.md and the relevant platform scripts in the repository. Explain which install path applies to me.
5. In the cloned repository, run exactly: npm ci, npm run build, and npm test. Stop and report the actual error if any command fails.
6. Configure my MCP client for direct local stdio using command `node` and the absolute path to `dist/src/index.js`. Use a supported repository launcher only if my chosen setup genuinely requires it. Show me the proposed configuration before changing it.
7. On Windows, use the repository's Windows scripts and request elevation only when actually necessary. Treat scheduled-task hosting as an advanced optional remote/Tunnel setup, not a requirement for direct local MCP. On macOS, use only the supported launcher script or optional Lumen Bridge.app when a launcher-based setup is explicitly chosen.
8. Keep Secure MCP Tunnel integration optional, external, and operator-owned. Never ask me to paste credentials into this prompt, source files, logs, or documentation, and never print secrets.
9. Reload or restart the MCP client as appropriate and verify that it exposes exactly these 11 tools: codex_threads, codex_models, codex_turn, codex_observe, codex_steer, codex_respond, codex_interrupt, codex_runtime, codex_checkpoint, codex_task_checkpoint, codex_rollover.
10. Preserve a rollback path. Do not delete an existing installation, native Codex conversation, checkpoint, scheduled task, credential, or configuration unless there is an explicit need, you explain the impact, and I approve that specific destructive action.
11. Finish with a short report containing: detected platform, versions checked, installation path, MCP entry point, tests run, tool-count verification, changes made, and rollback instructions. Do not configure Tunnel, perform a legacy migration/cutover, or start a live Codex smoke test unless I separately ask for it.

中文提示词

请帮助我从公开仓库安装并验证 Lumen Bridge：
https://github.com/diabetic0/lumen-bridge

请谨慎操作，并在执行每个重要操作前先解释其作用。

1. 检测这台电脑运行的是 Windows 还是 macOS；如果是其他操作系统，请停止。
2. 检查 Node.js 版本是否为 24 或更高，并检查 Git、Codex CLI，以及官方 `codex app-server --listen stdio://` 能力是否可用。如果任何前置条件缺失或版本过低，请停止并清楚说明我需要安装或升级什么。不要静默替换运行时，也不要绕过缺失的前置条件。
3. 让我选择或确认一个由当前用户拥有的安装目录，然后把 https://github.com/diabetic0/lumen-bridge.git 克隆到该目录。不要安装到系统所有或受保护的目录。
4. 在执行项目脚本前，先检查仓库中的 README.md 和当前平台相关脚本，并说明哪一种安装方式适合我。
5. 在克隆后的仓库中依次准确运行：npm ci、npm run build、npm test。任一命令失败时停止，并报告真实错误。
6. 为我的 MCP 客户端配置本地 stdio：命令使用 `node`，参数使用 `dist/src/index.js` 的绝对路径。只有在我选择的方案确实需要时，才使用仓库支持的启动器。修改配置前先向我展示拟议配置。
7. 在 Windows 上，仅在确有必要时使用仓库提供的 Windows 脚本并申请管理员权限。计划任务托管属于高级、可选的远程/Tunnel 方案，不是本地直连 MCP 的必需项。在 macOS 上，只有明确选择启动器方案时，才使用受支持的启动脚本或可选的 Lumen Bridge.app。
8. Secure MCP Tunnel 集成必须保持可选、外部管理并由操作者负责。绝不要让我把凭据粘贴到此提示词、源文件、日志或文档中，也不要输出任何秘密信息。
9. 按需重新加载或重启 MCP 客户端，并确认它准确显示以下 11 个工具：codex_threads、codex_models、codex_turn、codex_observe、codex_steer、codex_respond、codex_interrupt、codex_runtime、codex_checkpoint、codex_task_checkpoint、codex_rollover。
10. 保留回滚路径。除非确有明确需要、你已解释影响且我明确批准该项破坏性操作，否则不要删除现有安装、原生 Codex 对话、检查点、计划任务、凭据或配置。
11. 最后给出简短报告，包括：检测到的平台、已检查的版本、安装路径、MCP 入口、执行过的测试、工具数量验证、所做更改和回滚方法。除非我另行明确要求，否则不要配置 Tunnel、执行旧版迁移/切换，也不要启动会创建真实 Codex 线程的在线冒烟测试。

What happens during installation?

At runtime, the MCP client starts Lumen Bridge over stdio. Lumen Bridge starts the official Codex app-server over stdio and translates the small public tool contract into native Codex operations. Persistent conversation history stays with Codex; the Bridge keeps only bounded supervision and task-continuity state needed for its job.

Managing extra Codex conversations

Installation, verification, supervision, checkpoints, and rollover can create temporary native Codex threads or conversations. Review their purpose before deleting them:

Deleting a Codex conversation does not uninstall Lumen Bridge, but you may lose the ability to resume that thread or its context. Lumen Bridge does not auto-delete native Codex conversations.

Important Notes

• Never paste secrets into GitHub issues, this README, install prompts, source files, or logs.

• Tunnel credentials remain external and operator-owned.

• A stall advisory is advisory only. It does not auto-execute, auto-retry, interrupt work, or bypass approvals.

• A rollover recommendation does not migrate anything by itself. Preparation, finalization, and continued work are separate explicit actions.

• Keep direct fresh-install instructions separate from legacy Local Codex Bridge migration instructions.

• Live smoke tests create persistent native Codex threads. Run them only when you deliberately want that side effect.

Manual setup (Windows/macOS)

Direct local MCP — Windows

Open PowerShell in a user-owned directory:

git clone https://github.com/diabetic0/lumen-bridge.git
Set-Location lumen-bridge
npm ci
npm run build
npm test
Resolve-Path .\dist\src\index.js

Configure the MCP client with:

No scheduled task is needed for this direct local configuration.

Direct local MCP — macOS

Open Terminal in a user-owned directory:

git clone https://github.com/diabetic0/lumen-bridge.git
cd lumen-bridge
npm ci
npm run build
npm test
realpath dist/src/index.js

Configure the MCP client with node, the absolute path returned for dist/src/index.js, and stdio transport.

Optional advanced hosting and launchers

These components are for deliberate remote/Tunnel or durable-host scenarios. They are not part of ordinary direct local MCP installation.

For strict stdio clients, launch the built entry point with Node directly. Avoid npm start in strict MCP configuration because package-manager lifecycle output can contaminate stdout, which is reserved for JSON-RPC.

Public API

Lumen Bridge exposes exactly these 11 public MCP tools:

Privacy & Security

• Lumen Bridge is a control surface, not an operating-system sandbox. Actual permissions come from Codex, the selected sandbox policy, and explicit approvals.

• The official app-server child process inherits the Bridge process environment. Keep secrets out of environment variables unless the operator intentionally provides them to that process.

• Native Codex owns persistent threads, turns, history, final messages, and execution capabilities.

• Bridge-owned state is bounded to live supervision data, pending requests, terminal snapshots, optional checkpoints, task bindings, rollover state, and optional UX projection.

• Thread filters and working-directory filters are conveniences, not security boundaries or access-control lists.

• Lumen Bridge answers only real pending native requests. It does not fabricate approval or user-input request IDs.

• On writer conflicts or ambiguous mutating acknowledgements, the Bridge fails closed rather than retrying, replacing the thread, killing another app-server, or redirecting work.

• Direct local stdio stays on the local machine. Any remote access or Secure MCP Tunnel is separate, optional infrastructure configured and owned by its operator.

• Do not commit credentials, Tunnel profiles, local usernames, home-directory paths, access tokens, or machine-specific configuration.

Troubleshooting

For deterministic validation after any local source change:

npm run build
npm test
npm run test:shared
npm run test:platform

Live smoke testing is intentionally separate because it creates persistent native Codex threads.

Uninstall/cleanup

Direct local installation

1. Remove the lumen-bridge server entry from your MCP client configuration.

2. Reload or restart the MCP client so it stops launching the Bridge.

3. Confirm no active task depends on the installation or its local checkpoints.

4. Delete the user-owned cloned lumen-bridge folder if you no longer need it.

This does not delete native Codex conversations. Remove those separately only after applying the guidance in Managing extra Codex conversations.

Advanced Windows scheduled-task installation

Use the repository script so the exact scheduled task and host files are handled consistently:

.\windows\Uninstall-LumenBridge.ps1 -WhatIf
.\windows\Uninstall-LumenBridge.ps1 -Confirm

Review the preview and confirmation carefully. The script preserves private data by default. Tunnel credentials and external Tunnel configuration remain operator-owned and require their own deliberate cleanup.

macOS launcher

Remove the MCP client entry first. If you built the optional Lumen Bridge.app, remove that app bundle only after confirming it is not being used to launch an external Tunnel. Any Keychain or external Tunnel cleanup is separate and operator-owned.

Migrating from legacy Local Codex Bridge

Migration is a separate advanced workflow, not part of a fresh install. Do not run these scripts merely to configure direct local MCP.

Start with a plan-only migration and inspect its output:

.\windows\Migrate-ToLumenBridge.ps1 -PlanOnly

The migration flow deliberately stages first, requires an explicit switch, keeps the old task as the rollback path, and does not copy private credentials or delete old state. Cutover, rollback, scheduled-task changes, and destructive cleanup require explicit operator intent and may require real elevation.

Contributing

Contributions are welcome at github.com/diabetic0/lumen-bridge.

1. Create a focused branch or fork.

2. Keep the Bridge thin and preserve the boundary between native Codex state and bounded Bridge supervision state.

3. Do not add credentials, usernames, private paths, Tunnel profiles, generated secrets, or unrelated machine configuration.

4. Run the validation suite:

npm ci
npm run build
npm test
npm run test:shared
npm run test:platform

5. Open a pull request describing the behavior, validation evidence, and any platform-specific limitations. Report live smoke tests separately because they create persistent native threads.

Acknowledgements

Collaborative contributors: ChatGPT and Codex.

感谢小红书 UP @Nine 提供的思路，也感谢每一位帮助把“让外部 AI 真正监督 native Codex”从想法打磨成一层足够薄、边界足够清楚、可以公开协作的 Bridge 的朋友。特别感谢 予安 一路以来的支持。

License

Lumen Bridge is available under the MIT License.