zwilling
Lets Claude consult Google's Gemini models (via the Antigravity CLI) for a second opinion, code review, or analysis of many large files at once, with file contents inlined as context and every exchange logged to a shared markdown file.
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., "@zwilling get Gemini's second opinion on src/auth.ts and src/session.ts"
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.
zwilling
A small local MCP server (stdio) that lets Claude Code consult Gemini for a second opinion, a code review, or reading many large files at once. Every exchange is appended to a markdown log in the project, so you and both agents can see what was said.
zwilling is a thin wrapper around the Antigravity CLI (agy), which replaces the deprecated Gemini CLI. It uses your existing agy sign-in. It holds no API keys and never calls a Gemini API directly.
Gemini runs with no tool access: it can't read or write files, run commands, or call MCP servers. It only sees the prompt and the file contents zwilling attaches after its own path checks. Claude Code stays the only agent that changes code.
Requirements
Node.js ≥ 20
Antigravity CLI on your
PATHasagy, signed in (runagyonce and follow the prompts)
Related MCP server: Deep Code Reasoning MCP Server
Install and build
git clone https://github.com/Cromewell/zwilling.git
cd zwilling
npm install # .npmrc sets legacy-peer-deps (works around a Debian npm 9 bug)
npm run build # compiles src/ to dist/
npm test # builds, then runs the vitest suite against a fake agyRegister with Claude Code
claude mcp add zwilling -s user -- node /absolute/path/to/zwilling/dist/index.js
claude mcp list # should show: zwilling ... ✔ Connected-s user makes it available in every project. Start a new Claude Code session afterwards so the tools load.
If Claude Code can't find agy (for example because it was started from a launcher whose PATH lacks ~/.local/bin), pass the PATH explicitly:
claude mcp add zwilling -s user -e PATH="$HOME/.local/bin:/usr/local/bin:/usr/bin:/bin" -- node /absolute/path/to/zwilling/dist/index.jsTools
Tool | Inputs | What it does |
|
| Ask a question or hand Gemini a task, optionally with files or a diff inlined as context. With |
|
| Code review of files and/or a git diff (at least one of them): concrete issues with file:line, severity, and a suggested fix. |
|
| Runs a named task template from |
|
| Gemini proposes a change as a unified diff. zwilling checks its paths and dry-runs it with |
| none | Runs |
|
| Returns the last N matching log entries, so Claude can recall earlier answers. |
ask_gemini also takes diff? and timeout_s?. timeout_s (10–1800) overrides the default timeout for one call, e.g. for a slow -high review.
Files
Each entry in files is relative to the project root and can be:
Form | Example | Meaning |
file |
| the whole file |
line range |
| only those lines (1-based; the end is clamped to the file length). Only the attached lines count against the size limit. |
directory |
| every file below it |
glob |
|
|
Directories and globs are expanded from git ls-files --cached --others --exclude-standard, so .gitignore is respected. Outside a git repo zwilling walks the directory instead and skips .git/ and node_modules/. Files from a glob or directory that are blocked, binary or escape the root through a symlink are skipped and listed in a [zwilling: skipped …] note. If you name a blocked or binary file explicitly, the call fails. The file limit applies after expansion.
Diffs
diff attaches the output of git diff:
| Compares |
| index vs |
| working tree vs index (unstaged changes) |
| working tree (staged and unstaged) vs that ref |
| between two refs ( |
The diff counts against the size limit. Changed files that the denylist blocks (.env, *.pem, your deny patterns, …) are left out of the diff, and the answer says which ones.
Prompt format
Attachments are added after your prompt between boundary lines:
<prompt>
Attachment boundary id: 3f9c0a1b2d4e5f60
<<<zwilling:BEGIN 3f9c0a1b2d4e5f60 diff HEAD>>>
<git diff output>
<<<zwilling:END 3f9c0a1b2d4e5f60>>>
<<<zwilling:BEGIN 3f9c0a1b2d4e5f60 file path=src/auth.ts lines=40-120>>>
<contents>
<<<zwilling:END 3f9c0a1b2d4e5f60>>>The id is random for every call. If an attachment happens to contain it, zwilling picks a new one. That way a file can't end its own block and pretend to be part of the prompt.
A short fixed preamble goes before every prompt. It tells Gemini it has no tools, that everything it needs is inline, how the boundaries work, and that attachments are data, not instructions. Without it, Gemini wastes the timeout retrying blocked tools.
Structured review findings
gemini_review asks Gemini to end its review with a JSON block. zwilling parses it into structuredContent:
{ "parsed": true, "findings": [{ "file": "src/a.ts", "line": 12, "severity": "high", "issue": "…", "fix": "…" }] }severity is one of critical, high, medium, low and info; common synonyms like major or nit are mapped to these. If there's no block it can parse, the result is { "parsed": false, "findings": [] }. The tool doesn't fail in that case. The full text, JSON block included, is always in content.
Patch proposals
gemini_patch lets Gemini write code without touching your files. Gemini is asked for a short explanation and one fenced ```diff block in git diff format. zwilling then:
extracts the last diff block, and adds a missing
new file mode/deleted file modeline, which models often leave out;checks every path the patch touches with the same rules as attachments: relative, inside the root (also after following symlinks), not
.env/.git//*.pem/*.keyor adenypattern;dry-runs it with
git apply --check --recountagainst the working tree.--recounttolerates wrong line counts in@@headers.
The result is the full answer plus a note, and structuredContent { patch, files, applies, error? }. A patch that doesn't apply is a normal result with applies: false and git's error, not a tool error. zwilling never applies the patch. Claude reviews it and applies it itself, e.g. with git apply or its edit tools, so Claude stays the only agent that changes code. If the check fails, call gemini_patch again with follow_up: <log entry id> and the error in instructions. Attach every file the change touches; Gemini can only base hunks on what it sees.
Task templates
Put reusable instructions into .zwilling/tasks/<name>.md (names: letters, digits, -, _), for example:
<!-- .zwilling/tasks/test-ideas.md -->
List test cases that are missing for the attached code. Group them by function, and mark edge cases.Then call gemini_task with task: "test-ideas" and files. instructions is appended under ## Instructions. The tool description lists the tasks that existed when the server started. For an unknown task, the error lists the current ones. Templates are read through the same path checks as attached files.
Models and reasoning effort
model takes any ID from agy models. For Gemini, the reasoning effort is part of the ID:
gemini-3.8-flash-low
gemini-3.8-flash-medium
gemini-3.8-flash-highIf you leave model out, zwilling uses reviewModel (for gemini_review) or model from the configuration (see below). If neither is set, agy uses its default from ~/.gemini/antigravity-cli/settings.json ("model"), which you can also change with /model inside agy. Higher effort is slower: with medium effort, a review of two files took 19–83 s. list_gemini_models shows the IDs your agy accepts.
Comparing models
ask_gemini with models: ["gemini-3.8-flash-low", "gemini-3.8-flash-high"] runs one agy per model in parallel, with the same prompt and files. The answers come back one after the other, each under a heading:
## [zwilling] model: gemini-3.8-flash-low
<answer>
## [zwilling] model: gemini-3.8-flash-high (failed)
<error>Each run gets its own log entry. If only some models fail, their errors are shown inline and the call succeeds; it's an error only if every model failed. model and models can't be combined.
Configuration
zwilling reads an optional .zwilling.json from the project root when it starts, then applies ZWILLING_* environment variables on top. Environment variables win over the file, except ZWILLING_DENY, which adds to the file's deny. If the file or a variable is invalid (bad JSON, unknown key, out-of-range number), the server refuses to start and prints the reason to stderr.
{
"model": "gemini-3.8-flash-medium",
"reviewModel": "gemini-3.8-flash-high",
"limits": { "maxFiles": 40, "maxTotalKB": 1000, "timeoutMs": 240000 },
"deny": ["secrets/", "*.sqlite", "config/prod.*"],
"prompts": { "review": ".zwilling/review.md" },
"log": { "path": "docs/ai/GEMINI_LOG.md", "enabled": true },
"cli": "agy"
}Key | Variable | Default | Meaning |
— |
|
| Project root. File paths are confined to it, |
|
|
| Default model for |
|
|
| Default model for |
|
|
| Max files per call, after glob/directory expansion. |
|
|
| Max KB of attachments per call (files plus diff). |
|
|
| Kill |
|
| none | Extra paths to block. A pattern without |
|
| built-in | Root-relative file whose text replaces the built-in review instructions. |
|
|
| Where the shared log goes (relative to the root; paths outside the root, also via symlink, or inside |
|
|
| CLI binary to run: a name on |
Example: claude mcp add zwilling -s user -e ZWILLING_TIMEOUT_MS=180000 -- node …/dist/index.js
Shared log
Every call to ask_gemini, gemini_review, gemini_patch or gemini_task that reaches agy (successful or not) is appended to docs/ai/GEMINI_LOG.md in the project root (see log in Configuration). The file is created if it's missing.
<!-- zwilling:entry id=g-20261113-a1b2c3 -->
## 2026-11-13 19:45 · ask_gemini · model: default · id: g-20261113-a1b2c3
**Prompt:** <prompt on one line, first 500 chars>
<details><summary>Full prompt</summary> (only if the line above isn't the exact prompt)
…
</details>
**Files:** (diff: staged), src/auth.ts, src/session.ts:40-120
**Follow-up of:** g-20261113-0f9e8d (only for follow-ups)
**Answer:**
<full answer>
---Every entry has an id. The tool result ends with a separate text block [zwilling: log entry g-…] (several ids for a multi-model call), so Claude can refer to it later.
The HTML comment is invisible when the markdown is rendered. zwilling uses it to split entries, because answers often contain --- or headings themselves; if logged text contains the marker itself, it's defused with a zero-width space. Failed calls show **Error:** instead of **Answer:**. Calls rejected before reaching agy (a blocked path, too many files, an invalid diff) are not logged. gemini_task entries show up as gemini_task:<task>; a multi-model call writes one entry per model. Entries from older versions (marker without id) can still be read, but have no id and only a 500-character prompt preview.
Parallel calls are written one after another, so entries never interleave.
The log is also available as MCP resources: zwilling://log (the whole log) and zwilling://log/{id} (one entry; the last 50 are listed).
Decide per project whether to commit the log or add it to .gitignore.
Follow-ups
ask_gemini with follow_up: "<id>" looks up that entry and puts its full question and answer in front of the new prompt:
[Earlier exchange, log entry g-20261113-a1b2c3]
Files attached then (not attached again unless listed below): src/auth.ts
Question:
<earlier prompt>
Your answer:
<earlier answer>
[Follow-up question]
<new prompt>Only that one entry is included, not its own history: a follow-up of a follow-up sees the previous question and answer, but not the exchange before it. Files from the earlier call are named but not sent again; pass them in files if Gemini needs them. Unknown ids, entries without an answer (failed calls), and a disabled log return a tool error.
Safety
Your data goes to Google. The prompt, every file you attach with
files(including everything a glob or directory matches) and anydiffare sent to Gemini throughagy, under your Google account's terms. Don't attach anything you wouldn't share with Google.No shell.
agyis started with an argument array. The prompt goes over stdin as onestream-jsonmessage, so it isn't limited by the 128 KB per-argument limit on Linux and is never parsed as flags.Read-only Gemini. zwilling never passes
--dangerously-skip-permissions. Each run gets one-off--settings(never saved) that denyread_file(*),write_file(*),command(*),mcp(*),read_url(*),execute_url(*)anddownload_url(*), plus--sandbox. Deny rules apply in everyagymode. File reads are denied too becauseagy's permission rules don't support globs, so*.pemcouldn't be blocked selectively.Path confinement. Every path is resolved against the root and rejected unless it's still inside the root after
realpath. That blocks../and symlink escapes..env,.env.*,*.pem,*.keyand anything in.git/are rejected, also when reached through a symlink.denypatterns from the configuration add to this list and can't remove from it. The same checks apply to every file a glob or directory expands to, and to review and task templates. Binary files (a NUL byte) are rejected.Patches.
gemini_patchonly runsgit apply --check(a dry run, withLC_ALL=C, no shell,-c core.fsmonitor=false) after its own path checks; it never writes to the working tree. The patch text is returned for Claude to review.Diffs.
gitis run withexecFile(no shell). Thediffvalue has to look likestaged,working, a ref or a ref range: no leading-, no spaces and no:, so it can't be passed as an option. Pathspecs come after--as:(literal)…. zwilling passes--no-ext-diff --no-textconvand-c core.fsmonitor=false, so a repository's config can't makegitstart an external diff tool, textconv filter or fsmonitor program. Blocked files are left out of the diff.Prompt boundaries. Attachments are wrapped in boundary lines with a random id per call, and the preamble tells Gemini to treat their contents as data. This makes it harder for a file to pose as part of the prompt, but like any defence against prompt injection it isn't watertight.
Limits. By default at most 20 files and 500 KB of attachments (files plus diff) per call; see
limitsin Configuration. A file over 20 MB is refused even with a line range. Answers over 100 KB are truncated, and the response says so.agy's output is read line by line as it arrives, so long streams don't pile up in memory; a single output line over 16 MB is dropped.Timeout. After 120 s (
limits.timeoutMs, ortimeout_sper call),agy's whole process group gets SIGTERM, then SIGKILL 2 s later. The same happens when the client cancels the call or the server shuts down, so noagyprocess is left behind.stdout is only for the protocol. All diagnostics go to stderr.
Errors as tool results. A missing
agy, a non-zero exit, anERRORstatus or a timeout come back asisError: truewithagy's error and stderr. The server doesn't crash.
Known limitations
Web search.
agy'ssearch_webtool has no permission action, so zwilling can't block it. It can't touch local files, but parts of your prompt could end up in a Google search query. The preamble tells Gemini not to use any tools.No exploring. Gemini can't look around the repository by itself. Attach everything it should see with
files(globs and directories help) ordiff. Lettingagyread files itself isn't safe: tested with agy in November 2026, an allowedread_filealso read files outside the workspace despiteallowNonWorkspaceAccess: false, a directory-scopedallowrule had no effect (unmatched reads are approved in print mode), anddenybeatsallow. So reads stay denied entirely.Structured findings depend on Gemini. If Gemini leaves out the JSON block or gets it wrong,
structuredContentis{ "parsed": false, "findings": [] }, and only the text is usable.Large results. Claude Code warns above 10k tokens of tool output and saves results over 50,000 characters to a file. Long answers, or
read_gemini_logwith a largelast_n, may arrive that way.MCP Inspector. The Inspector CLI gives up after 60 s and doesn't request progress updates, so slow reviews time out there. Claude Code has no such limit for stdio servers. If a client sends a
progressToken, zwilling sends a progress update every 10 s, e.g.waiting for agy (30 s, 1840 chars received). It reports only how much text has arrived, never the text itself.
Suggested CLAUDE.md / AGENTS.md snippet
## Working with Gemini
- You have a `zwilling` MCP server.
- Use `gemini_review` with `diff: "HEAD"` (plus key `files` for context) before finishing any non-trivial change.
- Use `ask_gemini` with `files` when a task needs reading many large files at once.
- Gemini has no tool access: attach everything it needs via `files` (paths, `path:10-80`, `src/`, `src/**/*.ts`) or `diff` (max 20 files / 500 KB by default).
- `gemini_task` runs the project's templates in `.zwilling/tasks/`.
- `gemini_patch` returns a checked but unapplied diff: review it before applying it yourself.
- Optional `model`: gemini-3.8-flash-low | -medium | -high (effort level). Omit for the default.
- Treat Gemini's answer as a second opinion: verify claims against the code before acting.Development
src/index.ts server setup, tool registration, shutdown handling
src/gemini.ts runs agy: arguments, read-only settings, timeout, streaming output parsing, `agy models`
src/config.ts .zwilling.json + ZWILLING_* env loading and validation
src/paths.ts root, path validation, denylist, globs/ranges, file limits, prompt building
src/glob.ts minimal glob matching and deny-pattern matching
src/git.ts git diff: spec validation, safe invocation, blocked-file filtering
src/review.ts review prompts and parsing of structured findings
src/tasks.ts task templates in .zwilling/tasks/
src/patch.ts gemini_patch: diff extraction, path checks, git apply --check
src/log.ts markdown log: entry ids, append (serialized), read/parse, path checks
test/ vitest; test/fixtures/bin/agy is a fake agy put first on PATHTo try the server by hand: npx @modelcontextprotocol/inspector --cli node dist/index.js --method tools/list
License
ISC, see LICENSE.
zwilling is an independent project and is not affiliated with or endorsed by Google. Gemini and Antigravity are trademarks of Google LLC.
This project was coded with AI. It has been reviewed and tested to the best of my knowledge and belief.
Available Tools
6 toolsask_geminiA
Ask Gemini (via the Antigravity CLI) a question or hand it a task, optionally with files as context. Gemini runs without tool access: it only sees the prompt and the inlined files. Good for second opinions and reading many large files at once.
Inputs: prompt (required), diff, files, model, +3 more.
gemini_patchA
Have Gemini propose a code change as a unified diff. zwilling checks the paths it touches (same rules as attachments) and dry-runs it with git apply --check against the working tree, but never applies it: review it and apply it yourself. Attach every file the change touches. If it doesn't apply, call again with follow_up and the error.
Inputs: instructions (required), diff, files, model, +2 more. Returns: error, files, patch, applies
gemini_reviewA
Have Gemini review files and/or a git diff and list concrete issues (file:line, severity, suggested fix). Returns the written review plus structured findings. Give files, a diff, or both.
Inputs: diff, files, focus, model, +1 more. Returns: parsed, findings
gemini_taskB
Run a named task template from .zwilling/tasks/.md in the project (e.g. explain, test-ideas, migration-plan), with optional extra instructions, files and diff. Gemini still has no tool access. No task templates found in this project yet.
Inputs: task (required), diff, files, model, +2 more.
list_gemini_modelsARead-only
List the model IDs accepted by the model / models parameters (runs agy models).
Inputs: no named parameters.
read_gemini_logARead-only
Return entries of the shared Gemini log (docs/ai/GEMINI_LOG.md), to recall earlier Gemini answers. Filter by id, tool or a search text; returns the last N matches.
Inputs: id, tool, query, last_n.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
The four Gemini-calling tools have reasonably distinct framing: ask_gemini for open questions, gemini_review for issue-finding, gemini_patch for diffs, gemini_task for templated runs. There is still conceptual overlap (a well-worded ask_gemini or a review-style task template can approximate gemini_review), but the descriptions steer selection adequately. The two supporting tools (list_gemini_models, read_gemini_log) are clearly separate.
All names are snake_case, but three different patterns coexist: verb_gemini_noun (list_gemini_models, read_gemini_log), verb_noun (ask_gemini), and gemini_noun (gemini_review, gemini_patch, gemini_task). The split between 'ask_gemini' and 'gemini_review' is especially arbitrary. Readable, but no predictable rule an agent can rely on.
Six tools is well within the sweet spot and each maps to a distinct workflow: model discovery, log recall, open Q&A, review, patch proposal, templated tasks. Nothing looks like filler or a redundant alias.
Core lifecycle for a Gemini-assist wrapper is covered: discover models, ask, review, patch, run templates, and recall history. The main gap is task-template discoverability — gemini_task requires knowing .zwilling/tasks/<task>.md names, and there is no list_task_templates tool (the description even notes no templates were found). Applying a patch is deliberately excluded and documented, so that is not a real gap.
Maintenance
Related MCP Connectors
Multi-brand AI code review for Claude: up to 12 reviewers and a judge, no install.
Shared work memory for Claude Code, Codex, Cursor and chat, scoped to each repository.
Your AI apps as one team: hand work to Codex or Claude Code on your Mac, with a shared logbook.
Campfyrr, shared team memory for Claude Code
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables Claude Code to consult Gemini for complex coding problems with session management, file attachments, and conversation persistence.106MIT
- AlicenseNot gradedqualityAmaintenanceEnables Claude Code to delegate complex code analysis to Gemini AI, supporting execution-flow tracing, cross-system impact analysis, performance bottleneck detection, hypothesis testing, and multi-turn conversational debugging.MIT
- AlicenseNot gradedqualityAmaintenanceEnables Claude Code to escalate complex code-analysis tasks to Google Gemini for large-context execution tracing, cross-system impact analysis, performance bottleneck detection, and hypothesis testing.MIT
- AlicenseNot gradedqualityAmaintenanceEnables Claude Code to escalate complex code analysis to Google's Gemini AI for multi-model reasoning, including execution tracing, cross-system impact analysis, performance bottleneck detection, and hypothesis testing over large codebases and logs.MIT