gemini2codex
Provides tools for delegating frontend, general implementation, and writing tasks to Gemini via the local Antigravity CLI or the official Gemini API, including task spawning, messaging, follow-ups, status tracking, interruption, and writing operations such as polish, rewrite, and review.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@gemini2codex implement a responsive pricing page in this project and run the build"
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.
gemini2codex
gemini2codex runs a local stdio MCP server that allows Codex to delegate frontend development, general implementation, and writing tasks to Gemini. Codex handles task scoping, authorization, integration, and verification, while Gemini executes the delegated work.
Quick Start
Provide the following prompt to Codex to download, verify dependencies, build, configure MCP, and test the connection. Once installed, each MCP server startup checks GitHub for the latest stable release and automatically downloads, builds, and runs updates when available.
Please install and configure https://github.com/jiassia/gemini2codex so that this Codex session can delegate tasks to Gemini.
Perform the following steps autonomously:
1. Verify that Node.js 22+, npm, and Git are installed, check that Antigravity CLI (agy) is installed and authenticated, and install any missing build dependencies.
2. Clone the repository into a persistent local directory, run npm ci, and build from source.
3. Run npm run configure:codex to install the MCP configuration and automated delegation rules.
4. Verify the MCP initialization, tool listing, and ping. Once finished, report the installation directory and verification status, and suggest opening a new Codex session.
Execute the installation and configuration directly. Do not merely list instructions or ask the user to manually edit configuration files.Codex can also download, build, and launch a specific release of the stdio MCP service directly:
npx --yes --package=github:jiassia/gemini2codex#v2.3.0 gemini2codexRelated MCP server: personal_agent
Requirements
Node.js 22 or higher, npm, and Git.
On Windows, builds require the .NET Framework 4 C# compiler; the build script searches system directories for
csc.exe.The Antigravity CLI
agyis used by default and must be installed and authenticated beforehand. See the Antigravity official documentation for setup details. Ensureagyis in yourPATHor specify its absolute executable path withAGY_COMMAND.
Usage
Task orchestration tools include gemini_spawn_agent, gemini_send_message, gemini_followup_task, gemini_wait_agent, gemini_list_agents, and gemini_interrupt_agent. Dedicated writing tools include gemini_write, gemini_polish, gemini_rewrite, and gemini_review.
Codex delegates work using the following schema, setting workspace to the absolute path of the target project:
{
"task_name": "project_task",
"idempotency_key": "project-task-001",
"message": "Read the project instructions, implement the specified changes, run the project build, and report the actual results.",
"workspace": "C:/work/project",
"kind": "general",
"permissions": { "write": true, "native_tools": true }
}The kind field accepts frontend, general, and writing. File write access and native tool execution are disabled by default; enabling them in permissions grants Gemini the local user's permissions to modify project files and run tools.
Once Codex spawns a task, it uses the returned ID to inspect progress or send follow-ups. Use gemini_wait_agent with after_revision to fetch incremental updates; timeouts simply return the current task state. Tasks run without a default execution timeout and require gemini_interrupt_agent to halt explicitly. A completed status indicates that Gemini submitted its report, but actual filesystem changes and build outputs must still be verified.
An independent supervisor manages task states, allowing accepted tasks to continue running across MCP disconnections. Reuse the original idempotency_key if a submission result is ambiguous; using an existing key with different parameters returns a conflict error. If the supervisor process terminates, incomplete tasks are marked as EXECUTION_INTERRUPTED; inspect the filesystem and resume execution explicitly with gemini_followup_task. Synchronous writing operations run within the active request context, whereas long-running writing jobs that need disconnection recovery should use kind: "writing".
Configuration and Diagnostics
Codex configures environment variables according to .env.example; parent process environment variables take precedence. The default implementation model is gemini-3.8-flash-high and the writing model is gemini-3.8-flash-medium, configurable via AGY_AGENT_MODEL and AGY_MODEL. Model availability depends on the local CLI installation and account access.
To connect directly to the official Google Gemini API instead of the local CLI, set WRITER_PROVIDER=gemini-api, GEMINI_API_KEY, and GEMINI_API_MODEL simultaneously, selecting a model that supports the required thinking level. The server does not automatically switch providers. Keep all credentials in the local environment and never commit them to the repository.
Run gemini2codex --help for usage information, or run node dist/index.js --help when building from source. Both npm run healthcheck and the gemini_health MCP tool issue active requests to the configured provider. Standard server initialization, tool listings, and ping requests do not spawn agy.
License
LINUX DO Community
Thanks to the Linux.do community for its support and contributions.
Available Tools
14 toolsgemini_agent_cancelA
Cancel a queued or running task and stop its active process tree. Previously completed file changes remain for review.
Inputs: task_id (required).
gemini_agent_statusARead-only
Read durable task status, progress events, changed files, command exit codes, structured failure or final report. Tasks survive MCP reconnection; structured errors include failure_reason, retryable, error_id, explicitly incomplete partial output and recovery guidance when available. Completion records the agent report; independently check files and validation.
Inputs: task_id (required).
gemini_agent_submitADestructive
Delegate an autonomous frontend/general/writing task. Frontend and general use highest available thinking (high), writing uses medium. Default JSON-mode reads are scoped to workspace; writes require write=true. Explicit native_tools=true enables provider native tools with local user privileges, requires write=true, and does not track native effects. Commands grant an exact executable and fixed args; they run with local user privileges and must be reviewed before granting. Returns a task ID immediately; poll status for progress and results.
Inputs: task (required), workspace (required), kind, max_turns, +2 more.
gemini_followup_taskADestructive
Continue work on the same Gemini agent and retained context. Idle agents start a new run; running agents receive steering at the next boundary. Workspace and capabilities stay fixed.
Inputs: target (required), message (required).
gemini_healthARead-only
Explicit live provider probe: executable, authentication, exact model listing and READY generation. Unknown states are null.
Inputs: no named parameters.
gemini_interrupt_agentA
Interrupt a Gemini agent and stop active work. The agent remains available for follow-up with retained context; existing file changes remain.
Inputs: target (required).
gemini_list_agentsARead-only
List retained Gemini agents with names, stable IDs, status, messages, revisions and reports. Tasks and results survive MCP reconnection and remain available for follow-up.
Inputs: no named parameters.
gemini_polishCRead-only
Polish expression while preserving facts, numbers, names, URLs, paths, commands and identifiers.
Inputs: text (required), style, language, instruction, +1 more.
gemini_reviewBRead-only
Compare original and revised prose for fact drift and omissions. Structured editorial feedback; Codex remains the factual authority.
Inputs: revised (required), original (required), style, language, +2 more.
gemini_rewriteCRead-only
Restructure prose while preserving facts and literal technical content. Do not repeatedly polish the result.
Inputs: text (required), style, language, instruction, +1 more.
gemini_send_messageBDestructive
Send a message to a named or identified Gemini agent. JSON-mode agents discard stale proposed actions. Native-mode agents finish the current request before reading steering; native changes remain. Waiting agents resume when supplied an answer; completed agents retain messages without starting a run.
Inputs: target (required), message (required).
gemini_spawn_agentADestructive
Spawn a Gemini subagent, like Codex spawn_agent. Defaults to frontend / Gemini 3.8 Flash High. Specify task_name, message, existing absolute workspace and capabilities. Returns a durable id used as target for communication and follow-ups. Supply a stable idempotency_key to safely resubmit after an uncertain disconnect; the same key and request return the original task without executing again. Fixed command grants have local user privileges; inspect them before granting. permissions.native_tools=true explicitly enables provider native tools beyond fixed grants and requires write=true. Native effects are not tracked; independently verify the final report.
Inputs: message (required), workspace (required), kind, max_turns, +3 more.
gemini_wait_agentARead-only
Observe agy execution, tool activity, elapsed/silent time, messages and results. Pass returned revision as after_revision and compact=true for incremental events. until=update returns on new progress; until=attention streams MCP progress notifications while waiting for completion, input or a Gemini message. Bounded wait; no provider requests or retries.
Inputs: until, compact, targets, timeout_ms, +1 more.
gemini_writeBRead-only
Write prose from authoritative facts. One call per writing unit. Codex must check facts before final use.
Inputs: content (required), style, language, instruction, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
There are multiple overlapping pairs: gemini_spawn_agent vs gemini_agent_submit both start Gemini work, gemini_send_message vs gemini_followup_task both communicate with an existing agent, gemini_wait_agent vs gemini_agent_status both observe progress/results, and gemini_interrupt_agent vs gemini_agent_cancel both stop work. Descriptions help distinguish agent-oriented from task-oriented flows, but an agent can easily misselect between the parallel APIs.
All names use the gemini_ prefix and snake_case, but the action/resource ordering is inconsistent: gemini_spawn_agent, gemini_list_agents, gemini_wait_agent, and gemini_interrupt_agent use verb_noun, while gemini_agent_submit, gemini_agent_status, and gemini_agent_cancel use noun_verb. Prose tools like gemini_polish, gemini_rewrite, gemini_review, and gemini_write also break the agent/task noun pattern, making the naming scheme only partially predictable.
Fourteen tools is within a reasonable range for a server covering agent lifecycle, task lifecycle, prose operations, and health checks. The count is slightly inflated by two overlapping lifecycle families, but it is not excessive for the apparent scope.
The surface covers agent spawn/list/message/follow-up/wait/interrupt, task submit/status/cancel, prose write/polish/rewrite/review, and health probing. However, task listing is missing, and agent lifecycle lacks an explicit get/delete or terminate operation, which can create recovery gaps if IDs are lost or stale agents accumulate.
Maintenance
Related MCP Connectors
Shared task layer for AI agents: tasks, handoffs and decisions that persist across tools.
Task manager for AI agents. Orchestrate agents to achieve large goals in unified control plane.
Task tracking built for coding agents. Work is leased, so two agents never take the same SubTask.
Goal and task planning MCP for Codex and AI agents, with evidence-backed completion.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables Codex to delegate bounded work to external LLMs through role-based MCP tools, with worker health checks and audit logging.MIT
- AlicenseNot gradedqualityCmaintenanceEnables Codex to delegate explicitly assigned subtasks to a local runtime that executes them with user-configured models such as DeepSeek, Qwen, or Claude. All project modifications are gated behind generated diffs and human approval before being applied.MIT
- AlicenseNot gradedqualityBmaintenanceEnables delegating bounded tasks from Codex to Claude Code, including read-only reviews, isolated branch edits, long-running background work, and approval handling.MIT
- AlicenseNot gradedqualityCmaintenanceEnables Claude and Codex agents to delegate implementation, testing, research, or review tasks to each other through local MCP tools, while supporting persistent sessions, isolated editing workspaces, and reviewed integration. It also allows progress tracking, cancellation, model selection, and management handoff between providers.2MIT