agent-biographer

name	agent-biographer
description	Shadow and version-control another agent's conversation. Use when asked to track an agent, create agent biography, shadow an agent, document agent work, or make agent output more accessible.

Agent Biographer

Purpose: Shadow another agent's conversation, version-control it over time, and make dense agent output accessible for humans.

---

Quick Start

# 1. Find agent's CWD from SID
find ~/.claude/projects -name "{sid}.jsonl"

# 2. Dump conversation (--sid alone is sufficient)
python ~/swe/telemetry_projects/agent_dump/launchers/dump_conversations.py \
  --sid {suffix}

# 3. Create archive and commit
mkdir -p ~/KnowledgeBase/agent-archives/{name}-{suffix}
# ... copy conversation.txt, create README, git init, commit

---

Step 1: Find Agent's CWD

Method: Find JSONL File

find ~/.claude/projects -name "{sid}.jsonl"

Output format: ~/.claude/projects/{encoded-cwd}/{sid}.jsonl

Decode the CWD:

• Replace leading - with /
• Replace all remaining - with /

Examples (for inference)

JSONL Path	Encoded CWD	Decoded CWD
~/.claude/projects/-Users-sotola-agent-home/abc123.jsonl	-Users-sotola-agent-home	/Users/sotola/agent-home
~/.claude/projects/-Users-sotola-swe-telemetry-projects/def456.jsonl	-Users-sotola-swe-telemetry-projects	/Users/sotola/swe/telemetry_projects

One-Liner

SID="f11289f0-b231-407d-b891-0fe64047ed5a"
dirname "$(find ~/.claude/projects -name "${SID}.jsonl" 2>/dev/null)" | \
  xargs basename | \
  sed 's/^-/\//' | \
  tr '-' '/'

If Method Fails

If the JSONL file doesn't exist (old session), infer from context or ask the user for the CWD.

---

Step 2: Dump Target Agent's Conversation

Get SID Suffix

The --sid flag uses SUFFIX (last 5 characters), NOT prefix!

Full SID	Suffix
f11289f0-b231-407d-b891-0fe64047ed5a	ed5a
019bfbb7-16c8-79e3-82e7-f6818860ca12	0ca12

Dump Command

# --sid alone is sufficient - no time constraints needed
python ~/swe/telemetry_projects/agent_dump/launchers/dump_conversations.py \
  --sid {suffix} \
  --data-dir /tmp/agent-{suffix}

Output: /tmp/agent-{suffix}/{agent-type}/{full-sid}-{pid}/conversation.txt

Find Active Session

If multiple sessions exist, check round count:

for dir in /tmp/agent-{suffix}/claude/*/; do
  rounds=$(head -5 "$dir/conversation.txt" | grep "Rounds:" | awk '{print $2}')
  echo "$dir: $rounds rounds"
done

Most rounds = most recent/active session.

---

Step 3: Create Archive

Directory Structure

~/KnowledgeBase/agent-archives/{descriptive-name}-{suffix}/
├── README.md           # Overview (you write this)
├── conversation.txt    # Source of truth (copy from dump)
├── *.md                # Any docs the agent generated (optional)
└── .git/               # Version control

Initialize Archive

# Create directory
mkdir -p ~/KnowledgeBase/agent-archives/{name}-{suffix}

# Copy conversation
cp /tmp/agent-{suffix}/{type}/{full-sid}-{pid}/conversation.txt \
  ~/KnowledgeBase/agent-archives/{name}-{suffix}/

# Copy any generated docs (if applicable)
cp ~/agent-home/ai/generated_doc/*.md \
  ~/KnowledgeBase/agent-archives/{name}-{suffix}/ 2>/dev/null

# Initialize git
cd ~/KnowledgeBase/agent-archives/{name}-{suffix}
git init
git add -A
git commit -m "Initial commit: {agent description}

Co-authored by [Claude: {your-agent-id}]"

README Template

# {Agent Name} - Agent Archive

**Agent ID:** `{full-sid}`
**Agent Type:** Claude/Codex
**Date:** {date}
**Rounds:** {count}

## Summary

{2-3 sentences about what the agent did}

## Key Accomplishments

1. {accomplishment 1}
2. {accomplishment 2}
...

## Resume Command

\`\`\`bash
cd {cwd} && cclaude --resume {sid}
\`\`\`

---

Step 4: The Update Loop (Version Control)

When the user says "update":

1. Fresh Dump

rm -rf /tmp/agent-{suffix}
python ~/swe/telemetry_projects/agent_dump/launchers/dump_conversations.py \
  --sid {suffix} --data-dir /tmp/agent-{suffix}

2. Copy and Diff

cp /tmp/agent-{suffix}/{type}/{full-sid}-{pid}/conversation.txt \
  ~/KnowledgeBase/agent-archives/{name}-{suffix}/

cd ~/KnowledgeBase/agent-archives/{name}-{suffix}
git diff conversation.txt

3. Analyze New Content

• DO NOT re-read the entire conversation
• DO read only the git diff output
• Look for new rounds, new tool calls, new accomplishments

4. Commit

git add conversation.txt
git commit -m "Round N: {summary of new content}

Co-authored by [Claude: {your-agent-id}]"

---

Step 5: Make Content Accessible

Your Job as Biographer

The target agent's output is often dense and terse - good for agents, bad for humans.

Your job:

1. Translate technical content into accessible explanations
2. Don't dumb down - maintain accuracy and depth
3. Occasionally fact-check - but don't overdo it
4. Explain the "how" - show tool call traces when interesting

Example: Tool Call Trace

When the agent does something interesting, show HOW:

## How the Agent Found the Information

### Phase 1: Search (Calls 1-5)
- Searched for "throughput" in docs → found references but no numbers
- Read SKILL.md → design description only

### Phase 2: Experiment (Calls 6-10)
- Built release binaries
- Created test data samples
- Ran actual benchmarks
- **Result:** 2.4M lines/sec

**Key insight:** Agent transitioned from researcher → experimenter

---

Step 6: Reasoning Content & Role-Based Judgment

Extracting Reasoning

Add --include-reasoning to include thinking/reasoning blocks:

python ~/swe/telemetry_projects/agent_dump/launchers/dump_conversations.py \
  --sid {suffix} \
  --include-reasoning \
  --data-dir /tmp/agent-{suffix}

Default behavior: Reasoning is excluded (it's exploratory, not final output).

Judging Reasoning: Role Matters

CRITICAL: Reasoning content is exploratory thought, not final judgment. How you judge it depends on the agent's Role.

Role Type	Overthinking Is...
Complex debugging / ecosystem cleanup	GOOD
Simple execution task	BAD

Example: Same Agent, Different Judgment

Agent: 50+ tool calls, 29 minutes of reasoning about Docker containers

If Role = "Debug and fix the agent-box Docker image":

EXCELLENT. Exhaustive exploration of edge cases (volume mounts, symlink detection, platform mismatches, port conflicts) led to correct fix on first try. For ecosystem debugging, you WANT the agent to think through every scenario.

If Role = "Run this Docker image for me":

MASSIVE FAILURE. User wanted docker run <image>. Agent spent 29 minutes overthinking irrelevant edge cases. Should have executed in 30 seconds.

Default Stance

No Role provided → Report reasoning content without judgment. Let the user decide if the depth was appropriate.

---

Workflow Summary

┌─────────────────────────────────────────────────────────────────┐
│                     INITIAL SETUP                                │
├─────────────────────────────────────────────────────────────────┤
│ 1. Get target SID from user (full SID or suffix)                 │
│ 2. Find CWD: find ~/.claude/projects -name "{sid}.jsonl"         │
│ 3. Extract suffix (last 5 chars of SID)                          │
│ 4. Dump: --sid {suffix} (add --include-reasoning if needed)      │
│ 5. Create archive, write README, git init, commit                │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                     UPDATE LOOP                                  │
├─────────────────────────────────────────────────────────────────┤
│ On "update":                                                     │
│ 1. Fresh dump (rm old, re-dump with --sid {suffix})              │
│ 2. Copy conversation.txt to archive                              │
│ 3. git diff conversation.txt (NOT full re-read)                  │
│ 4. Analyze new rounds, make accessible                           │
│ 5. Commit with summary                                           │
│ 6. Repeat                                                        │
└─────────────────────────────────────────────────────────────────┘

---

User Preferences (Learned)

Preference	Do This	Don't Do This
Check conversation first	Read conversation.txt diff	Check docs first
Don't re-read everything	Use git diff	Read from start on every update
Make accessible	Translate dense output	Dumb it down
Commit each update	git commit after every update	Batch commits
Show tool call traces	Explain HOW agent found info	Just show results
Do own research	Fact-check, add context	Blindly trust target agent

---

Common Mistakes to Avoid

1. Wrong --sid Format

# WRONG - prefix
--sid f11289f0

# CORRECT - suffix (last 5 chars)
--sid ed5a

2. Adding Unnecessary Time Constraints

# UNNECESSARY - time constraints add nothing when --sid is specified
--start-hour 720 --end-hour 0 --sid ed5a

# CORRECT - --sid alone is sufficient and fast
--sid ed5a

3. Re-reading Full Conversation on Update

# WRONG
cat conversation.txt  # Every time

# CORRECT
git diff conversation.txt  # Only changes

---

Archive Naming Convention

~/KnowledgeBase/agent-archives/{descriptive-name}-{suffix}/

Examples:

• rust-db-expert-0ca12/
• biography-skill-researcher-ac26/
• docker-ecosystem-deployer-d8b8/