chronicle-remote-summarizer

Chronicle Remote Summarizer

This skill automates the workflow for summarizing Chronicle sessions across different systems (e.g., FreeBSD dev machine → Mac with Gemini API).

Auto-Activation

This skill auto-activates! (Milestone #13)

Prompts like "summarize session on remote" or "import session from FreeBSD" automatically trigger this skill!

Trigger patterns: remote, freebsd, import session, summarize on remote

See: docs/HOOKS.md for full details

When to Use This Skill

Use this skill when:

• You have Chronicle sessions on a remote system without Gemini API configured
• You want to summarize those sessions on your local machine (which has Gemini API)
• You need to transfer the summary back to the original system
• You're working across multiple development environments (FreeBSD, Linux, macOS)

Common scenario: FreeBSD development server (no Gemini API) → macOS laptop (has Gemini API key)

How It Works

Chronicle provides import-and-summarize --quiet which:

1. Creates temporary session with negative ID (e.g., -3)
2. Generates AI summary using Gemini
3. Auto-cleanup: Deletes temporary session and files
4. Outputs clean JSON to stdout (no status messages with --quiet)

No pollution between systems - the remote session stays on the remote system, only the summary is transferred.

Recommended Workflow: One-Line Command

Prerequisites:

• SSH access from local machine to remote machine
• Chronicle installed on both systems
• Gemini API key configured on local machine (chronicle config ai.gemini_api_key YOUR_KEY)
• Optional: Remote system configured in Chronicle config (automates hostname/path)

Step 1: Configure Remote System (One-Time Setup)

# Configure FreeBSD remote system
chronicle config remote_systems.freebsd.hostname "chandlerhardy-dev.aws0.pla-net.cc"
chronicle config remote_systems.freebsd.chronicle_path "/home/chandlerhardy/.local/bin/chronicle"

# Verify configuration
chronicle config --list | grep freebsd

Step 2: Use the Skill

When Claude uses this skill and finds remote system configuration, it will automatically construct the command:

ssh chandlerhardy-dev.aws0.pla-net.cc "/home/chandlerhardy/.local/bin/chronicle export-session 7" | chronicle import-and-summarize --quiet 2>&1 | grep -A 999999 '^{$' | ssh chandlerhardy-dev.aws0.pla-net.cc "/home/chandlerhardy/.local/bin/chronicle import-summary"

If no config found, Claude will ask for the hostname and construct the command interactively:

Command (Manual):

ssh <remote-host> "chronicle export-session <id>" | chronicle import-and-summarize --quiet 2>&1 | grep -A 999999 '^{$' | ssh <remote-host> "chronicle import-summary"

Example:

ssh freebsd "chronicle export-session 7" | chronicle import-and-summarize --quiet 2>&1 | grep -A 999999 '^{$' | ssh freebsd "chronicle import-summary"

Note: The grep -A 999999 '^{$' filters out Google library warnings that can leak through even with --quiet and 2>/dev/null.

What this does:

1. Remote → Local: Export session 7 as JSON
2. Local: Import, summarize with Gemini, auto-cleanup temporary session
3. Local → Remote: Send summary JSON back
4. Remote: Update session 7 with the summary

Why --quiet works:

• Suppresses ALL status messages from summarizer
• Outputs ONLY clean JSON to stdout (essential for piping)
• No need to manually extract JSON from verbose output
• 2>/dev/null suppresses Google library warnings (harmless)

Time: Typically 30-60 seconds for large sessions (depends on transcript size)

Alternative: Manual 3-Step Workflow

If SSH pipes hang or you need to inspect intermediate files:

Step 1: Export session from remote

ssh <remote-host> "chronicle export-session <id>" > /tmp/session_<id>.json

Example:

ssh freebsd "chronicle export-session 7" > /tmp/session_7.json

Step 2: Summarize locally (transient)

cat /tmp/session_<id>.json | chronicle import-and-summarize --quiet 2>/dev/null > /tmp/summary.json

Example:

cat /tmp/session_7.json | chronicle import-and-summarize --quiet 2>/dev/null > /tmp/summary.json

What happens:

• Creates temporary session (negative ID like -3)
• Generates summary with Gemini
• Auto-cleanup: Deletes temporary session and transcript files
• Outputs summary JSON to /tmp/summary.json

Step 3: Send summary back to remote

cat /tmp/summary.json | ssh <remote-host> "chronicle import-summary"

Example:

cat /tmp/summary.json | ssh freebsd "chronicle import-summary"

Result:

• ✅ Summary stored in remote database linked to original session
• ✅ Local system stays clean (temporary session auto-deleted)
• ✅ No data pollution between systems

What Actually Happens (Under the Hood)

On import-and-summarize --quiet:

1. Import: Reads session JSON from stdin
2. Create Temporary Session:
3. Assigns negative ID (e.g., -1, -2, -3)
4. Stores transcript in ~/.ai-session/sessions/session_-3.cleaned
5. Creates database entry with is_session=True
6. Summarize:
7. Runs summarize_session_chunked() with Gemini API
8. Processes large transcripts in chunks (10,000 lines per chunk)
9. Updates session with AI-generated summary
10. Output JSON:

``json { "version": "1.0", "original_id": 7, "summary": "AI-generated summary...", "summary_generated": true, "keywords": ["feature", "implementation", "testing"] } ``

1. Auto-Cleanup:
2. Deletes transcript file (session_-3.cleaned)
3. Deletes database entry (temporary session)
4. Only the summary JSON remains (piped to stdout)

On import-summary (remote side):

1. Read JSON: Reads summary from stdin
2. Find Session: Looks up session by original_id (e.g., 7)
3. Update: Sets response_summary, summary_generated=True, keywords
4. Done: Session 7 now has the AI summary

Session Examples

Tested with:

• Session 1: 16.3 minutes, system test
• Session 2: 66.7 minutes, large session
• Session 4: 23KB JSON export

All sessions work perfectly with this workflow.

Troubleshooting

SSH Pipes Hang

Symptom: Command hangs indefinitely

Solution: Use manual 3-step workflow instead:

# Step 1: Export to file
ssh freebsd "chronicle export-session 7" > /tmp/session.json

# Step 2: Process locally
cat /tmp/session.json | chronicle import-and-summarize --quiet > /tmp/summary.json

# Step 3: Send back
cat /tmp/summary.json | ssh freebsd "chronicle import-summary"

Gemini API Not Configured

Symptom: ImportError: google-generativeai package not installed

Solution: Configure Gemini API key on local machine:

chronicle config ai.gemini_api_key YOUR_API_KEY_HERE

Get free API key: https://ai.google.dev/

Session Not Found

Symptom: Session 7 not found

Solution: Check session exists on remote:

ssh freebsd "chronicle sessions --limit 20"

Summary Already Exists

Behavior: import-and-summarize will overwrite existing summaries

Note: This is by design - you can re-summarize sessions if needed.

Tips

• Use --quiet flag: Essential for piping - suppresses status messages
• Suppress stderr: Add 2>/dev/null to hide Google library warnings
• Check SSH paths: Remote Chronicle might be in ~/.local/bin/chronicle
• Inspect files: Use 3-step workflow to save intermediate JSON for debugging
• Large sessions: 10K+ line transcripts are chunked automatically (no action needed)
• Network failures: Use 3-step workflow for unreliable connections
• Batch processing: You can script this to process multiple sessions

How Claude Should Use This Skill

When invoked, Claude should:

1. Check for remote system config:

``bash chronicle config --list | grep remote_systems ``

1. **