description: "Gemini subagent: drive the official Google Gemini CLI as a one-shot coding subagent inside DeepSeek Harness (subagent_gemini delegation tool)."
kind: "package-bundle"
dsh-subagent-gemini
发布状态：暂未发布到 npm / DSH 插件市场。
Gemini CLI 目前尚未提供 Gemini 4，且本插件需要用户自备 Gemini API key 才能完成端到端验证；
在验证通过前不提交市场收录，避免把未经验证的插件放给用户。代码、测试与 CI 均已就绪，验证后可发布。
想用 Gemini 4 请安装 dsh-subagent-antigravity。
English | 中文
Adds a Gemini subagent to DeepSeek Harness (DSH): a parent session can call
subagent_gemini to run a Google Gemini CLI coding agent in a separate process
inside the parent workspace, let it edit files and run commands on its own, and
get only the final answer back.
The shape is the same as the official Codex subagent (subagent_codex) and the
community Cursor subagent (cursor_code):
- Fresh process, fresh session — every delegation spawns a new
gemini --acp;
- Final answer only — the child's thoughts, tool calls and stderr never enter the parent conversation;
- One task per run — no follow-up input or continuation (use the native
subagent/fork backends for those);
- Safe diagnostics — failures report fixed stage/category facts, never stderr, paths or credentials.
Community plugin; not affiliated with Google. Gemini CLI is Google's official CLI — this plugin only drives it from DSH.
How it works
parent session (DeepSeek model)
│ calls tool subagent_gemini({ description, prompt })
▼
DSH subagent seam (ctx.subagents)
│ provider: gemini (registered by this plugin)
▼
@deepseek-ai/dsh-subagent-acp (official ACP subagent backend)
│ spawn, ACP handshake, auto-answered permissions, process-range cleanup, safe diagnostics
▼
gemini --acp --skip-trust (separate process, parent cwd)
│ uses Gemini CLI's own tools (file edits / shell / search / MCP …)
▼
final answer → parent conversation
This plugin owns the Gemini-specific parts — locating the executable, validating configuration
and detecting credentials at load time with actionable guidance. Process lifecycle and the ACP
protocol are handled by DSH's official backend, so a DSH upgrade does not require rewriting the protocol here.
Requirements
| Dependency | Version / notes |
|---|
| DeepSeek Harness | 0.2.1-rc.2 series (provides ctx.subagents and the ACP subagent backend) |
| Node.js | ^22.19.0 or >=24 |
| Google Gemini CLI | a build that supports --acp (0.60+, latest recommended) |
| Gemini credential | Gemini Developer API key (recommended), or Vertex AI / Code Assist variables |
Install the CLI:
npm install -g @google/gemini-cli
gemini --version
Install the plugin
From the DSH plugin market (recommended): search for dsh-subagent-gemini, install and enable it.
From the command line:
dsh plugin --profile desktop add dsh-subagent-gemini
Then add the package to that profile's package.json → dsh.profile.bundles and restart (or let the
profile recompose):
"dsh": {
"profile": {
"bundles": ["…", "dsh-subagent-gemini"]
}
}
Once enabled, every agent sees the global tool subagent_gemini (a running session picks it up on its next request).
Credentials (important)
Gemini CLI needs its own credential. Google account browser login (OAuth) no longer works: Google retired
the individual Gemini Code Assist OAuth client for Gemini CLI, and the CLI reports
"This client is no longer supported for Gemini Code Assist for individuals".
Use an API key instead:
- Create a key at https://aistudio.google.com/apikey;
- Store it where Gemini CLI looks (no plugin config required):
printf 'GEMINI_API_KEY=your-key\n' > ~/.gemini/.env
chmod 600 ~/.gemini/.env
Gemini CLI loads ~/.gemini/.env automatically. Environment variables also work:
GEMINI_API_KEY — Gemini Developer API;GOOGLE_GENAI_USE_VERTEXAI=true + GOOGLE_API_KEY — Vertex AI;GOOGLE_GENAI_USE_GCA=true — Google Code Assist license.
To pass variables to the child explicitly, use the plugin's env config (see below). The plugin never reads,
logs or returns secret values.
Usage
The model calls it like any other delegation tool:
{
"name": "subagent_gemini",
"arguments": {
"description": "Fix login timeout",
"prompt": "In the workspace, find the login request timeout and raise it from 5s to 15s, run the related tests, and reply only with what you changed and the test result."
}
}
description — 3–5 word task name shown in the subagent list;prompt — a self-contained task; the child cannot see the parent conversation, so include paths, constraints and acceptance criteria.
When the run finishes the parent receives a completion notice with Gemini's final answer or a safe failure
diagnostic. The child's tool traffic and reasoning stay out of the parent session.
Configuration
Override the subagent-gemini entry's config in a profile patch:
| Field | Default | Meaning |
|---|
providerName | gemini | Name registered on ctx.subagents; must be unique in one profile |
command | empty (auto-detect) | Path to the gemini executable; empty searches PATH, then ~/.local/bin, /opt/homebrew/bin, /usr/local/bin, … |
args | ['--acp', '--skip-trust'] | CLI arguments; --acp is always kept, --skip-trust is present by default |
model | empty (CLI default) | Fixed model id such as gemini-2.5-flash; becomes one --model argument |
permission | allow | Auto-answer for child permission requests: allow approves (edits/shell), reject declines (read-only) |
env | {} | Extra environment variables layered over the credential-scrubbed parent environment |
disposeEofGraceMs | 6000 | Time the child gets to flush after stdin EOF before escalation |
disposeGraceMs | 3000 | Failure-observation and SIGTERM→SIGKILL escalation grace |
Example — fixed model, read-only child:
- id: subagent-gemini
config:
model: gemini-2.5-flash
permission: reject
Security and permissions
permission: allow means unattended: the child may edit workspace files and run commands without a human
approval prompt. That is what makes delegated coding tasks possible; use it in trusted workspaces and review
git diff afterwards.--skip-trust trusts the parent workspace for the child session only, so a delegation never stalls on an
interactive trust prompt.- The child is a separate process with its own credential environment: DSH's subprocess seam scrubs credential-like
variables from the parent environment; only variables in
env are forwarded.
- No telemetry. No credential is read, logged or returned by this plugin; the key is managed by Gemini CLI itself.
Troubleshooting
| Symptom | Fix |
|---|
Delegation fails with a process-start diagnostic | gemini not found. npm install -g @google/gemini-cli, or set command to an absolute path |
Gemini API key is missing or not configured | No credential. Write ~/.gemini/.env as above (chmod 600) |
This client is no longer supported for Gemini Code Assist for individuals | The retired OAuth login is in use. Switch to an API key |
| Child starts but never answers / times out | Check network reachability of the Gemini API; if it needs a proxy, put HTTPS_PROXY in the plugin's env |
| Want to check the machine setup | Run npm run smoke in the plugin checkout (costs one API request and prints PONG) |
Compatibility and development
- Depends on the official
@deepseek-ai/dsh-subagent-acp@0.2.1-rc.2, so protocol work tracks the official backend;
- Unit tests:
npm test (32 cases: config normalization, executable discovery, credential detection);
- End-to-end self-check:
npm run smoke (requires an API key);
- Reference implementations: the official Codex subagent (
@deepseek-ai/dsh-subagent-codex) and the official ACP
backend (@deepseek-ai/dsh-subagent-acp); all three share the same ctx.subagents contract.
Uninstall
dsh plugin --profile desktop remove dsh-subagent-gemini
Then remove dsh-subagent-gemini from the profile's dsh.profile.bundles and restart.
License
MIT. Gemini CLI and its name belong to Google; this project is not affiliated with Google.
