query
Ask Gemini to explore your codebase: it reads files, greps, and lists directories to answer prompts, analyze code, or return structured edits.
Instructions
Agentic query: Gemini runs inside your workingDirectory with read_file, grep, list_directory, and glob tools. Pass file paths as hints (not content) — Gemini reads them itself and can explore surrounding code for context.
Capabilities:
Code analysis with full repo exploration (Gemini follows imports, reads tests, checks related files)
Image understanding: screenshots, diagrams, architecture charts (png/jpg/gif/webp/bmp)
General knowledge questions and technical research
Text transformation, summarization, and generation
Change mode: structured edit blocks parsed into a machine-applicable
editsarray (see 'changeMode' below)
File handling: Pass file paths in the 'files' array as hints. Text files are referenced via @{path} — Gemini reads them with its own tools. Image files use --yolo mode for native pixel access. Gemini may also read files beyond the ones you hint at.
Note: Gitignored files cannot be read in text-query mode (plan mode restriction). Image queries (--yolo) can read gitignored files.
Change mode: set 'changeMode: true' to ask Gemini to emit structured **FILE: <path>:<start>-<end>** / ===OLD=== / ===NEW=== blocks instead of prose. The response text stays in response; parsed edits are returned on _meta.edits and never chunked. The tool runs in default agentic mode (NOT plan mode, which refuses to emit edit blocks) with a pre/post-spawn git snapshot that detects any file writes Gemini might attempt. If writes are detected the tool returns _meta.appliedWrites: true and omits edits for safety. Text-only (image files rejected). Requires a git working directory.
Model tips: Use gemini-2.5-flash for speed, gemini-2.5-pro for depth and complex reasoning. If omitted, the CLI auto-selects via its routing model.
Each invocation spawns a fresh CLI process (~15-20s startup overhead). Plan timeouts accordingly.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| files | No | File paths relative to workingDirectory, passed as hints. Gemini reads them with its own tools — contents are NOT inlined. Image files (png, jpg, jpeg, gif, webp, bmp) trigger --yolo mode. Max 20 files, 1MB per text file, 5MB per image. | |
| model | No | Gemini model override. Options: gemini-2.5-flash (fast), gemini-2.5-pro (deep). Omit to let CLI auto-route. | |
| prompt | Yes | The prompt to send to Gemini | |
| timeout | No | Timeout in milliseconds (default: 120000, max: 1800000). Minimum useful: ~20s due to CLI startup. | |
| changeMode | No | When true, Gemini emits structured **FILE: path:start-end** / ===OLD=== / ===NEW=== edit blocks. Legacy OLD:/NEW: markers are still parsed for back-compat. Parsed edits are returned on _meta.edits (never chunked). A pre/post-spawn git snapshot enforces that Gemini did not write any files; if writes are detected, _meta.appliedWrites is true and edits are omitted. Text-only, requires a git workingDirectory. | |
| workingDirectory | No | Working directory for file resolution and project context. The CLI reads GEMINI.md/AGENTS.md from here automatically. | |
| maxResponseLength | No | Soft limit on response length in words (e.g. 500). Reduces oversized responses from Gemini's large context window. |