How do I use Grok-Codex Bridge?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Grok-Codex Bridge refactor the database layer to use async queries" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Grok-Codex Bridge

by Nurkic4

Overview Schema Related Servers Score Discussions

TypeScript

Local

Grok-Codex Bridge

这是一个 MCP（模型上下文协议）工具，可以让 Codex 把具体的编码任务交给 Grok Build CLI 执行。经过测试，Grok 4.5 的编码处理速度远超其他模型，而且在有明确要求或方案的情况下能力完全不差。由于 GPT 5.6 的正常任务处理速度偏慢，所以需要用一个编码智能体来协助 Codex 干脏活累活。

协作分工

Codex：负责需求理解、架构设计、项目规划、代码审查和最终决策。
Grok：负责具体的代码查找、文件修改、命令执行和测试。
桥接程序：让任务调用一直等待到 Grok 完成；同时把实时过程写入本地日志，并显示在独立的观察窗口中。

下载安装 MCP 后，可以使用这段自定义提示词来要求 Codex 使用该工具：

当任务涉及代码项目时，先调用 grok_session_ensure 连接当前项目对应的 Grok 会话。当完成需求分析并需要进行具体的代码修改、命令执行或测试时，优先使用 Grok-Codex MCP 工具。Codex 负责规划、架构和审查，Grok 负责具体执行；工具说明和返回结果定义其余流程。

Related MCP server: Grok-in-Codex

功能

每个 Codex 任务、项目路径和 Git 分支对应一个 Grok 会话。
通过 ACP（代理客户端协议）的标准输入输出通道控制 Grok Build CLI。
通过 --always-approve 自动批准 Grok 的普通工具权限请求。
每五分钟进行一次内部健康检查；健康检查与最大运行时间分开配置。
不把 Grok 的连续过程逐条发送到 Codex 上下文。
提供可见的 PowerShell 观察窗口，显示任务阶段、工具、文件、测试、错误和健康检查结果；如果旧窗口已经关闭，会自动重新打开。
校验项目路径和工作目录。
在 Windows 上取消任务时结束完整的进程树（父进程及其子进程）。

环境要求

Node.js 20 或更高版本。
Git（用于从 GitHub 克隆仓库）。
已安装并完成认证的 Grok CLI。
grok 已加入 PATH 环境变量，或者设置 GROK_EXECUTABLE 指向 Grok 可执行文件。

从 GitHub 克隆并安装（Windows PowerShell）

下面的命令可直接复制；请按需把本地路径改成你自己的目录。

# 1. 进入你希望存放仓库的目录
cd $env:USERPROFILE\Desktop

# 2. 克隆公开仓库
git clone https://github.com/Nurkic4/grok-to-codex.git
cd grok-to-codex

# 3. 确认 Node.js 版本（需要 >= 20）
node -v

# 4. 安装依赖
npm install

# 5. 编译 TypeScript 到 dist/
npm run build

安装完成后，应能看到：

node_modules\：依赖
dist\index.js：MCP 服务入口
dist\observer.js：观察窗口入口

命令说明与完整验证流程

命令	作用	会不会生成 `dist/`
`npm install`	安装 `package.json` 中的依赖	否
`npm run typecheck`	只做 TypeScript 类型检查（`tsc --noEmit`），不写出编译产物	否
`npm test`	运行 `tests/*.test.ts` 单元测试	否
`npm run build`	编译 TypeScript，生成 `dist/` 下的 JS 产物	是

推荐的完整验证顺序（与仓库 CI 一致）：

cd C:\Users\你的用户名\Desktop\grok-to-codex

npm run typecheck
npm test
npm run build

说明：

typecheck：尽早发现类型错误，适合开发过程中频繁执行。
test：验证会话键、路径边界、任务提示词、默认终端配置、观察窗口存活判断等逻辑。
build：生成 Codex MCP 实际要启动的 dist/index.js 与观察窗口用的 dist/observer.js。
修改源码后，若要在发布模式下使用，需要重新执行 npm run build。

构建产物用途

产物	用途
`dist/index.js`	MCP 服务主入口。Codex 通过 `node` 启动它，从而暴露 `grok_*` 系列工具。
`dist/observer.js`	独立观察窗口入口。桥接程序在需要时用 `node dist/observer.js --file <jsonl日志>` 打开，实时读取 JSONL 日志并打印任务过程。

确认 Grok CLI 已安装、可调用

桥接程序默认执行 PATH 中的 grok；也可通过 GROK_EXECUTABLE 指定绝对路径。

