Content
# Grok-Codex Bridge
This is an MCP (Model Context Protocol) tool that allows Codex to delegate specific coding tasks to Grok Build CLI for execution. It has been tested that Grok 4.5's coding processing speed far exceeds other models, and its capabilities are not inferior when there are clear requirements or solutions. Since GPT 5.6's normal task processing speed is relatively slow, a coding agent is needed to assist Codex in doing dirty work.
## Collaboration and Division of Labor
- **Codex**: Responsible for demand understanding, architecture design, project planning, code review, and final decision-making.
- **Grok**: Responsible for specific code search, file modification, command execution, and testing.
- **Bridge Program**: Waits for tasks to be completed by Grok; writes the real-time process to the local log and displays it in an independent observation window.
You can use the following custom prompt to require Codex to use this tool after downloading and installing MCP:
> When tasks involve code projects, first call `grok_session_ensure` to connect to the Grok session corresponding to the current project. When completing demand analysis and needing to perform specific code modifications, command execution, or testing, prioritize using the Grok-Codex MCP tool. Codex is responsible for planning, architecture, and review, while Grok is responsible for specific execution; tool descriptions and return result definitions dictate the rest of the process.
## Features
- Each Codex task, project path, and Git branch corresponds to a Grok session.
- Control Grok Build CLI through ACP (Agent Client Protocol) standard input and output channels.
- Automatically approve Grok's ordinary tool permission requests through `--always-approve`.
- Perform internal health checks every five minutes; health checks are configured separately from the maximum running time.
- Do not send Grok's continuous process to the Codex context one by one.
- Provide a visible PowerShell observation window displaying task stages, tools, files, tests, errors, and health check results; automatically reopen if the old window is closed.
- Verify project paths and working directories.
- End the complete process tree (parent process and its child processes) on Windows when canceling tasks.
## Environment Requirements
- Node.js 20 or higher.
- Git (used to clone repositories from GitHub).
- Installed and authenticated Grok CLI.
- `grok` added to the `PATH` environment variable, or set `GROK_EXECUTABLE` to point to the Grok executable.
## Clone and Install from GitHub (Windows PowerShell)
The following commands can be directly copied; please modify the local path to your own directory as needed.
```powershell
# 1. Enter the directory where you want to store the repository
cd $env:USERPROFILE\Desktop
# 2. Clone the public repository
git clone https://github.com/Nurkic4/grok-to-codex.git
cd grok-to-codex
# 3. Confirm Node.js version (needs >= 20)
node -v
# 4. Install dependencies
npm install
# 5. Compile TypeScript to dist/
npm run build
```
After installation, you should see:
- `node_modules\`: dependencies
- `dist\index.js`: MCP service entry
- `dist\observer.js`: observation window entry
## Command Instructions and Complete Verification Process
| Command | Effect | Will generate `dist/` |
| --- | --- | --- |
| `npm install` | Install dependencies in `package.json` | No |
| `npm run typecheck` | Only perform TypeScript type checking (`tsc --noEmit`), do not output compiled products | No |
| `npm test` | Run unit tests in `tests/*.test.ts` | No |
| `npm run build` | Compile TypeScript, generate JS products under `dist/` | Yes |
Recommended complete verification sequence (consistent with repository CI):
```powershell
cd C:\Users\YourUsername\Desktop\grok-to-codex
npm run typecheck
npm test
npm run build
```
Description:
- **typecheck**: Find type errors as early as possible, suitable for frequent execution during development.
- **test**: Verify session keys, path boundaries, task prompts, default terminal configurations, and observation window survival judgments.
- **build**: Generate `dist/index.js` and `dist/observer.js` to be started by Codex MCP.
## Build Product Usage
| Product | Purpose |
| --- | --- |
| `dist/index.js` | MCP service main entry. Codex starts it through `node`, exposing the `grok_*` series of tools. |
| `dist/observer.js` | Independent observation window entry. The bridge program opens it with `node dist/observer.js --file <jsonl log>` when needed, reading JSONL logs in real-time and printing the task process. |
Related npm scripts:
| Script | Meaning |
| --- | --- |
| `npm start` | Start MCP in release mode: `node dist/index.js` |
| `npm run dev` | Run source code directly in development mode: `tsx src/index.ts` |
| `npm run observer` | Run observation window source code in development mode (still need to provide `--file` log path) |
## Confirm Grok CLI is Installed and Callable
The bridge program defaults to executing `grok` in `PATH`; you can also specify the absolute path through `GROK_EXECUTABLE`.
Check in a **new** PowerShell window:
```powershell
# Can grok be found in PATH?
Get-Command grok -ErrorAction SilentlyContinue
# View executable file location
where.exe grok
# Confirm the command can be started (based on your local Grok CLI actual support for help/version parameters)
grok --help
```
Judgment criteria:
1. **Installed and in PATH**: `Get-Command grok` returns command information, and `where.exe grok` prints the path.
2. **Not in PATH**: Configure `GROK_EXECUTABLE` for MCP, for example:
```powershell
# Example: Replace the path with your actual grok.exe location
$env:GROK_EXECUTABLE = "C:\Users\YourUsername\AppData\Local\Programs\grok\grok.exe"
```
3. **Authenticated**: This repository is not responsible for the Grok account login process. Please complete authentication according to the Grok CLI official method; if authentication is invalid, session connection or task execution will fail, and errors will appear in the observation window or logs under `%USERPROFILE%\.grok-to-codex\logs\`.
4. **Callable from terminal**: Run `grok` in a regular PowerShell without "unrecognized command" errors. The environment variables inherited by Codex startup MCP also need to find the same executable.
## Codex MCP Configuration (Windows Absolute Path Example)
Add this service to the MCP configuration used by Codex. **Please use the absolute path of the compiled entry file**, do not write it as a relative path.
```json
{
"mcpServers": {
"grok-to-codex": {
"command": "node",
"args": [
"C:\\Users\\YourUsername\\Desktop\\grok-to-codex\\dist\\index.js"
],
"env": {
"GROK_MODEL": "grok-4.5",
"GROK_ALWAYS_APPROVE": "true",
"GROK_OPEN_OBSERVER": "true"
}
}
}
}
```
Optional: When `grok` is not in PATH, add it to `env`:
```json
"GROK_EXECUTABLE": "C:\\Users\\YourUsername\\AppData\\Local\\Programs\\grok\\grok.exe"
```
Note:
- Use double backslashes `\\` for Windows paths in JSON, or use forward slashes `/`.
- MCP protocol data is only written to standard output; diagnostic information is written to standard error.
- The observation window is an independent console window that displays Grok's work process by reading JSONL (one JSON object per line) logs in the bridge program's data directory.
- Usually, you need to restart Codex / reload MCP after modifying the configuration or rebuilding `npm run build`.
## Provided Tools
- `grok_session_ensure`: Create or restore the Grok session corresponding to the current task.
- `grok_task_start`: Execute a coding, testing, or inspection task and wait for the task to complete before returning the result.
- `grok_task_status`: Return the brief status of the current task.
- `grok_task_cancel`: Cancel the current task and end Grok's process tree.
- `grok_session_switch`: Switch to an independent context corresponding to another project or branch.
- `grok_session_close`: Close idle Grok worker processes while retaining session mappings.
Each task should provide goals, allowed modification paths, constraints, acceptance criteria, and verification commands.
`grok_task_start` supports modes:
- `implement`: Implement/modify code
- `test`: Run or supplement tests
- `inspect`: Read-only inspection, troubleshooting
The call will wait until Grok completes, fails, blocks, is canceled, or triggers an optional maximum runtime limit.
## Runtime Configuration
| Environment Variable | Default Value | Description |
| --- | --- | --- |
| `GROK_CODEX_BRIDGE_HOME` | `%USERPROFILE%\.grok-to-codex` | Session registry and log directory |
| `GROK_EXECUTABLE` | `grok` | Grok executable |
| `GROK_MODEL` | `grok-4.5` | Model name passed to Grok |
| `GROK_TERMINAL_SHELL` | Windows uses `powershell.exe`, Unix uses the system default shell | Shell used when Grok creates a terminal through ACP |
| `GROK_ALWAYS_APPROVE` | `true` | Skip ordinary permission inquiries when starting Grok |
| `GROK_OPEN_OBSERVER` | `true` | Whether to open a visible observation window |
| `GROK_HEALTH_INTERVAL_MS` | `300000` | Internal health check interval, default five minutes |
| `GROK_MAX_RUNTIME_MS` | `0` | Optional maximum runtime (milliseconds), `0` means no limit |
Data directory structure (default):
```text
%USERPROFILE%\.grok-to-codex\
sessions.json # Session mapping
logs\
<session key>.jsonl # Real-time logs read by the observation window
```
### Health Check and Task Waiting (Important)
- **Five-minute health check is not task timeout.**
- Check every approximately 5 minutes (`GROK_HEALTH_INTERVAL_MS=300000`) if Grok process and ACP channel are still available.
- As long as Grok is running normally, `grok_task_start` can wait until the task is completed.
- The bridge program will continuously read ACP events, so it will return the result immediately after Grok completes.
## Permission Instructions
`--always-approve` will cancel Grok's ordinary tool call human confirmation, **not representing** obtaining Windows administrator privileges. Grok's rejection rules, hooks (automatic checks before and after tool execution), or administrator policies may still block operations.
## Development Mode and Release Mode
| Mode | How to Start | Applicable Scenarios |
| --- | --- | --- |
| **Development Mode** | `npm run dev` (internally `tsx src/index.ts`) | Locally modify source code, debug MCP logic; run TypeScript directly, do not depend on the latest `dist/` |
| **Release / Codex Use Mode** | First `npm run build`, then Codex starts `node ...\dist\index.js`, or execute `npm start` | Daily tasks are delegated to Grok; MCP configuration should point to the compiled `dist/index.js` |
Supplement:
- The observation window starts `observer.js` in the same directory during runtime. In release mode, it corresponds to `dist/observer.js`.
- In development mode, after modifying `src/`, restart `npm run dev`; in release mode, you must rebuild `npm run build` and restart MCP.
- Codex integration uses release mode products to avoid writing `tsx` development links into MCP configuration.
## Brief Complete Usage Process
```powershell
# A. Prepare this repository
cd C:\Users\YourUsername\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. Confirm Grok is available
Get-Command grok
grok --help
# C. Add the absolute path of dist\index.js and environment variables to Codex MCP configuration
# D. Restart / reload Codex's MCP
# E. In Codex, first grok_session_ensure, then grok_task_start when you need to make code changes
# F. View the popped observation window, or open:
# $env:USERPROFILE\.grok-to-codex\logs\
```
Recommended prompt (can be put into Codex custom instructions):
> When tasks involve code projects, first call `grok_session_ensure` to connect to the Grok session corresponding to the current project. When completing demand analysis and needing to perform specific code modifications, command execution, or testing, prioritize using the Grok-Codex MCP tool. Codex is responsible for planning, architecture, and review, while Grok is responsible for specific execution.
## Common Problem Troubleshooting
### 1. `grok` is not in PATH
Phenomenon: MCP startup session fails, log or standard error prompts cannot find `grok` / unable to start process.
Solution:
```powershell
Get-Command grok -ErrorAction SilentlyContinue
where.exe grok
```
- If not found: Add Grok installation directory to user or system `PATH`, **open** PowerShell / restart Codex and try again.
- Or set `GROK_EXECUTABLE` in MCP `env` to the absolute path of `grok.exe`.
### 2. Observation Window Not Displaying
Possible causes and solutions:
- `GROK_OPEN_OBSERVER` is set to `false` / `0` / `off` / `no`: Change it back to `true` or delete the variable to use the default value.
- Session has not been successfully established: Call `grok_session_ensure` first; the observation window usually opens when the session is ready.
- Old window has been closed: Re-`ensure` / start a task, if the old observation process is detected to be gone, it will try to reopen.
- Manually check if logs are being written:
```powershell
Get-ChildItem "$env:USERPROFILE\.grok-to-codex\logs"
Get-Content "$env:USERPROFILE\.grok-to-codex\logs\*.jsonl" -Tail 20
```
- You can also manually open the observation window (replace the log file path with the actual file):
```powershell
node C:\Users\YourUsername\Desktop\grok-to-codex\dist\observer.js --file C:\Users\YourUsername\.grok-to-codex\logs\some session.jsonl
```
### 3. Where are the logs?
Default:
```text
%USERPROFILE%\.grok-to-codex\logs\
```
Open in PowerShell:
```powershell
explorer "$env:USERPROFILE\.grok-to-codex\logs"
```
If `GROK_CODEX_BRIDGE_HOME` is set, the logs are located in `logs\` under that directory. The session registry is `sessions.json` at the same level.
### 4. What does the five-minute health check mean?
- It is a **running survival/connectivity check**, defaulting to approximately every 5 minutes.
- **Not** "tasks can only run for five minutes and will timeout".
- The optional timeout for a single task is controlled by `GROK_MAX_RUNTIME_MS` or the tool parameter `max_runtime_ms`; the default is `0` (no limit).
- Health check failure will write to the observation log and may close the abnormal Grok process; this is different from "returning immediately after a task is completed normally".
### 5. Why does `grok_task_start` not return?
- Normal phenomenon: The tool will block and wait for Grok to complete the current task.
- Please look at the observation window or JSONL logs for stages, tool calls, and errors.
- Call `grok_task_cancel` when you need to abort.
- Do not confuse the five-minute health check with timeout; unless you explicitly configure the maximum runtime, tasks can run until completion.
### 6. I modified the code, but Codex behavior did not change
```powershell
npm run build
```
Then restart / reload Codex's MCP, confirm the configuration still points to the latest `dist\index.js`.
## Development and Verification
```powershell
npm run typecheck
npm test
npm run build
```
CI (`.github/workflows/ci.yml`) executes the same sequence on Node.js 20: `npm ci` → `typecheck` → `test` → `build`.
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available