Skip to main content
Glama

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 gemini2codex

Related 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 agy is used by default and must be installed and authenticated beforehand. See the Antigravity official documentation for setup details. Ensure agy is in your PATH or specify its absolute executable path with AGY_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

MIT

LINUX DO Community

Thanks to the Linux.do community for its support and contributions.

Available Tools

14 tools
gemini_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_statusA
Read-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_submitA
Destructive

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_taskA
Destructive

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_healthA
Read-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_agentsA
Read-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_polishC
Read-only

Polish expression while preserving facts, numbers, names, URLs, paths, commands and identifiers.

Inputs: text (required), style, language, instruction, +1 more.

gemini_reviewB
Read-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_rewriteC
Read-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_messageB
Destructive

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_agentA
Destructive

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_agentA
Read-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_writeB
Read-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

    B3.1/5.0

    Scored across 14 tools

    Disambiguation2/5

    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.

    Naming Consistency2/5

    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.

    Tool Count4/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables Codex to delegate bounded work to external LLMs through role-based MCP tools, with worker health checks and audit logging.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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.
      2
      MIT