在新的 PowerShell 窗口中检查：

# 是否能在 PATH 中找到 grok
Get-Command grok -ErrorAction SilentlyContinue

# 查看可执行文件位置
where.exe grok

# 确认命令能被启动（以你本机 Grok CLI 实际支持的帮助/版本参数为准）
grok --help

判断标准：

已安装且在 PATH 中：Get-Command grok 能返回命令信息，where.exe grok 能打印路径。
不在 PATH 中：为 MCP 配置设置 GROK_EXECUTABLE，例如：

# 示例：把路径换成你本机实际的 grok.exe 位置
$env:GROK_EXECUTABLE = "C:\Users\你的用户名\AppData\Local\Programs\grok\grok.exe"

已认证：本仓库不负责 Grok 账号登录流程。请先按 Grok CLI 官方方式完成认证；若认证无效，会话连接或任务执行会失败，错误会出现在观察窗口或 %USERPROFILE%\.grok-to-codex\logs\ 下的日志中。
可从终端调用：在普通 PowerShell 里能运行 grok，并且没有 “无法识别命令” 一类错误。Codex 启动 MCP 时继承的环境变量也需要能找到同一可执行文件。

Codex MCP 配置（Windows 绝对路径示例）

在 Codex 使用的 MCP 配置中添加此服务。请使用编译后入口文件的绝对路径，不要写成相对路径。

{
  "mcpServers": {
    "grok-to-codex": {
      "command": "node",
      "args": [
        "C:\\Users\\你的用户名\\Desktop\\grok-to-codex\\dist\\index.js"
      ],
      "env": {
        "GROK_MODEL": "grok-4.5",
        "GROK_ALWAYS_APPROVE": "true",
        "GROK_OPEN_OBSERVER": "true"
      }
    }
  }
}

可选：当 grok 不在 PATH 中时，在 env 中补充：

"GROK_EXECUTABLE": "C:\\Users\\你的用户名\\AppData\\Local\\Programs\\grok\\grok.exe"

注意：

JSON 里的 Windows 路径请使用双反斜杠 \\，或改用正斜杠 /。
MCP 协议数据只写入标准输出；诊断信息写入标准错误。
观察窗口是独立的控制台窗口，通过读取桥接程序数据目录中的 JSONL（每行一个 JSON 对象）日志显示 Grok 的工作过程。
修改配置或重新 npm run build 后，通常需要重启 Codex / 重新加载 MCP，才会生效。

提供的工具

grok_session_ensure：创建或恢复当前任务对应的 Grok 会话。
grok_task_start：执行一项编码、测试或检查任务，并等待任务结束后返回结果。
grok_task_status：返回当前任务的简要状态。
grok_task_cancel：取消当前任务并结束 Grok 的进程树。
grok_session_switch：切换到另一个项目或分支对应的独立上下文。
grok_session_close：关闭闲置的 Grok 工作进程，同时保留会话映射。

每个任务都应该提供目标、允许修改的路径、限制条件、验收标准和验证命令。

grok_task_start 支持的模式：

implement：实现/修改代码
test：运行或补充测试
inspect：只读检查、排查

该调用会一直等待，直到 Grok 完成、失败、阻塞、被取消，或触发可选的最大运行时间限制。

运行配置

环境变量	默认值	说明
`GROK_CODEX_BRIDGE_HOME`	`%USERPROFILE%\.grok-to-codex`	会话注册表和日志目录
`GROK_EXECUTABLE`	`grok`	Grok 可执行文件
`GROK_MODEL`	`grok-4.5`	传给 Grok 的模型名称
`GROK_TERMINAL_SHELL`	Windows 使用 `powershell.exe`，Unix 使用系统默认 shell	Grok 通过 ACP 创建终端时使用的 shell
`GROK_ALWAYS_APPROVE`	`true`	启动 Grok 时跳过普通权限询问
`GROK_OPEN_OBSERVER`	`true`	是否打开可见观察窗口
`GROK_HEALTH_INTERVAL_MS`	`300000`	内部健康检查间隔，默认五分钟
`GROK_MAX_RUNTIME_MS`	`0`	可选的最大运行时间（毫秒），`0` 表示不限制

数据目录结构（默认）：

%USERPROFILE%\.grok-to-codex\
  sessions.json          # 会话映射
  logs\
    <会话键>.jsonl       # 观察窗口读取的实时日志

健康检查与任务等待（重要）

