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:

{ "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:

{"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

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

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

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

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

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

Lines changed

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

Stream Processing

Filter by Event Type

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

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

#!/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