claude-use-gemini-acp

Claude → Gemini via ACP

Spawn a Gemini CLI subprocess in ACP mode, send a prompt, stream the response to stdout, and terminate cleanly. No persistent session — one prompt, one response.

When to use

The task requires more context than fits in Claude's window
You want real-time Google Search grounding
You want a second opinion from a different model
The user says "ask Gemini", "use Gemini for this", etc.

Setup (first use only)

cd ~/.claude/skills/claude-use-gemini-acp/scripts
pnpm install

This installs @agentclientprotocol/sdk into the local node_modules/. Subsequent runs skip this step — pnpm caches the result.

Usage

GEMINI_MODEL=gemini-2.5-pro \
TARGET_CWD=/path/to/project \
node ~/.claude/skills/claude-use-gemini-acp/scripts/gemini-delegate.mjs \
  "Summarize the architecture in ARCHITECTURE.md and list the top 3 risks"

The response streams to stdout as Gemini generates it. Capture it for use in your response:

response=$(node ~/.claude/skills/claude-use-gemini-acp/scripts/gemini-delegate.mjs "your prompt")

Environment variables

Variable	Default	Description
`GEMINI_MODEL`	`gemini-2.5-pro`	Model to use
`GEMINI_CLI_VERSION`	`nightly`	gemini-cli package version (`nightly` or a specific semver)
`TARGET_CWD`	current working dir	Working directory passed to the Gemini session

How it works

Spawns pnpm dlx @google/gemini-cli@<version> --acp --yolo --model <model>
Connects via @agentclientprotocol/sdk's ClientSideConnection + ndJsonStream
Sends initialize → newSession → prompt over the ACP session
Streams agent_message_chunk deltas to stdout as they arrive
Terminates the subprocess once the prompt response completes

The --yolo flag (-y) auto-approves all tool calls inside Gemini's session.

Prompt construction tips

Include all relevant context in the prompt string — this is a fresh session with no prior history
Reference files by absolute path if you want Gemini to read them (it can use its filesystem tools)
Keep prompts focused: one clear task per invocation
For multi-step work, do multiple sequential invocations rather than one sprawling prompt

Error handling

If the script exits non-zero, check stderr for:

pnpm dlx download failures (network, auth)
Gemini auth errors (gemini auth login may be needed)
ACP initialization failures (version mismatch)

The script does not retry — if something fails, surface the error to the user and suggest re-running after fixing the root cause.