五分钟健康检查不是任务超时时间。
默认每隔约 5 分钟（GROK_HEALTH_INTERVAL_MS=300000）检查一次 Grok 进程与 ACP 通道是否仍然可用。
只要 Grok 正常运行，grok_task_start 可以一直等待到任务结束。
桥接程序会持续读取 ACP 事件，因此 Grok 完成后会立即返回结果。
若需要限制单次任务最长运行时间，请单独设置 GROK_MAX_RUNTIME_MS，或在 grok_task_start 中传入 max_runtime_ms；0 表示不限制。

权限说明

--always-approve 会取消 Grok 普通工具调用的人工确认，不代表获得 Windows 管理员权限。Grok 的拒绝规则、钩子（工具执行前后的自动检查）或管理员策略仍然可能阻止操作。

开发模式与发布模式

模式	如何启动	适用场景
开发模式	`npm run dev`（内部是 `tsx src/index.ts`）	本地改源码、调试 MCP 逻辑；直接跑 TypeScript，不依赖最新 `dist/`
发布 / Codex 使用模式	先 `npm run build`，再由 Codex 启动 `node ...\dist\index.js`，或执行 `npm start`	日常把任务交给 Grok；MCP 配置应指向编译后的 `dist/index.js`

补充说明：

观察窗口在运行时会启动同目录下的 observer.js。发布模式下对应 dist/observer.js。
开发模式下改动 src/ 后，重启 npm run dev 即可；发布模式下必须重新 npm run build，再重启 MCP。
Codex 集成请使用发布模式产物，避免把 tsx 开发链路写进 MCP 配置。

简短完整使用流程

# A. 准备本仓库
cd C:\Users\你的用户名\Desktop
git clone https://github.com/Nurkic4/grok-to-codex.git
cd grok-to-codex
npm install
npm run typecheck
npm test
npm run build

# B. 确认 Grok 可用
Get-Command grok
grok --help

# C. 在 Codex MCP 配置中加入 dist\index.js 的绝对路径与环境变量
# D. 重启 / 重新加载 Codex 的 MCP
# E. 在 Codex 中先 grok_session_ensure，再在需要落地改代码时 grok_task_start
# F. 查看弹出的观察窗口，或打开：
#    $env:USERPROFILE\.grok-to-codex\logs\

推荐提示词（可放进 Codex 自定义说明）：

当任务涉及代码项目时，先调用 grok_session_ensure 连接当前项目对应的 Grok 会话。当完成需求分析并需要进行具体的代码修改、命令执行或测试时，优先使用 Grok-Codex MCP 工具。Codex 负责规划、架构和审查，Grok 负责具体执行。

常见问题排查

1. `grok` 不在 PATH

现象：MCP 启动会话失败，日志或标准错误提示找不到 grok / 无法启动进程。

处理：

Get-Command grok -ErrorAction SilentlyContinue
where.exe grok

若找不到：把 Grok 安装目录加入用户或系统 PATH，新开 PowerShell / 重启 Codex 后再试。
或者在 MCP env 中设置 GROK_EXECUTABLE 为 grok.exe 的绝对路径。

2. 观察窗口不显示

可能原因与处理：

GROK_OPEN_OBSERVER 被设为 false / 0 / off / no：改回 true 或删除该变量以使用默认值。
尚未成功建立会话：先调用 grok_session_ensure；观察窗口通常在会话就绪时打开。
旧窗口已关闭：再次 ensure / 启动任务时，若检测到旧观察进程已不在，会尝试重新打开。
手动查看日志是否在写入：

Get-ChildItem "$env:USERPROFILE\.grok-to-codex\logs"
Get-Content "$env:USERPROFILE\.grok-to-codex\logs\*.jsonl" -Tail 20

也可手动打开观察窗口（把日志文件路径换成实际文件）：

node C:\Users\你的用户名\Desktop\grok-to-codex\dist\observer.js --file C:\Users\你的用户名\.grok-to-codex\logs\某个会话.jsonl

3. 日志目录在哪里

默认：

%USERPROFILE%\.grok-to-codex\logs\

PowerShell 打开：

explorer "$env:USERPROFILE\.grok-to-codex\logs"

若设置了 GROK_CODEX_BRIDGE_HOME，则日志位于该目录下的 logs\。会话注册表是同级的 sessions.json。

4. 五分钟健康检查是什么意思

