Use the local Grok CLI as a subagent through a standard stdio MCP server. Dispatch tasks, resume conversations, inspect progress, send follow-up instructions, and interrupt work.
The server supports Codex and Claude Code. registers the server and result hooks for either client at user level.
Use the local Grok CLI as a subagent in Codex and Claude Code via MCP, with asynchronous tasks, automatic result delivery, and session-scoped history management
Stars
2
Tools
—
Uptime
—
install.py
Requirements
Windows, Python 3.11+, uv, and an installed, authenticated Grok CLI.
No third-party Python dependencies. uv run creates the project environment.
Grok must support ACP session configuration and closing, and the x.ai/task and x.ai/subagent extensions.
Install
git clone https://github.com/cigenb/grok-subagent-mcp.git
cd grok-subagent-mcp
uv run python install.py codex # Codex
uv run python install.py claude # Claude Code
Both clients use the MCP server name grok and three mcp_tool hooks that call grok_collect:
PostToolUse and UserPromptSubmit collect results; Stop returns unread results or asks the model to wait for unfinished tasks.
Hooks do not wake an idle chat after its turn has ended. Uncollected results remain in the task database and can be retrieved when the conversation continues.
Codex
The installer backs up existing configuration, registers the grok MCP server in the user-level config.toml, and merges three MCP tool hooks into hooks.json.
Review and trust these definitions through /hooks in the Codex CLI, then start a new chat to load the server.
Codex uses the threadId supplied in call metadata as the source conversation.
Claude Code
The installer backs up ~/.claude/settings.json, registers the user-scope grok server through claude mcp add-json, and merges three hooks into settings.json. New sessions load both.
Tools appear as mcp__grok__grok_*; add mcp__grok to permissions.allow to skip per-call confirmation.
Claude Code does not send a conversation ID with tool calls. The server uses the session ID from the CLAUDE_CODE_SESSION_ID environment variable that Claude Code sets when it starts the server; this variable is not part of the documented Claude Code interface.
Resuming the same Claude session after a restart keeps access to its Grok sessions. Tasks follow the server process: if the conversation changes (for example through /clear) while the server keeps running, its earlier tasks stay with the new conversation.
Other MCP clients
Other MCP clients can use the same server with this stdio command:
uv run --directory "<install-dir>" python server.py --client claude
Other clients can supply --owner <source-conversation-id> or the source_id tool argument to preserve ownership across server restarts.
Without either, tasks are isolated to that MCP connection.
Tools
Tool
Purpose
grok_spawn
Dispatch a task with required prompt and scope; wait_s waits up to 60 seconds; session_id resumes a conversation
grok_wait
Wait for this conversation's tasks; timing out or cancelling the wait does not stop execution
grok_status
List tasks, or inspect ids; full=true returns the complete output
grok_steer
Send instructions to a running task, applied during subsequent processing
grok_interrupt
Interrupt a task and its subagents, preserving output and files already produced
grok_collect
Client hook interface that returns event-specific hook JSON
The default model is regular grok-4.7 with reasoning effort high. Explicit model and effort arguments override these values; a resumed conversation inherits the last successfully applied settings when they are omitted.
These settings are independent of the interactive Grok defaults. The process disables cross-session memory, retains conversation resume, and allows Grok to use its own subagents.
Grok runs with its sandbox off and tool execution automatically approved. Every call's scope must describe allowed read/write paths, prohibited actions, and acceptance criteria.
scope is an instruction to the model, not filesystem access control. The caller must verify artifacts and tests. Grok is instructed to report files created or changed by terminal commands in its deliverable list.
A Grok conversation can have only one active main task. Resuming retains its working directory. Each task closes its native session after finishing; resuming loads the saved history.
The bridge does not automatically create worktrees. Paths returned for Grok subagent worktrees are retained as artifacts.
Closing the MCP connection stops its Grok process tree. After restarting the server, callers can read saved output or resume registered conversations.
Data and cleanup
Runtime data lives under ~/.grok/cigenb-grok-mcp/codex/ or claude/:
tasks.sqlite3: source conversations, main and child session IDs, status, delivery state, and artifact paths.
logs/: per-process Grok diagnostics; several tasks may reference the same log.
backups/: client configuration backups made before installation.
Grok's native history remains in ~/.grok/sessions/, associated by session ID.
Shared caches, global logs, project deliverables, and worktrees are not removed with task history.
Use --client codex or --client claude to select the data partition:
uv run python manage.py --client codex list
uv run python manage.py --client codex inspect <task-id>
uv run python manage.py --client codex keep <task-id>
uv run python manage.py --client codex cleanup-plan --days 7 --out cleanup-plan.json
Default candidates are finished tasks whose results have been collected and whose conversation has not been used for seven days. Use --ids to select tasks explicitly, or --sessions to select every task of the given native Grok sessions.
Tasks sharing a native conversation are checked together. Active, unread, and retained tasks cannot be deleted.
The cleanup plan lists exact files, hashes, and artifacts to preserve. Review the list and obtain deletion confirmation before applying it:
uv run python manage.py --client codex cleanup cleanup-plan.json --confirm <confirmation-from-plan>
Cleanup invokes grok sessions delete for registered main and child sessions; that command may also delete corresponding remote history.
If tasks or files change after the preview, cleanup refuses to proceed and requires a new plan.
Process logs become eligible only after their MCP process has exited and every referencing task is already cleaned or included in the plan.
Configuration backups are retained separately. After cleanup, the task database retains ownership, session IDs, and artifact paths, while removing task and scope text.
GROK_MCP_BIN selects the Grok executable. GROK_MCP_DATA_DIR overrides the MCP data root, primarily for isolated tests.
Tests
uv run python -m unittest discover -s tests -v
uv run python tests/smoke.py
The second command calls Grok for real, creates files in a system temporary directory, and produces native test sessions.
Uninstall
Codex: run codex mcp remove grok, then remove the three handlers whose server is grok and tool is grok_collect from ~/.codex/hooks.json.
Claude Code: run claude mcp remove grok -s user, then remove the same three handlers from ~/.claude/settings.json.
Task data and native Grok history are retained separately.
Use the local Grok CLI as a subagent in Codex and Claude Code via MCP, with asynchronous tasks, automatic result delivery, and session-scoped history management
No tool list yet. Remote servers get one after the first health check.
FAQ
Questions
How do I install Grok Subagent?
Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.
Does Grok Subagent need an API key?
No required environment variable is listed on this record.
What transport does Grok Subagent use?
Grok Subagent runs locally over stdio.
When was Grok Subagent last checked?
Last checked 2026-10-27. Use the local Grok CLI as a subagent in Codex and Claude Code via MCP, with asynchronous tasks, automatic result delivery, and session-scoped history management