CHANGELOG.md

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[0.8.0] - 2026-05-21

Deprecated

• Project deprecated and unmaintained. Google is retiring Gemini CLI on 2026-06-18 in favor of Antigravity CLI. After that date, Gemini CLI stops serving requests for Google AI Pro, Ultra, and free-tier (Gemini Code Assist for individuals) accounts. Enterprise customers on paid Gemini Code Assist Standard/Enterprise licenses retain access. Because this bridge wraps Gemini CLI as a subprocess, it stops working for individual users on the same date.
• README updated with a prominent deprecation banner and migration pointers (Antigravity CLI, sibling claude-mcp-bridge / codex-mcp-bridge).
• package.json description prefixed with [DEPRECATED] so npmjs.com listings surface the status. The npm package will be marked deprecated (npm deprecate) and the GitHub repository archived after this release publishes.

No code changes in this release. Existing installs continue functioning until 2026-06-18.

[0.7.0] - 2026-04-26

Removed (BREAKING)

• review tool: bundled reviewer prompts + depth selector + stripReviewPreamble + anchor sets. Caller-supplied prompts via the existing query tool, or direct gemini -p invocation, replace it. The gemini ecosystem ships several review surfaces (Code Review extension, skills, subagents, Code Assist, third-party MCP servers); the bridge is the wrong layer to add another.
• assess tool: depth recommender calibrated to review's depth grammar. Without review, the rubric has no anchor.
• prompts/review-{agentic,focused,quick}.md: review prompt templates.
• policies/review.toml: review policy file.
• src/utils/git.ts: review/assess were the only consumers.

Rationale: docs/decisions/001-remove-review-and-assess-tools.md.

Changed

• Tool surface is now query, structured, search, fetch-chunk, ping (5 tools).
• README adds a "Code review with this CLI" section pointing to the gemini ecosystem's review surfaces in priority order.
• server.json description tightened to fit the 100-char registry limit.

[0.6.0] - 2026-04-21

Added

• changeMode on query tool: opt-in flag that asks Gemini to emit structured **FILE: <path>:<start>-<end>** / ===OLD=== / ===NEW=== edit blocks instead of prose. Legacy OLD: / NEW: markers are still parsed per-block for back-compat. Parsed edits are returned on _meta.edits as a machine-applicable array (never chunked) while the raw response stays in response (chunked normally).
• Change-mode write guardrail: pre/post-spawn snapshot of tracked-file mtime+size and git status --porcelain under the working directory. If Gemini mutates any file during the spawn, _meta.appliedWrites is set to true and edits is omitted so callers can't re-apply half-applied state. Requires a git working directory.
• prompts/change-mode.md template: strict output contract instructing Gemini to emit edit blocks only, without applying writes.
• src/utils/changeMode.ts: edit-block parser with primary (:<start>-<end>) and bare (**FILE: <path>**, content-inferred range) header formats, path realpath check against the working directory, and same-file overlap rejection. Uses ===OLD=== / ===NEW=== section markers to avoid collision with legacy OLD: / NEW: lines that can appear naturally in YAML, config files, or string literals. Legacy OLD: / NEW: markers are still accepted as a fallback.
• src/utils/workdirSnapshot.ts: cheap tracked-file snapshot + diff used by the change-mode guardrail.
• query-change-mode smoke target: node scripts/smoke-test.mjs query-change-mode <repo> exercises the full change-mode path end-to-end.
• MCP Registry manifest (server.json): registers the bridge with the official MCP Registry so it shows up at registry.modelcontextprotocol.io and downstream aggregators (PulseMCP, FindMCP, VS Code @mcp gallery).
• mcpName in package.json (io.github.hampsterx/gemini-mcp-bridge): required for Registry ownership verification on publish. Env var defaults in server.json are strings per Registry validation.

Note

• Change mode rejects image files for v1 and refuses to run in non-git working directories (the guardrail needs git ls-files / git status).
• Spawn uses default agentic mode (no --approval-mode plan, no --yolo) because plan mode refuses to emit edit blocks (verified on CLI 0.38.0). The snapshot guardrail is the safety net against the default-mode write capability.