它是运行中的存活/连通性检查，默认约每 5 分钟一次。
不是“任务最多跑五分钟就会超时”。
任务真正的可选超时由 GROK_MAX_RUNTIME_MS 或工具参数 max_runtime_ms 控制；默认为 0（不限制）。
健康检查失败时，会写入观察日志，并可能关闭异常的 Grok 进程；这与“正常完成任务后立即返回”是两回事。

5. `grok_task_start` 为什么一直不返回

正常现象：该工具会阻塞等待 Grok 做完当前任务。
请看观察窗口或 JSONL 日志中的阶段、工具调用和错误。
需要中止时，调用 grok_task_cancel。
不要把五分钟健康检查误判为超时；除非你显式配置了最大运行时间，否则任务可以一直跑到结束。

6. 改了代码但 Codex 行为没变

npm run build

然后重启 / 重新加载 Codex 的 MCP，确认配置仍指向最新的 dist\index.js。

开发和验证

npm run typecheck
npm test
npm run build

CI（.github/workflows/ci.yml）在 Node.js 20 上执行同样的顺序：npm ci → typecheck → test → build。

Available Tools

6 tools

grok_session_closeC

当 Grok 会话已经闲置且不再需要后台进程时调用。它会关闭工作进程，但保留会话映射，之后仍可尝试恢复。

ParametersJSON Schema

Name	Required	Description	Default
`branch`	No
`project_root`	Yes
`codex_task_id`	Yes
`working_directory`	No

TDQS

C2.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description adequately discloses key behaviors: it closes the worker but preserves session mapping for later recovery. However, it omits details on idempotency, error conditions (e.g., calling on non-idle session), and synchronization behavior, leaving notable gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (single sentence) but lacks structure; it front-loads the condition but omits critical parameter information, sacrificing completeness for brevity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 4 parameters, no output schema, and no annotations, the description is insufficient for correct usage. The missing parameter semantics and lack of behavioral detail leave the agent underinformed for this moderate-complexity tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the description provides no explanation for any of the 4 parameters (branch, project_root, codex_task_id, working_directory). The agent receives no guidance on how to populate these fields, making tool invocation guesswork.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool closes the worker process of an idle Grok session while retaining session mapping for potential recovery. This purpose is distinct from sibling tools like grok_session_ensure or grok_task_start, though it could be more explicit about differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description specifies when to call (session idle, no longer needs background processes), providing basic usage guidance. However, it lacks explicit exclusions or alternatives among siblings, and does not clarify when not to use it (e.g., for permanent termination).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

grok_session_ensureA

当任务涉及代码项目时，先调用此工具连接或创建当前 Codex 任务、项目路径和 Git 分支对应的 Grok 会话。它只建立会话，不会让 Grok 开始编码。

ParametersJSON Schema

Name	Required	Description	Default
`branch`	No
`project_root`	Yes
`codex_task_id`	Yes
`open_observer`	No
`working_directory`	No

TDQS

A3.6/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description must bear full burden. It reveals the tool only establishes a session, not coding, but omits details like session reuse, return values, error behavior, and parameter meanings, leaving significant gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with condition, no wasted words. Efficient and clear.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 5 parameters, no annotations, and no output schema, the description lacks explanation of parameters, return value, edge cases, and behavior under various inputs. Incomplete for robust agent usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so description should explain parameters. It mentions codex_task_id, project_root, and branch implicitly, but does not cover open_observer or working_directory. Partial value, but not sufficient to fully compensate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool connects or creates a Grok session for a Codex task, project path, and Git branch, and explicitly notes it only establishes a session, not coding. It distinguishes from siblings like grok_task_start and grok_session_close.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

States 'when tasks involve code projects, call this tool first', providing clear context. Also clarifies it does not start coding, implying other tools are for that purpose. Missing explicit alternatives, but context is strong.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

grok_session_switchB

当项目路径、工作目录或 Git 分支发生变化时调用，为新的上下文切换到独立的 Grok 会话，避免复用不相关的旧上下文。

ParametersJSON Schema

Name	Required	Description	Default
`branch`	No
`project_root`	Yes
`codex_task_id`	Yes
`open_observer`	No
`working_directory`	No

TDQS

