@biggora/claude-plugins 1.0.0 → 1.1.0

package/src/skills/gemini-cli/references/headless-and-scripting.md

@@ -0,0 +1,181 @@
+# Headless Mode & Scripting Reference
+
+## How Headless Mode is Triggered
+
+- Passing a prompt via `-p` or `--prompt` flag
+- Running in a non-TTY environment (pipes, CI, cron)
+- Stdin piped input
+
+## Output Formats
+
+| Flag | Behavior |
+|---|---|
+| *(default)* | Raw text to stdout, ANSI codes stripped in non-TTY |
+| `--output-format json` | Single JSON object after all turns complete |
+| `--output-format stream-json` | Newline-delimited JSON (JSONL) events in real-time |
+
+## JSON Output Schema
+
+```json
+{
+  "response": "The final text response",
+  "stats": {
+    "models": {
+      "gemini-2.5-pro": {
+        "api": {
+          "totalRequests": 2,
+          "totalErrors": 0,
+          "totalLatencyMs": 5053
+        },
+        "tokens": {
+          "prompt": 24939,
+          "candidates": 20,
+          "total": 25113,
+          "cached": 21263,
+          "thoughts": 154,
+          "tool": 0
+        }
+      }
+    },
+    "tools": {
+      "totalCalls": 1,
+      "totalSuccess": 1,
+      "totalFail": 0,
+      "totalDurationMs": 1881,
+      "byName": {
+        "google_web_search": { "count": 1, "success": 1, "fail": 0 }
+      }
+    },
+    "files": {
+      "totalLinesAdded": 5,
+      "totalLinesRemoved": 2
+    }
+  }
+}
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | General error |
+| 2 | Authentication error |
+| 3 | Rate limit / quota exceeded |
+
+## Session Management in Headless Mode
+
+```bash
+# Sessions are auto-saved to ~/.gemini/sessions/<project_hash>/<session_id>.jsonl
+
+# Resume a previous session
+gemini -p "Continue from where we left off" --resume <session_id>
+```
+
+## Input Sources (merged in order)
+
+1. `--context-file` flag
+2. Stdin pipe
+3. `-p` prompt argument
+
+## Bash Scripting Patterns
+
+### Pattern 1: Simple text response
+```bash
+gemini -p "Summarize @./README.md" > summary.txt
+```
+
+### Pattern 2: JSON response with jq extraction
+```bash
+RESPONSE=$(gemini -p "Generate a changelog entry" --output-format json | jq -r '.response')
+echo "$RESPONSE" >> CHANGELOG.md
+```
+
+### Pattern 3: Conditional on token usage
+```bash
+RESULT=$(gemini -p "Review @./src/main.py" --output-format json)
+TOKENS=$(echo "$RESULT" | jq '.stats.models."gemini-2.5-pro".tokens.total')
+echo "Used $TOKENS tokens"
+echo "$RESULT" | jq -r '.response'
+```
+
+### Pattern 4: Pipe chain
+```bash
+git log --oneline -20 | gemini -p "Summarize the recent development activity"
+```
+
+### Pattern 5: Auto-accept all tool actions (YOLO)
+```bash
+# For CI pipelines where no human is present
+gemini -p "Fix lint errors in @./src/ and save changes" --yolo --output-format json
+```
+
+### Pattern 6: Batch processing multiple files
+```bash
+#!/bin/bash
+for py_file in $(find src -name "*.py"); do
+  echo "Processing: $py_file"
+  gemini -p "Add type hints to @$py_file and save" --yolo
+done
+```
+
+### Pattern 7: Structured data extraction
+```bash
+# Get structured JSON from model
+gemini --output-format json \
+  "Return a raw JSON object with keys 'version' and 'deps' from @package.json" \
+  | jq -r '.response' > data.json
+```
+
+### Pattern 8: Git commit automation
+```bash
+#!/bin/bash
+DIFF=$(git diff --cached)
+if [ -z "$DIFF" ]; then
+  echo "Nothing staged"
+  exit 1
+fi
+
+MSG=$(echo "$DIFF" | gemini -p "Write a concise conventional commit message (max 72 chars)" --output-format json | jq -r '.response')
+echo "Committing: $MSG"
+git commit -m "$MSG"
+```
+
+## PowerShell Patterns (Windows)
+
+```powershell
+# Batch process Python files to Markdown docs
+Get-ChildItem -Recurse -Filter "*.py" | ForEach-Object {
+  $newName = $_.FullName -replace '\.py$', '.md'
+  gemini "Generate Markdown documentation for @$($_.FullName). Print to stdout." | Out-File -FilePath $newName -Encoding utf8
+}
+
+# JSON response
+$output = gemini --output-format json "Return raw JSON with 'version' and 'deps' from @package.json" | ConvertFrom-Json
+$output.response > data.json
+```
+
+## GitHub Actions Integration
+
+```yaml
+- name: AI Code Review
+  env:
+    GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
+  run: |
+    REVIEW=$(git diff origin/main...HEAD | gemini -p "Review these changes for bugs and issues" --output-format json | jq -r '.response')
+    echo "$REVIEW" >> $GITHUB_STEP_SUMMARY
+```
+
+## Logging / Debugging
+
+```bash
+# Enable debug logging to file
+gemini -p "My prompt" --debug-log ./gemini-debug.jsonl
+```
+
+The log file captures all API interactions and tool executions as JSONL events.
+
+## Known Limitations
+
+- Custom slash commands (`.toml`) currently do NOT work in headless/non-interactive mode (open issue). Workaround: embed the full prompt text directly in your script.
+- Extensions also unavailable in headless mode currently.

package/src/skills/gemini-cli/references/mcp-and-extensions.md

@@ -0,0 +1,254 @@
+# MCP Servers & Extensions Reference
+
+## What is MCP?
+
+Model Context Protocol (MCP) is a standard that lets external servers expose tools and
+resources to Gemini CLI. MCP servers act as a bridge between Gemini and external systems
+(databases, APIs, custom scripts, cloud services).
+
+## MCP Server Configuration in settings.json
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_TOKEN": "$GITHUB_TOKEN"
+      }
+    },
+    "postgres": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-postgres"],
+      "env": {
+        "DATABASE_URL": "$DATABASE_URL"
+      }
+    },
+    "myPythonServer": {
+      "command": "python",
+      "args": ["-m", "my_mcp_server"],
+      "cwd": "./mcp_tools",
+      "env": {
+        "API_KEY": "$MY_API_KEY"
+      },
+      "timeout": 15000,
+      "trust": false,
+      "includeTools": ["safe_tool_1", "safe_tool_2"],
+      "excludeTools": ["dangerous_tool"]
+    }
+  }
+}
+```
+
+## MCP Server Config Fields
+
+| Field | Type | Description |
+|---|---|---|
+| `command` | string | Executable to run |
+| `args` | string[] | Arguments array |
+| `cwd` | string | Working directory |
+| `env` | object | Environment variables (use `"$VAR"` to reference env) |
+| `timeout` | number | Connection timeout in ms (default: 10000) |
+| `trust` | boolean | Skip all confirmation dialogs (use with caution) |
+| `includeTools` | string[] | Whitelist of tools to expose |
+| `excludeTools` | string[] | Blacklist of tools to hide |
+
+## Remote MCP Servers (SSE/HTTP)
+
+```json
+{
+  "mcpServers": {
+    "cloudflare": {
+      "url": "https://mcp.cloudflare.com/sse",
+      "transport": "sse"
+    }
+  }
+}
+```
+
+Supports OAuth 2.0 for authenticated remote servers.
+
+## CLI Commands for MCP Management
+
+```bash
+# Add a server
+gemini mcp add github --command "npx -y @modelcontextprotocol/server-github"
+
+# List configured servers
+gemini mcp list
+
+# Remove a server
+gemini mcp remove github
+```
+
+**In interactive session:**
+```
+/mcp list           # list all servers and status
+/mcp status         # detailed connection info
+/mcp enable github  # enable a disabled server
+/mcp disable github # disable without removing
+```
+
+## Using MCP Tools in Prompts
+
+```
+> @github List my open pull requests
+> @github Create an issue titled "Bug: login fails"
+> @slack Send summary of today's commits to #dev
+> @database Find users who haven't logged in for 30 days
+```
+
+## MCP Prompts as Slash Commands
+
+MCP servers can expose predefined prompts, which become slash commands:
+
+```
+/poem-writer --title="Gemini CLI" --mood="reverent"
+/pr-review --repo="my-project" --pr-number=42
+```
+
+Positional args also work:
+```
+/mycommand arg1 arg2
+```
+
+## Security Notes
+
+- Never hardcode API keys in settings.json — use `"KEY": "$ENV_VAR"` pattern
+- The CLI redacts sensitive env vars (`*TOKEN*`, `*SECRET*`, `*KEY*`, etc.) from MCP processes unless explicitly listed in `env`
+- `"trust": true` disables all confirmation dialogs — only use for servers you completely control
+- MCP servers run with your user account permissions
+
+---
+
+## Extensions
+
+Extensions bundle together MCP servers, context files, and custom commands into a reusable unit.
+
+### Install from Git URL
+```bash
+gemini extension install https://github.com/GoogleCloudPlatform/cloud-run-mcp
+```
+
+### Browse the gallery
+https://geminicli.com/extensions/
+
+### Popular extensions
+- **Cloud Run** (Google) — deploy to Cloud Run
+- **GitHub** — manage issues, PRs, repositories
+- **Redis** — query Redis instances
+- **DynaTrace** — observability integration
+
+### Extension Structure
+
+```
+my-extension/
+├── gemini-extension.json    # required manifest
+├── GEMINI.md                # optional context instructions
+└── commands/
+    └── deploy.toml          # optional custom commands
+```
+
+### gemini-extension.json Manifest
+
+```json
+{
+  "name": "my-extension",
+  "version": "1.0.0",
+  "description": "My custom extension",
+  "mcpServers": {
+    "my-server": {
+      "command": "node",
+      "args": ["./server.js"]
+    }
+  },
+  "contextFileName": "GEMINI.md",
+  "excludeTools": ["run_shell_command"]
+}
+```
+
+### Extension Locations
+
+- `~/.gemini/extensions/<n>/` — user-scoped (all projects)
+- `<project>/.gemini/extensions/<n>/` — project-scoped
+
+### Managing Extensions
+
+```
+/extension list          # list installed extensions
+/extension enable <n>    # enable extension
+/extension disable <n>   # disable extension
+```
+
+---
+
+## Custom Slash Commands (.toml) — Full Reference
+
+### File Locations
+
+```
+~/.gemini/commands/plan.toml              → /plan         (global)
+<project>/.gemini/commands/review.toml   → /review       (project)
+<project>/.gemini/commands/git/commit.toml → /git:commit  (namespaced)
+```
+
+### .toml Schema
+
+```toml
+# Required
+prompt = "Your prompt text here"
+
+# Optional
+description = "What this command does"
+
+# Arguments placeholder
+# Use {{args}} to insert all user-provided arguments
+prompt = "Review this code: {{args}}"
+
+# Shell command execution (backtick-style)
+prompt = "Review staged changes:\n!{git diff --cached}"
+
+# Combined example
+description = "Commit with AI message"
+prompt = """
+Write a conventional commit message for these changes:
+!{git diff --cached}
+
+Format: <type>(<scope>): <description>
+Types: feat, fix, docs, style, refactor, test, chore
+"""
+```
+
+### Usage examples
+
+```
+/plan                    # Run /plan command
+/review src/auth.py      # {{args}} = "src/auth.py"
+/git:commit              # Namespaced command
+```
+
+### Invoking with args
+```
+/review --file="src/auth.py" --focus="security"
+/review src/auth.py      # positional
+```
+
+## Multi-Modal Tool Responses
+
+MCP tools can return mixed content (text + images):
+
+```json
+{
+  "content": [
+    { "type": "text", "text": "Here is the chart:" },
+    { "type": "image", "data": "BASE64_DATA", "mimeType": "image/png" },
+    { "type": "text", "text": "Analysis complete." }
+  ]
+}
+```
+
+Gemini CLI will:
+1. Combine all text blocks into a single response part
+2. Pass image data as inline content to the model
+3. Show a user-friendly summary in the terminal