| name | collect-transcripts |
| description | Ingest raw session transcripts from coding-agent harnesses via vendor-specific adapters, normalize to a common event schema, triage for struggle signals, and write structured findings to episodic memory |
| category | Git Workflow |
| tags | ["transcripts","session-mining","capability-gaps","harness","multi-vendor"] |
| triggers | ["collect transcripts","mine transcripts","transcript mining","session transcripts"] |
Collect Transcripts
Ingest raw session transcripts from supported coding-agent harnesses via vendor-specific adapters, normalize them to a common event schema, triage for struggle signals, and run deep analysis on flagged sessions. Findings are written to episodic memory using the D4 tag schema with source:transcript-mined.
Arguments
$ARGUMENTS - Optional flags:
--adapter <name> (claude_code_cli, claude_code_web, codex_cli, codex_web, gemini_cli; default: all available)--threshold <float> (composite score threshold for deep analysis; default: 5.0)--dry-run (print planned operations without API calls; default in CI)--enable (opt-in to actually run LLM analysis; required to make API calls)
Adapters
| Adapter | Source | Schema Version |
|---|
claude_code_cli | ~/.claude/projects/<encoded-cwd>/<session-id>.jsonl | 1.0 |
claude_code_web | CLI bridge via claude --teleport <session-id> | 1.0 |
codex_cli | $CODEX_HOME/sessions/YYYY/MM/DD/rollout-*.jsonl | rollout-v1 |
codex_web | CLI bridge via codex cloud | rollout-v1 |
gemini_cli | ~/.gemini/tmp/<hash>/chats/session-*.json | chatRecordingService-v1 |
All adapters fail soft (log warning, skip) when their source is unavailable.
Pipeline
1. Discover sessions (per adapter)
2. Normalize to NormalizedEvent schema
3. Sanitize (secrets, entropy, paths) — BEFORE any LLM sees content
4. Triage (score for struggle signals: retries, errors, scope violations, corrections)
5. Deep analyze (flagged sessions only — heuristic or LLM)
6. Write findings to episodic memory (D4 tag schema, source:transcript-mined)
How It Works
- Discovery: Each adapter enumerates available sessions from its source
- Normalization: Raw vendor events -> NormalizedEvent (common schema in
references/event-schema.md)
- Sanitization: Reuses
session-log sanitizer extended for tool-call arguments and tool-result outputs
- Triage: Scores each session on retry_count, tool_error_count, scope_violation_count, user_correction_count
- Deep Analysis: Runs on flagged sessions (composite score >= threshold), extracts structured findings
- Memory: Findings written with D4 tags (
failure_type:*, capability_gap:*, etc.) + source:transcript-mined
Model Resolution
- Triage: archetype
analyst (standard tier), configurable via config.yaml: triage.archetype
- Deep analysis: archetype
reviewer (premium tier), configurable via config.yaml: deep_analysis.archetype
- Both resolve via
agents_config.resolve_model() from the coordinator
Prerequisites
- Python 3.11+
- At least one harness's sessions directory accessible on disk
- For web adapters: vendor CLI installed and authenticated
Steps
1. Discover and Normalize
python3 <agent-skills-dir>/collect-transcripts/scripts/adapters/claude_code_cli.py
2. Triage
python3 <agent-skills-dir>/collect-transcripts/scripts/triage.py \
--events-dir docs/transcripts/$(date +%Y-%m-%d)/ \
--threshold 5.0 \
--dry-run
3. Deep Analysis (flagged sessions only)
python3 <agent-skills-dir>/collect-transcripts/scripts/deep_analyze.py \
--events-file docs/transcripts/2026-06-01/session-abc.jsonl \
--dry-run