[0.5.0] - 2026-04-20

Added

• Response chunking for query, review, and search: oversized text responses now return chunk 1 plus cache metadata instead of risking MCP client truncation. Cache is in-memory, 10-minute TTL, max 50 entries, with logical-boundary chunk splitting where possible.
• fetch-chunk tool: retrieves cached follow-up chunks using cacheKey and a 1-based chunkIndex.
• Chunking smoke coverage: node scripts/smoke-test.mjs fetch-chunk validates the cache round-trip without restarting the MCP client.
• assess change-kind classification: empty, code, mixed, non-code, generated. Returned alongside complexity so callers can decide whether a diff is worth reviewing at all. Documentation-only diffs are still reviewable by default rather than auto-dismissed as churn.
• assess guidance field: human-readable recommendation string tailored to the detected change kind and complexity.
• Spawn pacing controls: GEMINI_MIN_INVOCATION_GAP_MS enforces a minimum gap between CLI start times; GEMINI_SPAWN_JITTER_MAX_MS adds small randomized startup jitter. Concurrency limits and queue behavior unchanged.
• Structured capacity-failure metadata for deep reviews: explicit 429 / 503 / RESOURCE_EXHAUSTED responses surface as structured metadata on the review result instead of triggering an internal retry. Callers can now decide whether to back off, downgrade depth, or retry.

Changed

• Server response formatting: prose-style tool responses now flow through a shared formatter that can append metadata and apply chunking consistently.
• structured tool left unchunked intentionally: preserves machine-consumable JSON output instead of returning partial payloads.
• Deep review no longer falls back internally on capacity errors: previously a 429 or 503 would trigger a retry. Now it returns structured capacity metadata for the caller. Other tools and review depths keep existing fallback behavior.

[0.4.0] - 2026-04-14

Added

• assess tool: zero-cost diff analysis pre-flight. Runs git diff --numstat and --name-only locally (no CLI spawn, no model call) and returns diff stats, changed file list, complexity classification (trivial/moderate/complex), and suggestions for which review depth to use with estimated wall-clock times. Use before review to set timeout expectations. Cross-cutting detection uses top-level directory count (3+ distinct dirs = complex).
• depth parameter on review: three tiers replace the binary quick/agentic split.
  • scan: diff-only, single-pass, no repo exploration. Constant 180s timeout.
  • focused: diff + CLI reads changed files in plan mode (no shell). Timeout scales 120s + 15s * files, capped at 300s; falls back to 240s when diff stat is unavailable.
  • deep (default): full agentic exploration with --yolo. Timeout now scales 240s + 45s * files (was 180s + 30s * files), capped at 1800s; fallback 600s.
• buildFocusedPrompt / prompts/review-focused.md: new prompt template for focused reviews. Instructs the CLI to read changed files only and acknowledges that some changed files may be unreadable (deleted, renamed-away, binary, generated, gitignored).
• scaleTimeoutForDepth, defaultTimeoutForDepth, resolveDepth: new exports on src/tools/review.ts for per-depth timeout and input resolution.

Changed

• ReviewResult.mode values: "agentic" | "quick" → "scan" | "focused" | "deep". Breaking for callers inspecting result.mode. Pre-1.0 so a minor bump covers this mechanically, but call it out: anyone checking result.mode === "quick" or === "agentic" needs to update to the new values.
• Deep (previously agentic) timeout scaling: per-file budget raised from 30s to 45s and base from 180s to 240s. A 10-file diff goes from 480s to 690s. The user explicitly picked deep, so don't cut it short.
• Partial response hint: timeout annotations now read consider depth: "scan" or narrow the base (was consider quick: true or narrow the base). Scan timeouts are no longer annotated — no shallower alternative exists.
• Tool description on review: rewritten to explain the three depths and new timeout formulas.

Deprecated

