Gemini CLI Integration

Gemini CLI is Google's open-source AI terminal assistant that brings the power of Gemini directly into your command line. Plexus can monitor your Gemini CLI sessions, tracking AI interactions, tool usage, and costs across all your projects.

What is Gemini CLI?

Gemini CLI is an open-source AI agent that runs in your terminal, powered by Google's Gemini 2.5 Pro model. Key features include:

• 1M Token Context Window - Process large codebases and documentation in a single session
• Built-in Tools - Google Search grounding, file operations, shell commands, and web fetching
• MCP Support - Model Context Protocol integration for custom tools and data sources
• GEMINI.md Files - Project-specific instructions that tailor AI behavior
• Hooks System - Lifecycle event hooks for customizing agent behavior
• Free Tier - 60 requests per minute and 1,000 requests per day at no cost

Gemini CLI is fully open-source under the Apache 2.0 license.

How Plexus Integrates with Gemini CLI

Plexus monitors Gemini CLI through its native hooks system, capturing AI interactions in real-time:

┌─────────────────────────────────────────────────┐
│               Terminal Session                   │
│                                                 │
│  ┌──────────────────────────────────────────┐  │
│  │            Gemini CLI Agent              │  │
│  │                                          │  │
│  │  ┌────────────┐  ┌────────────────────┐  │  │
│  │  │   Model    │  │   Built-in Tools   │  │  │
│  │  │  Request   │  │  (Shell, Files,    │  │  │
│  │  │            │  │   Search, etc.)    │  │  │
│  │  └─────┬──────┘  └────────┬───────────┘  │  │
│  │        │                  │              │  │
│  │        └────────┬─────────┘              │  │
│  │                 ▼                        │  │
│  │  ┌──────────────────────────────────┐   │  │
│  │  │      Gemini CLI Hooks Layer      │   │  │
│  │  │   (BeforeTool, AfterTool, etc.)  │   │  │
│  │  └──────────────────────────────────┘   │  │
│  └──────────────────┼───────────────────────┘  │
│                     │                           │
└─────────────────────┼───────────────────────────┘
                      ▼
              ┌───────────────┐
              │    Plexus     │
              │   Dashboard   │
              └───────────────┘

Monitored Events

Installing Gemini CLI

Prerequisites

• Node.js 20 or later - Required to run Gemini CLI
• Plexus - Already installed on your system

Installation via npm

npm install -g @google/gemini-cli

Installation via Other Package Managers

Using pnpm:

pnpm add -g @google/gemini-cli

Using yarn:

yarn global add @google/gemini-cli

Using Homebrew (macOS):

brew install gemini-cli

Verify Installation

gemini --version

Authentication Setup

After installation, run gemini in your terminal to start the setup wizard:

Option 1: Login with Google (Recommended)

1. Run gemini in your terminal
2. Select Login with Google when prompted
3. A browser window opens for Google authentication
4. Complete the login process
5. Return to your terminal - you're ready to go

This method provides free access with:

• 60 requests per minute
• 1,000 requests per day
• Access to Gemini 2.5 Pro

Option 2: API Key Authentication

For higher limits or enterprise use, authenticate with an API key:

1. Visit Google AI Studio
2. Create or select an API key
3. Set the environment variable:

export GEMINI_API_KEY="your-api-key-here"

Add to your shell profile (~/.zshrc, ~/.bashrc, etc.) for persistence:

echo 'export GEMINI_API_KEY="your-api-key-here"' >> ~/.zshrc
source ~/.zshrc

Option 3: Vertex AI (Enterprise)

For Google Cloud users with Vertex AI access:

export GOOGLE_API_KEY="your-api-key"
export GOOGLE_GENAI_USE_VERTEXAI=true
export GOOGLE_CLOUD_PROJECT="your-project-id"

Setting Up the Plexus Integration

Automatic Setup

When you first launch Plexus with Gemini CLI installed, the integration is configured automatically:

1. Launch Plexus from your Applications folder
2. Plexus detects Gemini CLI and installs the necessary hooks
3. Open a terminal and run gemini - sessions will appear in Plexus

Manual Setup

If automatic setup doesn't work, configure the integration manually:

1. Open Plexus and go to Settings > Agents
2. Find Gemini CLI in the list and click Configure
3. Follow the on-screen instructions to install hooks

Verifying the Integration

To verify Plexus is connected to Gemini CLI:

1. Open a terminal and run gemini
2. Send a test message like "Hello, what can you do?"
3. Check the Plexus dashboard - a new Gemini session should appear

Gemini CLI Configuration Files

Gemini CLI uses several configuration files that Plexus respects and monitors:

Configuration Locations

Settings Structure

The settings.json file uses a structured format:

{
  "theme": "dark",
  "model": {
    "default": "gemini-2.5-pro"
  },
  "tools": {
    "enabled": ["run_shell_command", "read_file", "write_file"]
  },
  "hooks": {
    "BeforeTool": [],
    "AfterTool": []
  }
}

GEMINI.md Context Files

GEMINI.md files provide instructions that customize AI behavior for your projects:

# Project Guidelines

