Subagent Transcript Indexing

Subagent Transcript Search Protocol (JSONL Log Indexing)

Overview

In multi-agent systems and hierarchical agent frameworks (Antigravity IDE, Claude Code, AutoGen), child subagents generate detailed step-by-step conversation trajectories stored on disk as JSON Lines (transcript.jsonl).

When a parent agent needs to check what a subagent did ("Did the research subagent find the API key?" or "What error did the test subagent encounter?"), naive orchestrators dump the entire 50-step transcript (10MB of JSON) into context, burning 80,000+ tokens.

The Subagent Transcript Search Protocol inspects on-disk JSONL log files using targeted local regex/ripgrep filters, extracting strictly the exact step, tool call, or error message in sub-millisecond local execution.

Full Transcript Replay vs. Targeted JSONL Indexing

┌─────────────────────────────────────────────────────────────┐
│                 Multi-Agent Memory Economics                │
│                                                             │
│  Full Transcript Ingestion (50 Steps / 78,000 Tokens):      │
│  • Reads all 50 step objects, system messages, DOM dumps    │
│  • 78,000 tokens billed ($0.234), slow 12s latency          │
│  • Overwhelms parent context with low-level child chatter   │
│                                                             │
│  Targeted JSONL Search (`rg "type":"USER_INPUT"` - 140 Toks):│
│  • Agent queries `<appDataDir>/brain/<id>/logs/transcript.jsonl`│
│  • Extracts step 14 `status:"ERROR"` directly via local CLI │
│  ↳ 140 clean tokens (99.8% Reduction!), 0.02s execution     │
└─────────────────────────────────────────────────────────────┘

The 2 Transcript File Archetypes

Every conversation trajectory produces two complementary JSONL files:

┌───────────────────────────────────────────────────────────────────────────┐
│ 1. `transcript.jsonl` (Compact / Token-Efficient - START HERE):           │
│    • Large tool outputs and reasoning blocks are safely truncated         │
│    • Lightweight for fast grep searching and trajectory mapping           │
│                                                                           │
│ 2. `transcript_full.jsonl` (Complete Untruncated Ground Truth):           │
│    • Preserves bit-for-bit complete outputs and full file payloads        │
│    • Read specific line numbers ONLY when `transcript.jsonl` is truncated │
└───────────────────────────────────────────────────────────────────────────┘

Master CLI Search Recipes for Subagent Transcripts

1. Find all Subagents Spawned in Conversation

rg '"tool_calls":.*"invoke_subagent"' <appDataDir>/brain/<id>/.system_generated/logs/transcript.jsonl

2. Find Exact Test / Tool Error Failures

rg '"status":"ERROR"' <appDataDir>/brain/<id>/.system_generated/logs/transcript.jsonl | jq '.content'

3. Extract All User Directives in Chronological Order

rg '"type":"USER_INPUT"' <appDataDir>/brain/<id>/.system_generated/logs/transcript.jsonl | jq '.content'

Production Python JSONL Transcript Extractor

import json
from pathlib import Path
from typing import List, Dict, Any, Optional

def search_transcript_step(
    transcript_path: Path,
    step_index: Optional[int] = None,
    error_only: bool = False
) -> List[Dict[str, Any]]:
    """Searches JSONL conversation transcript with zero context token waste."""
    results = []
    
    with transcript_path.open("r", encoding="utf-8") as f:
        for line in f:
            if not line.strip():
                continue
            entry = json.loads(line)
            
            # Filter by step index
            if step_index is not None and entry.get("step_index") == step_index:
                return [entry]
                
            # Filter by error status
            if error_only and entry.get("status") == "ERROR":
                results.append({
                    "step": entry.get("step_index"),
                    "source": entry.get("source"),
                    "content": entry.get("content")[:300]
                })
                
    return results

Benchmark Comparison

Investigating the cause of a child subagent failure across a 40-step session:

Agent Operational Directive

MANDATORY: Parent agents investigating child subagent history must NEVER ingest full transcript.jsonl files. Always run local ripgrep or python JSONL parsers to extract strictly the targeted step_index or error event.