• quick parameter on review: superseded by depth. Still works for backwards compatibility: quick: true → depth: "scan", quick: false → depth: "deep". depth wins when both are set.

Note

• Focused mode containment is prompt-driven, not CLI-enforced. Plan mode removes shell access but does not scope read_file / grep_search / list_directory to the changed files. Gemini could still read any non-gitignored file in the repo — the containment relies on the prompt instruction "Do NOT explore beyond the changed files" plus the reduced tool surface.

[0.3.0] - 2026-04-12

Changed

• Always-agentic query and structured tools: Both query and structured now run in agentic mode by default (--approval-mode plan). Gemini launches inside the working directory with read_file, grep, list_directory, and glob tools, exploring the repo for context instead of receiving pre-inlined file blobs. Text files are passed as @{path} hints, not inlined content. Image queries still use --yolo for native pixel access.
• Default timeout raised to 120s for both query and structured (was 60s for text queries). Plan mode boots the CLI tool system, which adds to the ~16s cold start.
• Tool descriptions updated: Both tools now explicitly describe themselves as agentic. The files parameter documentation clarifies that contents are NOT inlined.
• Footer label: Files included: renamed to Files hinted: in tool responses to reflect the new semantics (paths passed, Gemini may or may not have read them).

Removed

• File content inlining: readFiles() and assemblePrompt() removed from src/utils/files.ts. No text file content is pre-read or inlined into prompts.

Note

• Gitignored files are unreadable in text-query mode (plan mode restriction). Image queries (--yolo) can still read gitignored files. This is a CLI-level constraint with no bypass.
• Breaking for callers relying on guaranteed file reads: Gemini now decides which hinted files are relevant. If a file isn't pertinent to the query, Gemini may skip it. Callers who depended on "Gemini definitely saw the contents of file X" should verify via the response.

[0.2.8] - 2026-04-12

Fixed

