Gemini JSON Parsing

🚨 MANDATORY: Invoke gemini-cli-docs First

STOP - Before providing ANY response about Gemini JSON output:

•INVOKE gemini-cli-docs skill

•QUERY for the specific output format topic

•BASE all responses EXCLUSIVELY on official documentation loaded

Overview

Skill for parsing Gemini CLI's structured output formats. Essential for integration workflows where Claude needs to process Gemini's responses programmatically.

When to Use This Skill

Keywords: parse gemini output, json output, stream json, gemini stats, token usage, jq parsing, gemini response

Use this skill when:

•Extracting responses from Gemini JSON output
•Analyzing token usage and costs
•Parsing tool call statistics
•Handling errors from Gemini CLI
•Building automation pipelines

Output Formats

Standard JSON (`--output-format json`)

Single JSON object returned after completion:

json

{
  "response": "The main AI-generated content",
  "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,
      "totalDecisions": {
        "accept": 0,
        "reject": 0,
        "modify": 0,
        "auto_accept": 1
      },
      "byName": {
        "google_web_search": {
          "count": 1,
          "success": 1,
          "fail": 0,
          "durationMs": 1881
        }
      }
    },
    "files": {
      "totalLinesAdded": 0,
      "totalLinesRemoved": 0
    }
  },
  "error": {
    "type": "ApiError",
    "message": "Error description",
    "code": 500
  }
}

Stream JSON (`--output-format stream-json`)

Newline-delimited JSON (JSONL) with real-time events:

Event Type	Description	Fields
`init`	Session start	session_id, model, timestamp
`message`	User/assistant messages	role, content, timestamp
`tool_use`	Tool call requests	tool_name, tool_id, parameters
`tool_result`	Tool execution results	tool_id, status, output
`error`	Non-fatal errors	type, message
`result`	Final outcome	status, stats

Example stream:

jsonl

{"type":"init","timestamp":"2025-10-10T12:00:00.000Z","session_id":"abc123","model":"gemini-2.5-flash"}
{"type":"message","role":"user","content":"List files","timestamp":"2025-10-10T12:00:01.000Z"}
{"type":"tool_use","tool_name":"Bash","tool_id":"bash-123","parameters":{"command":"ls -la"}}
{"type":"tool_result","tool_id":"bash-123","status":"success","output":"file1.txt\nfile2.txt"}
{"type":"message","role":"assistant","content":"Here are the files...","delta":true}
{"type":"result","status":"success","stats":{"total_tokens":250}}

Common Extraction Patterns

Extract Response Text

bash

# Get main response
gemini "query" --output-format json | jq -r '.response'

# With error handling
result=$(gemini "query" --output-format json)
if echo "$result" | jq -e '.error' > /dev/null 2>&1; then
  echo "Error: $(echo "$result" | jq -r '.error.message')"
else
  echo "$result" | jq -r '.response'
fi

Token Statistics

bash

# Total tokens used
echo "$result" | jq '.stats.models | to_entries | map(.value.tokens.total) | add'

# Cached tokens (cost savings)
echo "$result" | jq '.stats.models | to_entries | map(.value.tokens.cached) | add'

# Billable tokens
total=$(echo "$result" | jq '.stats.models | to_entries | map(.value.tokens.total) | add')
cached=$(echo "$result" | jq '.stats.models | to_entries | map(.value.tokens.cached) | add')
echo "Billable: $((total - cached))"

# Tokens by model
echo "$result" | jq '.stats.models | to_entries[] | "\(.key): \(.value.tokens.total) tokens"'

Tool Call Analysis

bash

# Total tool calls
echo "$result" | jq '.stats.tools.totalCalls'

# List tools used
echo "$result" | jq -r '.stats.tools.byName | keys | join(", ")'

# Tool success rate
total=$(echo "$result" | jq '.stats.tools.totalCalls')
success=$(echo "$result" | jq '.stats.tools.totalSuccess')
echo "Success rate: $((success * 100 / total))%"

# Detailed tool stats
echo "$result" | jq '.stats.tools.byName | to_entries[] | "\(.key): \(.value.count) calls, \(.value.durationMs)ms"'

Model Usage

bash

# List models used
echo "$result" | jq -r '.stats.models | keys | join(", ")'

# Model latency
echo "$result" | jq '.stats.models | to_entries[] | "\(.key): \(.value.api.totalLatencyMs)ms"'

# Request counts
echo "$result" | jq '.stats.models | to_entries[] | "\(.key): \(.value.api.totalRequests) requests"'

Error Handling

bash

# Check for errors
if echo "$result" | jq -e '.error' > /dev/null 2>&1; then
  error_type=$(echo "$result" | jq -r '.error.type // "Unknown"')
  error_msg=$(echo "$result" | jq -r '.error.message // "No message"')
  error_code=$(echo "$result" | jq -r '.error.code // "N/A"')
  echo "Error [$error_type]: $error_msg (code: $error_code)"
  exit 1