B3.2/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses that the tool switches to an independent session and avoids reusing old context, but it does not explain what happens to the old session (e.g., suspended, closed) or any side effects. Since no annotations are provided, the description carries full burden and is insufficient for understanding behavioral impact.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, efficient and to the point. It covers the trigger and action without unnecessary words. However, it could be slightly expanded to include parameter hints without losing conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (5 parameters, 2 required, no schema descriptions, no annotations, no output schema), the description is too brief. It does not explain parameter roles, return values, or detailed behavior, leaving significant gaps for an agent to correctly invoke the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description provides no information about the parameters (codex_task_id, project_root, branch, etc.), even though schema coverage is 0%. The agent must rely solely on parameter names, which may be insufficient. The description fails to compensate for the lack of schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: to switch to an independent Grok session when project path, working directory, or Git branch changes. It uses a specific verb ('switch') and resource ('Grok session'), and distinguishes from siblings like grok_session_ensure (which likely creates/ensures a session) and grok_session_close (which closes one).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use the tool: when project path, working directory, or Git branch changes. It implies this is the correct tool for session switching and mentions avoiding reuse of irrelevant old context. However, it does not explicitly state when not to use it or name alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

grok_task_cancelA

当用户要求停止当前 Grok 工作，或确认任务已经失去响应时调用。它会取消任务并结束对应的 Grok 进程树。

ParametersJSON Schema

Name	Required	Description	Default
`branch`	No
`project_root`	Yes
`codex_task_id`	Yes
`working_directory`	No

TDQS

A3.7/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description carries the full burden. It discloses that the tool cancels the task and ends the process tree, but lacks details on potential side effects, reversibility, or required permissions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with two sentences, front-loading the purpose without wasted words. It is well-structured for quick understanding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simplicity of a cancel action and the presence of sibling tools, the description is largely complete. It lacks details on return values or error handling, but the context is sufficient for basic usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description does not explain any of the 4 parameters, even though schema description coverage is 0%. It fails to clarify the meaning of fields like codex_task_id, project_root, or working_directory, leaving the agent without necessary context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool is for canceling a Grok task and ending its process tree, and provides specific trigger conditions (user request or unresponsive task). It distinguishes from sibling tools like grok_task_start and grok_task_status.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context on when to use the tool (user wants to stop or task is unresponsive). However, it does not explicitly state when not to use it or mention alternatives, missing some guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

grok_task_startA

当 Codex 完成需求分析并需要具体修改代码、执行命令或运行测试时，使用此工具把明确任务交给 Grok。此调用会一直等待，直到 Grok 完成、失败、阻塞或被取消；等待期间不要并行执行其他项目工作。架构规划、需求判断和最终审查仍由 Codex 负责。

ParametersJSON Schema

Name	Required	Description	Default
`mode`	Yes
`branch`	No
`objective`	Yes
`constraints`	No
`project_root`	Yes
`allowed_paths`	No
`codex_task_id`	Yes
`open_observer`	No
`max_runtime_ms`	No
`working_directory`	No
`acceptance_criteria`	No
`verification_commands`	No

TDQS

A3.9/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses the critical blocking behavior and warns against parallel execution. It also clarifies that architecture and review are Codex's domain. Without annotations, this is useful context, though it does not cover error handling or return values.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise—three sentences that each add essential information: when to use, blocking behavior, and responsibility split. No redundant or filler content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite good purpose clarity, the description lacks parameter details and does not describe the return value or outcome of the call. With 12 parameters and no output schema, an agent lacks sufficient context to use the tool correctly without additional information.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 12 parameters with 0% description coverage, and the tool description does not explain any parameter's meaning or usage. The description mentions the task objective and mode only implicitly, leaving a significant gap for correct invocation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: to hand off tasks (code modification, command execution, testing) from Codex to Grok, and it distinguishes this tool by emphasizing its blocking behavior and the division of responsibilities (Codex handles planning and review).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains when to use the tool (after Codex completes requirements analysis) and what not to do (avoid parallel work during the blocking call). It also clarifies that planning and review remain with Codex. However, it does not explicitly contrast with sibling tools like grok_task_status or grok_task_cancel.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

grok_task_statusA

在用户要求查看进度、排查异常或确认 Grok 状态时调用。返回简短状态，不返回完整实时日志；不需要主动每隔几分钟轮询。

ParametersJSON Schema

Name	Required	Description	Default
`branch`	No
`project_root`	Yes
`codex_task_id`	Yes
`working_directory`	No

TDQS

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. It discloses that the tool returns brief status (not full logs) and recommends against polling. Missing details on error handling, side effects (likely none), and authorization.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with purpose, no wasted words. Efficient and clear.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Without an output schema, the description should clarify the return format and potential states. It only says 'brief status' but does not specify possible values or error responses, leaving the agent underinformed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description provides no parameter explanations. With four parameters (two required), the agent lacks guidance on values like project_root or codex_task_id.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool is for checking progress, troubleshooting, or confirming Grok status. It distinguishes itself from sibling tools (grok_task_start, grok_task_cancel, etc.) by focusing on status retrieval.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains when to call the tool (user wants status) and advises against frequent polling. However, it does not explicitly mention alternatives or when not to use the tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