• npm publish workflow: Run npm publish via npx --yes npm@latest instead of corepack. OIDC trusted publishing requires npm ≥ 11.5.1 but Node 22 ships with npm 10.9.7, and neither npm install -g npm@latest (v0.2.6, self-upgrade race breaks promise-retry) nor corepack prepare npm@latest --activate (v0.2.7, doesn't reroute npm without a packageManager field in package.json) actually got a modern npm onto PATH. npx downloads the package fresh into a temp dir and runs its bin directly, which sidesteps both problems.

Note

• v0.2.6 and v0.2.7 never reached the registry: both publish jobs aborted before npm publish completed. npm view gemini-mcp-bridge version still shows 0.2.5 immediately before this release.

[0.2.5] - 2026-04-08

Added

• MCP tool annotations: Tools declare readOnlyHint, destructiveHint, openWorldHint, and idempotentHint so MCP clients can make informed permission and caching decisions.
• Execution metadata: All tool results now include executionTime, timedOut, and resolvedModel fields alongside the response.
• Rich tool descriptions: Tool descriptions include parameter docs and usage examples, rendered inline for clients that display them.
• Progress heartbeats: Long-running operations emit MCP progress notifications so clients can show activity indicators instead of appearing stalled.
• MCP transport wiring tests: 7 new tests verifying server tool registration, stdio transport, and progress token propagation.
• CI smoke step: npm run smoke:ci runs a minimal MCP handshake in CI to catch wiring regressions.

[0.2.4] - 2026-04-05

Added

• Stream-JSON output format: Switch from --output-format json to --output-format stream-json (NDJSON) for progressive capture. Timeouts now return partial responses instead of generic error messages.
• Smoke test script: npm run smoke / scripts/smoke-test.mjs for testing tool functions directly without restarting the MCP client. Supports all four tools with configurable workingDirectory.
• Resolved working directory: All tool results now include resolvedCwd showing the actual directory used after git root resolution and path validation.
• Latency budget documentation: Document ~16s CLI cold start, per-layer timing breakdown, and implications for timeout configuration in CLAUDE.md and README.

Changed

• parseStreamJson() replaces parseGeminiOutput() as the primary parser, with automatic fallback to legacy JSON parsing for older CLI versions.
• tryParsePartial() extracts partial content from NDJSON on timeout, forwarding stderr for fallback parsing.
• Smoke test timeouts aligned with real CLI cold start times (60-120s).

[0.2.3] - 2026-03-30

Added

• Response length awareness: Optional maxResponseLength parameter (in words) on query, search, and review tools. Appends a soft length instruction to the prompt.
• Conciseness guidance in review and search prompt templates to reduce verbose output by default.
• buildLengthLimit() and appendLengthLimit() helpers in src/utils/prompts.ts.
• GEMINI_DEFAULT_MODEL env var support for default model selection.
• Auto-retry with fallback model on quota exhaustion (GEMINI_FALLBACK_MODEL env var).
• 10 new tests for response length controls.

Changed

• maxResponseLength zod schemas enforce .int().positive().

[0.2.2] - 2026-03-25

Added

• search tool: Google Search grounded queries. Spawns CLI in agentic mode with google_web_search, synthesizes answers with source URLs. Default 120s timeout.
• structured tool: JSON output conforming to a provided JSON Schema, with validation.
• Image support in query: Image files (png, jpg, jpeg, gif, webp, bmp) trigger agentic mode so the CLI reads them natively. Text files still inlined as before. Mixed text+image queries supported. 5MB size limit for images (vs 1MB for text).
• src/utils/errors.ts: Shared checkErrorPatterns() for consistent auth/rate-limit error handling across all tools.
• isImageFile() and IMAGE_EXTENSIONS helpers in src/utils/files.ts.
• 23 new tests (query tool: 11, search tool: 8, isImageFile: 4).

Fixed

• Review tool now checks for rate-limit/quota errors (previously only checked auth errors).

Changed

• File reads in readFiles() run in parallel via Promise.all instead of sequentially.
• Image path validation runs in parallel.

[0.2.1] - 2026-03-18

Changed

• Review prompts extracted from inline template literals to standalone markdown files in prompts/, loaded at runtime via loadPrompt().

Fixed

• Prompt placeholder replacement no longer corrupts diffs containing {{word}} patterns (Handlebars, Go templates, etc.).
• loadPrompt now uses basename() to prevent path traversal.

Added

• 9 tests for prompt template loading and placeholder substitution.

[0.2.0] - 2026-03-18

Added

• Agentic code review (default): Spawns Gemini CLI with --yolo inside the target repo. The CLI runs git diff itself, reads full files, follows imports, checks tests, and reads project instruction files (CLAUDE.md, GEMINI.md, AGENTS.md, etc.) for context-aware reviews.
• quick parameter on review tool: set true to skip repo exploration and get a fast diff-only review (previous behavior).
• focus parameter on review tool: direct attention to specific areas (e.g. "security", "performance", "error handling").
• Bundled policies/review.toml for future policy-based shell filtering (waiting on upstream CLI fix google-gemini/gemini-cli#20469).

Fixed

• JSON output parsing: Gemini CLI with --output-format json writes JSON to stderr in newer versions. Parser now checks both stdout and stderr.

[0.1.1] - 2026-03-17

Fixed

• ping auth detection: validate OAuth cred types instead of trusting shape
• Return "unknown" for malformed/partial OAuth creds (missing both refresh_token and expiry_date)
• Distinguish ENOENT (return "missing") from parse/permission errors (return "unknown") in catch block

[0.1.0] - 2026-03-16

Added

• query tool: one-shot Gemini queries with optional file context
• review tool: code review via native git-diff sent to Gemini
• ping tool: health check and CLI capability detection
• Hardened subprocess environment (minimal env allowlist)
• Path sandboxing (realpath validation, traversal prevention)
• Concurrency limiter (max 3 concurrent spawns, FIFO queue)
• Configurable timeouts with 600s hard cap
• JSON output parsing with ANSI-strip fallback