chronicle-remote-summarizer

What this skill does

# 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)**

```bash
# 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:

```bash
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):**
```bash
ssh <remote-host> "chronicle export-session <id>" | chronicle import-and-summarize --quiet 2>&1 | grep -A 999999 '^{$' | ssh <remote-host> "chronicle import-summary"
```

**Example:**
```bash
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
```bash
ssh <remote-host> "chronicle export-session <id>" > /tmp/session_<id>.json
```

**Example:**
```bash
ssh freebsd "chronicle export-session 7" > /tmp/session_7.json
```

### Step 2: Summarize locally (transient)
```bash
cat /tmp/session_<id>.json | chronicle import-and-summarize --quiet 2>/dev/null > /tmp/summary.json
```

**Example:**
```bash
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
```bash
cat /tmp/summary.json | ssh <remote-host> "chronicle import-summary"
```

**Example:**
```bash
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**:
   - Assigns negative ID (e.g., `-1`, `-2`, `-3`)
   - Stores transcript in `~/.ai-session/sessions/session_-3.cleaned`
   - Creates database entry with `is_session=True`
3. **Summarize**:
   - Runs `summarize_session_chunked()` with Gemini API
   - Processes large transcripts in chunks (10,000 lines per chunk)
   - Updates session with AI-generated summary
4. **Output JSON**:
   ```json
   {
     "version": "1.0",
     "original_id": 7,
     "summary": "AI-generated summary...",
     "summary_generated": true,
     "keywords": ["feature", "implementation", "testing"]
   }
   ```
5. **Auto-Cleanup**:
   - Deletes transcript file (`session_-3.cleaned`)
   - Deletes database entry (temporary session)
   - **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:
```bash
# 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:
```bash
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:
```bash
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
   ```

2. *