This is a TypeScript project using React and Next.js.

## Coding Standards
- Use functional components with hooks
- Prefer TypeScript strict mode
- Follow the existing code style

## File Structure
- Components in `src/components/`
- Pages in `app/`
- Utilities in `src/lib/`

Generate a starter GEMINI.md file:

gemini /init

Hooks Configuration for Plexus

Plexus uses Gemini CLI's hooks system to monitor sessions. The hooks are configured in ~/.gemini/settings.json:

Plexus Hook Configuration

{
  "hooks": {
    "SessionStart": [
      {
        "name": "plexus-session-start",
        "type": "command",
        "command": "~/.plexus/hooks/gemini/session-start.sh",
        "timeout": 5000
      }
    ],
    "BeforeTool": [
      {
        "name": "plexus-before-tool",
        "type": "command",
        "command": "~/.plexus/hooks/gemini/before-tool.sh",
        "timeout": 5000
      }
    ],
    "AfterTool": [
      {
        "name": "plexus-after-tool",
        "type": "command",
        "command": "~/.plexus/hooks/gemini/after-tool.sh",
        "timeout": 5000
      }
    ],
    "SessionEnd": [
      {
        "name": "plexus-session-end",
        "type": "command",
        "command": "~/.plexus/hooks/gemini/session-end.sh",
        "timeout": 5000
      }
    ]
  }
}

Note: Plexus automatically manages these hooks. You don't need to configure them manually unless troubleshooting.

Monitoring AI Features

Session Tracking

Plexus monitors all Gemini CLI sessions including:

• Session start and end times
• Active project/directory
• Total requests and token usage
• Cost estimation

Tool Usage

When Gemini CLI uses built-in tools, Plexus tracks:

Context Window Usage

Plexus monitors your context window utilization:

• Input tokens per request
• Output tokens generated
• Total context size
• Remaining capacity in 1M token window

Cost Tracking

Plexus tracks API costs for Gemini CLI sessions:

Free Tier Limits

API Key Pricing (Pay-as-you-go)

Note: Pricing may vary. Check Google AI pricing for current rates.

Viewing Cost Breakdown

1. Click on a Gemini session in the dashboard
2. Select the Costs tab
3. View token usage and estimated costs

MCP Server Integration

Gemini CLI supports MCP (Model Context Protocol) servers for extended functionality. Plexus monitors these connections.

MCP Configuration

Configure MCP servers in ~/.gemini/settings.json:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]
    }
  }
}

What Plexus Monitors

• Active MCP server connections
• Tool calls made through MCP
• Data retrieved from external sources
• Connection status and errors

Troubleshooting

Gemini CLI Sessions Not Appearing

If Gemini CLI sessions don't appear in Plexus:

1. Verify Plexus is running - Check your system tray/menu bar
2. Check Gemini CLI installation - Run gemini --version
3. Restart Gemini CLI - Exit and run gemini again
4. Reinstall hooks - Go to Plexus Settings > Agents > Gemini CLI > Reinstall

Hook Installation Failed

If Plexus can't install hooks:

1. Check that ~/.gemini/ directory exists:

   ls -la ~/.gemini/

2. Verify settings.json is writable:

   touch ~/.gemini/settings.json

3. Manually verify hooks in settings:

   cat ~/.gemini/settings.json | grep -A 10 "hooks"

Authentication Issues

If Gemini CLI won't authenticate:

1. Clear cached credentials:

   rm -rf ~/.gemini/credentials
   gemini

2. Try API key authentication:

   export GEMINI_API_KEY="your-key"
   gemini

3. Check network access to Google services

High Token Usage

If you're hitting rate limits:

1. Use /compact command to compress conversation history
2. Start new sessions for unrelated tasks
3. Use specific file references instead of reading entire directories
4. Consider upgrading to API key authentication for higher limits

Tool Execution Errors

If tools fail to execute:

1. Check sandbox mode isn't blocking operations
2. Verify file permissions for read/write operations
3. Ensure shell commands have proper PATH access
4. Check Gemini CLI logs for detailed errors

MCP Servers Not Connecting

If MCP servers aren't working:

1. Verify MCP server packages are installed
2. Check environment variables are set correctly
3. Test MCP server independently:

   npx -y @modelcontextprotocol/server-github

4. Review Gemini CLI output for connection errors

Best Practices

Optimize Your Workflow

1. Use GEMINI.md files - Provide project context to reduce repeated explanations
2. Leverage the 1M context - Reference large files directly instead of summarizing
3. Use specific prompts - Clear instructions reduce back-and-forth

Manage Token Usage

1. Use /compact regularly in long sessions
2. Start fresh sessions for new tasks
3. Reference specific files with @filename syntax
4. Monitor usage in Plexus dashboard

Security Considerations

1. Review shell commands before execution
2. Use sandbox mode for untrusted operations
3. Be cautious with API keys in environment variables
4. Monitor MCP server access through Plexus

CLI Commands Reference

Common Gemini CLI commands:

Next Steps

• Learn about Webhook Notifications for team alerts
• Explore Configuration Options for advanced settings
• Check Keyboard Shortcuts for faster navigation