The Stack Review

The Ultimate AI Stack: Making Claude Code Orchestrate Gemini CLI

TL;DR

Claude Code is an incredibly smart interactive assistant, but it has context limits. Gemini CLI has a massive context window but lacks Claude's nuance and instruction-following capabilities. This article details a hybrid strategy: configuring your CLAUDE.md file to teach Claude to treat Gemini CLI as a backend research tool. This allows you to perform deep, project-wide analysis from Claude’s interface without blowing your context budget.

AI-powered coding assistants have become indispensable, but developers are currently stuck choosing between two extremes. On one side, you have tools like Claude Code, which are highly intelligent, responsive, and great at following complex instructions, but suffer from a finite context window. On the other side, you have tools like Google’s Gemini CLI, which boasts a massive context window capable of ingesting entire repos, but can feel sluggish and "dumb" when trying to hold a conversation.

As a recent discussion in the developer community highlighted, the Gemini CLI is powerful, but it effectively needs to be "micro-managed" to be useful. It doesn't listen to instructions as well as Claude.

The solution isn't to switch back and forth. The solution is to make Claude use Gemini as its workhorse.

This guide details the strategy shared by developers to create an orchestrated system: using CLAUDE.md to force Claude to delegate large-scale data gathering to Gemini CLI.

The Two-Tool Dilemma

In this specific setup, we are looking at two distinct tools:

  1. The Brain (Claude Code): Your primary interface. It understands intent, plans refactors, and writes great code. However, it cannot hold a massive legacy codebase in its working memory.
  2. The Brawn (Gemini CLI): A command-line tool with a context window large enough to swallow thousands of files. It’s perfect for "read-only" analysis but terrible at the back-and-forth chat.

The goal is to stop using Gemini CLI interactively. Instead, we want to use it in non-interactive mode (-p) solely to fetch information and feed it back to Claude.

The Solution: The CLAUDE.md Configuration

The core principle is simple: we add a specific set of rules to the CLAUDE.md file (which configures Claude's behavior in your project). We tell Claude that whenever a request requires looking at the whole project, it must run a specific terminal command using Gemini.

This transforms Claude into an orchestrator. It recognizes a heavy task, constructs a gemini command, executes it, reads the output, and then explains it to you.

Implementing the Workflow

To enable this, add the following instructions to your CLAUDE.md file in the root of your project. This teaches Claude the specific syntax for Gemini's file inclusion (@) and non-interactive prompting.

# Using Gemini CLI for Large Codebase Analysis

When analyzing large codebases, multiple files, or entire directories that would exceed your context limit, you MUST use the Gemini CLI. Use `gemini -p` to leverage Google Gemini's large context capacity in non-interactive mode.

## File and Directory Inclusion Syntax

Use the `@` syntax to include files and directories in your Gemini prompts. The paths should be relative to WHERE you run the `gemini` command.

### Command Examples

**Single file analysis:**
`gemini -p "@src/main.py Explain this file's purpose and structure"`

**Multiple files:**
`gemini -p "@package.json @src/index.js Analyze the dependencies used in the code"`

**Entire directory:**
`gemini -p "@src/ Summarize the architecture of this codebase"`

**Multiple directories:**
`gemini -p "@src/ @tests/ Analyze test coverage for the source code"`

**Current directory (Full Project):**
`gemini -p "@./ Give me an overview of this entire project"`

**Using the All-Files Flag:**
`gemini --all_files -p "Analyze the project structure and dependencies"`

## Delegation Triggers: When to Use Gemini

You must delegate the task to `gemini -p` when:
- Analyzing entire codebases or large directories.
- Comparing or searching across several large files (totaling >100KB).
- Understanding project-wide patterns, architecture, or dependencies.
- Verifying the complete implementation of a feature (e.g., "Is dark mode fully implemented?").
- Auditing for security vulnerabilities across the codebase.
- The current context window is insufficient for the task.

Powerful Use Cases

With these instructions in CLAUDE.md, you don't need to manually type long commands. You can simply ask Claude natural questions, and it will run the Gemini CLI for you.

1. Architectural Understanding

Perfect for onboarding or understanding a legacy repo without reading every file manually.

  • You ask Claude: "Summarize the architecture of the src folder."
  • Claude executes: 
    gemini -p "@src/ Summarize the architecture of this codebase."

2. Feature Verification

You can ask Claude to verify if a feature touches all necessary parts of the stack (DB, API, Frontend).

  • You ask Claude: "Is dark mode fully implemented?"
  • Claude executes: 
    gemini -p "@src/ @lib/ Has dark mode been implemented in this codebase? Show me the relevant files and functions"

3. Security Auditing

Use Gemini's massive context to scan for vulnerabilities, while Claude interprets the results.

  • You ask Claude: "Check the API for SQL injection protections."
  • Claude executes: 
    gemini -p "@src/ @api/ Are SQL injection protections implemented? Show how user inputs are sanitized"

4. Implementation Checks

  • You ask Claude: "Is Redis caching set up correctly in the services layer?"
  • Claude executes: 
    gemini -p "@src/ @lib/ @services/ Is Redis caching implemented? List all cache-related functions and their usage"

Why This Works

  • No "YOLO" Mode Needed: Since we are using Gemini for analysis (read-only), we don't need to worry about it attempting to edit files. We are simply piping its output into Claude's context.
  • Best of Both Worlds: You get the superior reasoning and "personality" of Claude Code, backed by the infinite memory of Gemini.
  • Context Efficiency: Claude doesn't fill its memory with 50 source files; it only stores the summary and analysis provided by Gemini.

By treating Gemini CLI not as a separate assistant, but as a "plugin" or "sub-processor" for Claude Code, you create a development environment that is both incredibly smart and capable of handling massive scale.

Frequently Asked Questions (FAQ)

Why shouldn't I just use the Gemini CLI directly if it has a larger context window?

While Gemini CLI is excellent at ingesting massive amounts of code, it often lacks the conversational nuance and complex instruction-following capabilities of Claude Code. By using this hybrid workflow, you avoid the frustration of Gemini ignoring specific instructions. You get the best of both worlds: Gemini handles the heavy lifting of reading thousands of lines of code, while Claude acts as the intelligent "brain" to process that data and provide high-quality solutions.

Will using this setup allow Gemini to modify my code files?

No. The configuration provided uses Gemini's -p (prompt) flag, which runs the tool in a non-interactive, read-only mode. Gemini simply reads the files you target (using the @ syntax), generates a text response, and feeds it back into the chat. Claude remains the only tool with the authority to propose or apply actual changes to your codebase.

How does Claude know when to switch to using Gemini?

Claude doesn't know inherently; you have to teach it via the CLAUDE.md file. By adding the "Delegation Triggers" section to your project's configuration file, you explicitly define the criteria (such as analyzing entire directories or checking project-wide patterns) that require the larger context window. This instruction prompts Claude to stop trying to read everything itself and instead execute the gemini command to get the information it needs.