gemini-cli-scanner

Discover patterns in your Gemini CLI and Claude Code environments. Extract tribal knowledge from how you actually use AI coding tools and surface it as reusable skills, agents, and best practices.

Quick Start

npx gemini-cli-scanner

No install required. Launches an interactive TUI with:

| Menu Item | What It Does | |:---|:---| | Quick Scan | Environment scan, optional repo discovery — no API key needed | | Full Scan | Everything + AI-powered skill suggestions from your conversation patterns | | View Report | Scrollable markdown report with t for TOC section-jump navigation | | Maturity Dashboard | Score breakdown (0–67), tier, advisory recommendations | | Auth Settings | Credential switching with export hints for session persistence |

Headless mode

npx gemini-cli-scanner --skip-suggestions
npx gemini-cli-scanner --repos ~/Code --chat-days 30

What This Does

1. Catalogs your MCP servers, skills, extensions, agents, policies, and context files
2. Analyzes conversation history — tools, models, topics, prompt patterns
3. Scores maturity (0–67) across 8 categories with actionable recommendations
4. Discovers ecosystems — Gemini CLI, Claude Code, Antigravity, Continue, Windsurf, JetBrains AI, OpenCode
5. Suggests skills using a two-stage AI pipeline grounded in your real usage data
6. Produces a shareable JSON manifest + markdown report (credentials auto-redacted)

Maturity Model

The advisory engine evaluates 8 categories and assigns a maturity tier:

| Tier | Score | What It Means | |:---|:---|:---| | 🌱 Getting Started | 0–33 | Basic install, minimal config | | 🔧 Intermediate | 34–46 | Active usage with some governance | | ⚡ Advanced | 47–60 | Strong policies, skills, MCP governance | | 🏆 Expert | 61–67 | Full-stack: hooks, extensions, context architecture |

📖 Full scoring breakdown and category details →

Install as Extension

For /scan commands inside Gemini CLI:

gemini extensions install https://github.com/pauldatta/gemini-cli-scanner

Partial Environments

The scanner works even when Gemini CLI is not installed. When ~/.gemini is missing:

• Gemini-specific sub-scans (settings, skills, conversations, memory) are skipped
• All other AI tool scans (Claude Code, Windsurf, Continue, JetBrains AI, OpenCode) run normally
• Repository-level scans (GEMINI.md, CLAUDE.md, local .gemini/ configs) proceed as usual
• The report includes a prominent installation banner and the ecosystem table marks Gemini CLI as "❌ Not installed"

This means your team can collect scan reports from everyone — including engineers who haven't adopted Gemini CLI yet — for a complete picture.

Configure (for AI skill suggestions)

# Option A: Vertex AI
export GOOGLE_CLOUD_PROJECT="your-project"

# Option B: API key
export GOOGLE_API_KEY="your-key"

Without these, the scanner runs fully — it just skips AI-powered skill suggestions.

📖 Skill suggestion pipeline details →

CLI Options

npx gemini-cli-scanner [OPTIONS]

--version, -v         Show version and exit
--gemini-dir PATH     Path to .gemini dir (default: ~/.gemini)
--home-dir PATH       Home directory for Claude scanning (default: ~)
--output-dir PATH     Output directory (default: ./scan-results)
--repos PATH [PATH..] Code repo paths or parent directories to scan
--repo-depth N        Max depth for recursive repo discovery (default: 3)
--chat-days N         Only include conversation data from the last N days
--skip-suggestions    Skip AI skill suggestion (no API key needed)
--json-only           Output JSON only, no markdown report
--include-prompts     Include raw prompts, topics, and project names in output manifest
--skip-update-check   Don't check GitHub for newer versions

Team Dashboard

Aggregate scan reports from your team into a single leadership dashboard:

# Auto-discovers reports in ./scan-results/, ./reports/, or current dir
npx gemini-cli-scanner dashboard

# Or point at a specific folder
npx gemini-cli-scanner dashboard --source ~/team-reports/

Opens a browser dashboard at http://localhost:3847 showing:

| Section | What It Shows | |:---|:---| | Overview Cards | Team coverage, average maturity score, top risk | | Maturity Distribution | Expert/Advanced/Intermediate/Getting Started breakdown | | CLI Detection | Which AI coding tools (Gemini CLI, Claude Code, Windsurf, etc.) are installed per engineer | | Toolkit Candidates | Skills and MCP servers shared across engineers — select and assemble into a toolkit spec | | Policy Compliance | YOLO gaps, missing deny rules, mode coverage | | Tool Chain Patterns | Behavioral sequences repeated across the team (automation candidates) | | Reporter Scorecards | Per-engineer score, trend arrows, expandable drill-down |

How It Works

1. Engineers run npx gemini-cli-scanner and save their gemini-env-manifest.json to a shared folder
2. Leader runs npx gemini-cli-scanner dashboard --source ./that-folder/
3. Dashboard reads all manifests, deduplicates, and builds a cumulative team-state.json
4. Click Sync to pick up new reports. Click Assemble to generate a toolkit spec from selected candidates

Options

npx gemini-cli-scanner dashboard [OPTIONS]

--source PATH    Folder containing manifest JSON files (auto-discovers if omitted)
--port PORT      Server port (default: 3847)

Output

After running, check scan-results/:

• gemini-env-manifest.json — Structured data for aggregation
• gemini-env-report.md — Human-readable report with scores, recommendations, and skills

Privacy & Redaction

Auto-redacted: API keys (AIza..., sk-...), OAuth tokens (ya29...), GitHub PATs (ghp_...), and any field named token, secret, password, or api_key.

Privacy by default (v3.5.6+): The output manifest (gemini-env-manifest.json) contains only aggregate statistics — counts, tool names, model usage, and chain fingerprints. Raw user prompts, thought topics, and project names are not written to disk. The AI skill pipeline uses full data in-memory. Use --include-prompts to include raw data for local analysis. The markdown report always retains full detail as a local-only artifact.

Not touched: Shell history, browser data, or files outside ~/.gemini/, ~/.claude/, and --repos paths.

Documentation

| Doc | Description | |:---|:---| | 📊 Advisory Engine | Scoring categories, maturity tiers, detailed point breakdowns | | 🔍 Scanning Reference | What gets scanned, recursive discovery, ecosystem detection | | 🤖 Skill Suggestions | Two-stage AI pipeline, quality standards, methodology | | 📖 Skill Identification | How patterns are extracted from conversation history | | 👥 For Teams | Cross-team aggregation, maturity benchmarking, enterprise patterns |

Developer Install

git clone https://github.com/pauldatta/gemini-cli-scanner.git
cd gemini-cli-scanner
make          # Interactive TUI
make test     # 258 tests across 12 test files

Contributing

Issues are automatically triaged by Gemini. Use the issue templates for bug reports and feature requests. Collaborators can re-triage by commenting /triage.

License

Apache 2.0