6 tool updatesv0.1.0Jul 28, 2026
- First observedgrok_session_close
- First observedgrok_session_ensure
- First observedgrok_session_switch
- First observedgrok_task_cancel
- First observedgrok_task_start
- First observedgrok_task_status

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.8/5.0

Disambiguation5/5

Each tool has a distinct purpose: session creation, task start, status check, cancel, session switch, and close. No overlap or ambiguity.

Naming Consistency5/5

All tools follow a consistent 'grok_verb_noun' pattern (e.g., grok_session_ensure, grok_task_start), making it predictable.

Tool Count5/5

With 6 tools, the server is well-scoped, covering the full lifecycle of session and task management without unnecessary duplication.

Completeness5/5

The tool set covers all essential operations for managing Grok sessions and tasks: creation, starting, status, cancellation, context switching, and cleanup. No obvious gaps.

Maintenance

ActivitySlowing

ResponsivenessSyncing

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

AI Worlds CLI Knowledge A
com.claude-world
Source-checked CLI guides and model-aware planning for Claude Code, Codex, and Grok Build.
Command Line Developer Tools Documentation Access
121
PAPI: Persistent Adaptive Project IntelligenceOAuth
io.github.getpapi
Adaptive plan/build/review cycles for AI coding assistants, persisted across sessions.
Coding Agents Autonomous Agents
27
Bring Your AI A
ai.bringyour
No-data MCP handoff for local Claude Code to Codex harness moves. $49 lifetime.
Developer Tools Coding Agents
72
Planner MCP — provable "done" for AI agents A
com.monopoly-gold.planner
Goal and task planning MCP for Codex and AI agents, with evidence-backed completion.
421

Related MCP Servers

claude-code-codex-agents
Coding Agents Code Execution Autonomous Agents
tsunamayo7
A
license
A
quality
D
maintenance
Enables Claude Code to delegate tasks to OpenAI's Codex CLI (GPT-5.4) with structured execution traces, parallel execution, session persistence, and adversarial code review.
Updated 5 months ago (2026-04-03 15:10 UTC)
15
MIT
Grok-in-Codex
AI & Machine Learning Coding Agents Image & Video Processing
stdevMac
A
license
Not graded
quality
D
maintenance
Enables Codex to delegate code reviews, coding tasks, image/video generation, and background investigations to Grok via MCP tools.
Updated a month ago (2026-08-04 13:15 UTC)
22
Apache 2.0
grok-subagent
Agent Orchestration Coding Agents
Walvez
A
license
Not graded
quality
A
maintenance
Enables Codex to use Grok Build CLI as a controlled subagent via MCP tools for independent investigation, review, and isolated implementation tasks.
Updated a month ago (2026-08-03 15:29 UTC)
4
MIT
Grok Build Bridge
naplesblue
A
license
Not graded
quality
B
maintenance
Connects OpenAI Codex and Claude Code to the local Grok Build CLI for second-opinion code reviews, bounded coding tasks, web research, media generation, and TTS.
Updated a month ago (2026-07-24 05:03 UTC)
2
Apache 2.0

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Nurkic4/grok-to-codex'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

脚本	含义
`npm start`	以发布模式启动 MCP：`node dist/index.js`
`npm run dev`	以开发模式直接运行源码：`tsx src/index.ts`
`npm run observer`	以开发模式运行观察窗口源码（仍需自行提供 `--file` 日志路径）

Grok-Codex Bridge

协作分工

功能

环境要求

从 GitHub 克隆并安装（Windows PowerShell）

命令说明与完整验证流程

构建产物用途

确认 Grok CLI 已安装、可调用

Codex MCP 配置（Windows 绝对路径示例）

提供的工具

运行配置

健康检查与任务等待（重要）

权限说明

开发模式与发布模式

简短完整使用流程

常见问题排查

1. grok 不在 PATH

2. 观察窗口不显示

3. 日志目录在哪里

4. 五分钟健康检查是什么意思

5. grok_task_start 为什么一直不返回

6. 改了代码但 Codex 行为没变

开发和验证

Available Tools

Tool Schema Changelog

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

1. `grok` 不在 PATH

5. `grok_task_start` 为什么一直不返回