# Gemini CLI Schema

**Source**: [google-gemini/gemini-cli](https://github.com/google-gemini/gemini-cli)

**Schema Location**: `packages/core/src/services/chatRecordingService.ts`

**File Location**: `~/.gemini/tmp/{project_hash}/chats/session-{timestamp}-{id}.json`

**Format**: Single JSON file

## Session File Structure

```typescript
interface ConversationRecord {
  sessionId: string;
  projectHash: string;
  startTime: string;           // ISO timestamp
  lastUpdated: string;         // ISO timestamp
  messages: MessageRecord[];
  summary?: string;            // Session summary (optional)
  directories?: string[];      // Workspace dirs added via /dir add
}
```

## Message Types

### Base Message
```typescript
interface BaseMessageRecord {
  id: string;                  // UUID
  timestamp: string;           // ISO timestamp
  content: PartListUnion;      // Google GenAI content format
  displayContent?: PartListUnion;
}
```

### Message Type Variants

| Type | Description |
|------|-------------|
| `user` | User input message |
| `gemini` | Assistant response (with tool calls, thoughts, tokens) |
| `info` | Informational message |
| `error` | Error message |
| `warning` | Warning message |

### Gemini Message (Assistant)
```typescript
interface GeminiMessage extends BaseMessageRecord {
  type: 'gemini';
  toolCalls?: ToolCallRecord[];
  thoughts?: Array<ThoughtSummary & { timestamp: string }>;
  tokens?: TokensSummary | null;
  model?: string;              // e.g., "gemini-2.5-pro"
}
```

## Tool Call Structure

```typescript
interface ToolCallRecord {
  id: string;
  name: string;                // e.g., "write_file", "run_shell_command"
  args: Record<string, unknown>;
  result?: PartListUnion | null;
  status: Status;
  timestamp: string;

  // UI metadata
  displayName?: string;        // e.g., "WriteFile", "Shell"
  description?: string;
  resultDisplay?: ToolResultDisplay;
  renderOutputAsMarkdown?: boolean;
}
```

### Tool Status Values

| Status | Description |
|--------|-------------|
| `validating` | Validating tool call parameters |
| `scheduled` | Scheduled for execution |
| `executing` | Currently executing |
| `awaiting_approval` | Waiting for user confirmation |
| `success` | Completed successfully |
| `error` | Failed with error |
| `cancelled` | Cancelled by user |

## Token Usage

```typescript
interface TokensSummary {
  input: number;      // promptTokenCount
  output: number;     // candidatesTokenCount
  cached: number;     // cachedContentTokenCount
  thoughts?: number;  // thoughtsTokenCount
  tool?: number;      // toolUsePromptTokenCount
  total: number;      // totalTokenCount
}
```

## Thoughts (Reasoning)

```typescript
interface ThoughtSummary {
  subject: string;       // Bold header, e.g., "Planning Architecture"
  description: string;   // Detailed reasoning text
}

// In message, includes timestamp:
interface TimestampedThought extends ThoughtSummary {
  timestamp: string;     // ISO timestamp
}
```

## Tool Result Display

```typescript
type ToolResultDisplay = string | FileDiff | AnsiOutput | TodoList;

interface FileDiff {
  fileDiff: string;            // Unified diff format
  fileName: string;
  filePath: string;
  originalContent: string | null;
  newContent: string;
  diffStat?: DiffStat;
  isNewFile?: boolean;
}

interface DiffStat {
  model_added_lines: number;
  model_removed_lines: number;
  model_added_chars: number;
  model_removed_chars: number;
  user_added_lines: number;
  user_removed_lines: number;
  user_added_chars: number;
  user_removed_chars: number;
}

interface TodoList {
  todos: Todo[];
}

interface Todo {
  description: string;
  status: 'pending' | 'in_progress' | 'completed' | 'cancelled';
}
```

## Example Session

```json
{
  "sessionId": "3e72f9b9-e75e-4083-8d27-10f5a4498c7c",
  "projectHash": "1e01272821378e1687d1411198dfc72cf42d5b784d1f332393cc02a6e6df260f",
  "startTime": "2026-02-04T11:11:32.896Z",
  "lastUpdated": "2026-02-04T11:33:22.130Z",
  "messages": [
    {
      "id": "98c2f592-91f4-4ada-bbb4-47d17782573a",
      "timestamp": "2026-02-04T11:11:32.896Z",
      "type": "user",
      "content": "Build a blog app with Flask"
    },
    {
      "id": "96ae62b1-f39d-49fe-b8ed-901f7e4774e2",
      "timestamp": "2026-02-04T11:11:48.717Z",
      "type": "gemini",
      "content": "I'll create the project structure.",
      "model": "gemini-2.5-pro",
      "tokens": {
        "input": 6610,
        "output": 144,
        "cached": 0,
        "thoughts": 242,
        "total": 6996
      },
      "thoughts": [
        {
          "subject": "Planning the Build",
          "description": "Setting up Flask project structure with blueprints.",
          "timestamp": "2026-02-04T11:11:35.981Z"
        }
      ],
      "toolCalls": [
        {
          "id": "write_file-001",
          "name": "write_file",
          "displayName": "WriteFile",
          "args": {"file_path": "app.py", "content": "..."},
          "status": "success",
          "timestamp": "2026-02-04T11:11:48.716Z",
          "resultDisplay": {
            "fileName": "app.py",
            "filePath": "/project/app.py",
            "isNewFile": true,
            "newContent": "from flask import Flask..."
          }
        }
      ]
    }
  ]
}
```

## Schema Comparison: Official vs QC Trace Implementation

### Coverage Status: COMPREHENSIVE

Our v1.py schema (`qc_trace/schemas/gemini_cli/v1.py`) now includes **all types** from the official Gemini CLI schema:

#### Session Types (All Covered)
| Official Type | Our Implementation |
|---------------|-------------------|
| `ConversationRecord` | `GeminiConversationRecord` |
| `ResumedSessionData` | `GeminiResumedSessionData` |

#### Message Types (All Covered)
| Official Type | Our Implementation |
|---------------|-------------------|
| `MessageRecord` | `GeminiMessageRecord` |
| `user` | `GeminiUserMessageRecord`, `GeminiUserMessage` |
| `gemini` | `GeminiGeminiMessageRecord`, `GeminiAssistantMessage` |
| `info` | `GeminiInfoMessageRecord`, `GeminiInfoMessage` |
| `error` | `GeminiErrorMessageRecord`, `GeminiErrorMessage` |
| `warning` | `GeminiWarningMessageRecord`, `GeminiWarningMessage` |

#### Tool Types (All Covered)
| Official Type | Our Implementation |
|---------------|-------------------|
| `ToolCallRecord` | `GeminiToolCallRecord`, `GeminiToolCall` |
| `Status` | `GeminiToolStatus` |

#### ToolResultDisplay Variants (All Covered)
| Official Type | Our Implementation |
|---------------|-------------------|
| `string` | Part of `GeminiToolResultDisplay` union |
| `FileDiff` | `GeminiFileDiff` |
| `AnsiOutput` | `GeminiAnsiOutput` |
| `AnsiLine` | `GeminiAnsiLine` |
| `AnsiToken` | `GeminiAnsiToken` |
| `TodoList` | `GeminiTodoList` |
| `Todo` | `GeminiTodo` |
| `DiffStat` | `GeminiDiffStat` |

#### Token Types (All Covered)
| Official Type | Our Implementation |
|---------------|-------------------|
| `TokensSummary` | `GeminiTokensSummary`, `GeminiTokens` |
| All fields | `input`, `output`, `cached`, `thoughts`, `tool`, `total` |

#### Thought Types (All Covered)
| Official Type | Our Implementation |
|---------------|-------------------|
| `ThoughtSummary` | `GeminiThoughtSummary` |
| Timestamped | `GeminiTimestampedThought`, `GeminiThought` |

#### Tool Argument Types (All Covered)
| Tool | Our Implementation |
|------|-------------------|
| `write_file` | `GeminiWriteFileArgs` |
| `edit` | `GeminiEditArgs` |
| `run_shell_command` | `GeminiShellArgs` |
| `write_todos` | `GeminiWriteTodosArgs` |
| `glob` | `GeminiGlobArgs` |
| `grep` | `GeminiGrepArgs` |
| `read_file` | `GeminiReadFileArgs` |
| `list_dir` | `GeminiListDirArgs` |

## Schema Version

- **Version**: v1 (frozen 2026-02-04)
- **CLI Version**: Latest from github.com/google-gemini/gemini-cli
- **Official Source**: [`packages/core/src/services/chatRecordingService.ts`](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/services/chatRecordingService.ts)

## Notes

- Project hash is SHA-256 of the project root path
- Session files are stored per-project in `~/.gemini/tmp/{hash}/chats/`
- The `content` field uses Google's GenAI `PartListUnion` type which can contain text, function calls, or function responses
- Tool results can be string (simple) or structured objects (FileDiff, TodoList)
- Official schema is in TypeScript