fi

File Modifications

bash

# Lines changed
echo "$result" | jq '"Added: \(.stats.files.totalLinesAdded), Removed: \(.stats.files.totalLinesRemoved)"'

Stream Processing

Filter by Event Type

bash

# Get only tool results
gemini --output-format stream-json -p "query" | jq -r 'select(.type == "tool_result")'

# Get only errors
gemini --output-format stream-json -p "query" | jq -r 'select(.type == "error")'

# Get assistant messages
gemini --output-format stream-json -p "query" | jq -r 'select(.type == "message" and .role == "assistant") | .content'

Real-time Monitoring

bash

# Watch tool calls as they happen
gemini --output-format stream-json -p "analyze code" | while read line; do
  type=$(echo "$line" | jq -r '.type')
  case "$type" in
    tool_use)
      tool=$(echo "$line" | jq -r '.tool_name')
      echo "[TOOL] Calling: $tool"
      ;;
    tool_result)
      status=$(echo "$line" | jq -r '.status')
      echo "[RESULT] Status: $status"
      ;;
    error)
      msg=$(echo "$line" | jq -r '.message')
      echo "[ERROR] $msg"
      ;;
  esac
done

Quick Reference

What	jq Command
Response text	`.response`
Total tokens	`.stats.models \| to_entries \| map(.value.tokens.total) \| add`
Cached tokens	`.stats.models \| to_entries \| map(.value.tokens.cached) \| add`
Tool calls	`.stats.tools.totalCalls`
Tools used	`.stats.tools.byName \| keys \| join(", ")`
Models used	`.stats.models \| keys \| join(", ")`
Error message	`.error.message // "none"`
Error type	`.error.type // "none"`
Lines added	`.stats.files.totalLinesAdded`
Lines removed	`.stats.files.totalLinesRemoved`
Total latency	`.stats.models \| to_entries \| map(.value.api.totalLatencyMs) \| add`

Complete Example

bash

#!/bin/bash
# Analyze code and report stats

result=$(cat src/main.ts | gemini "Review this code for security issues" --output-format json)

# Check for errors
if echo "$result" | jq -e '.error' > /dev/null 2>&1; then
  echo "Error: $(echo "$result" | jq -r '.error.message')"
  exit 1
fi

# Extract response
echo "=== Security Review ==="
echo "$result" | jq -r '.response'

# Report stats
echo ""
echo "=== Stats ==="
total=$(echo "$result" | jq '.stats.models | to_entries | map(.value.tokens.total) | add // 0')
cached=$(echo "$result" | jq '.stats.models | to_entries | map(.value.tokens.cached) | add // 0')
models=$(echo "$result" | jq -r '.stats.models | keys | join(", ") | if . == "" then "none" else . end')
tools=$(echo "$result" | jq '.stats.tools.totalCalls // 0')

echo "Tokens: $total (cached: $cached)"
echo "Models: $models"
echo "Tool calls: $tools"

Test Scenarios

Scenario 1: Extract Response

Query: "How do I extract the response from Gemini JSON output?" Expected Behavior:

•Skill activates on "parse gemini output" or "json output"
•Provides jq extraction pattern Success Criteria: User receives .response extraction command

Scenario 2: Token Usage Analysis

Query: "How do I track token usage from Gemini CLI?" Expected Behavior:

•Skill activates on "token usage" or "gemini stats"
•Provides stats extraction patterns Success Criteria: User receives token calculation jq commands

Scenario 3: Stream Processing

Query: "How do I process Gemini CLI stream-json output?" Expected Behavior:

•Skill activates on "stream json"
•Provides JSONL processing patterns Success Criteria: User receives real-time stream processing example

References

Query gemini-cli-docs for official documentation on:

•"json output format"
•"stream-json output"
•"headless mode"

Version History

•v1.1.0 (2025-12-01): Added Test Scenarios section
•v1.0.0 (2025-11-25): Initial release

Gemini JSON Parsing

🚨 MANDATORY: Invoke gemini-cli-docs First

Overview

When to Use This Skill

Output Formats

Standard JSON (--output-format json)

Stream JSON (--output-format stream-json)

Common Extraction Patterns

Extract Response Text

Token Statistics

Tool Call Analysis

Model Usage

Error Handling

File Modifications

Stream Processing

Filter by Event Type

Real-time Monitoring

Quick Reference

Complete Example

Test Scenarios

Scenario 1: Extract Response

Scenario 2: Token Usage Analysis

Scenario 3: Stream Processing

References

Version History

Standard JSON (`--output-format json`)

Stream JSON (`--output-format stream-json`)