Session Log Manager
Monitor, archive, rotate, and diagnose AI agent session logs across all stores. Deterministic shell scripts for health/archive/rotate; Python for forensics. Operates on system-wide session stores but archives per-repo.
Quick Start
# Health check — scan all stores, report per-repo sizes, flag hotspots
bash .agents/skills/session-log-manager/scripts/session-health-check.sh
# Archive — copy & compress sessions for this repo
bash .agents/skills/session-log-manager/scripts/session-archive.sh --repo build-meta-analysis
# Rotate — compress sessions older than 7 days in the archive
bash .agents/skills/session-log-manager/scripts/session-rotate.sh
# Forensics — crash/stall RCA from session ID
python3 .agents/skills/session-log-manager/scripts/session-forensics.py <session-id-or-path>
# Image strip — remove embedded image byte-dicts, archive originals
python3 .agents/skills/session-log-manager/scripts/session-image-strip.py --dry-run --all
python3 .agents/skills/session-log-manager/scripts/session-image-strip.py --all
Or use Makefile targets:
make session-health
make session-archive REPO=build-meta-analysis
make session-rotate
What This Skill Manages
System Stores (Source of Truth — never modified)
| Store |
Location (macOS) |
Format |
| Copilot CLI |
~/.copilot/session-state/<uuid>/events.jsonl |
JSONL (event stream) |
| VS Code Insiders |
~/Library/Application Support/Code - Insiders/User/workspaceStorage/<hash>/chatSessions/*.jsonl |
JSONL (chat log) |
| VS Code Stable |
~/Library/Application Support/Code/User/workspaceStorage/<hash>/chatSessions/*.jsonl |
JSONL (chat log) |
Archive (Repo-Local — managed by this skill)
| Location |
Contents |
runs/sessions/<repo>/ |
Compressed .jsonl.gz files, deduplicated by session UUID |
Scripts
session-health-check.sh — P0: Monitor
Scans all 3 session stores. Reports per-repo sizes. Flags hotspots.
bash .agents/skills/session-log-manager/scripts/session-health-check.sh
Output: Markdown report with:
- Summary table (files, size, oversized count per store)
- Copilot CLI per-repo breakdown (from
workspace.yaml)
- VS Code per-workspace breakdown (from
workspace.json)
- Health warnings (workspace >500 MB, session >10 MB, total >5 GB)
Thresholds:
- Workspace: >500 MB = WARNING
- Individual session: >10 MB = WARNING
- Total: >5 GB = CRITICAL
session-archive.sh — P0: Archive
Archives sessions for a specific repo with gzip compression and UUID-based deduplication.
bash .agents/skills/session-log-manager/scripts/session-archive.sh --repo <name> [--output-dir <path>] [--dry-run]
Behavior:
- Scans CLI sessions via
workspace.yaml → git_root match
- Scans VS Code sessions via
workspace.json → folder URI match
- Compresses each session to
.jsonl.gz (4-5x compression)
- Names:
{cli|vscode}_{uuid}.jsonl.gz
- Deduplicates: running twice produces 0 new copies
session-rotate.sh — P0: Rotate
Compresses uncompressed sessions older than N days in the archive. Never touches system stores.
bash .agents/skills/session-log-manager/scripts/session-rotate.sh [--archive-dir <path>] [--days 7] [--dry-run]
Retention policy:
- 0-7 days: Raw
.jsonl (active, live access)
- 7+ days: Compressed
.jsonl.gz (searchable via zgrep)
- Never delete: Session logs are primary behavioral evidence
session-forensics.py — P1: Diagnose
Crash/stall RCA from a session ID or file path.
python3 .agents/skills/session-log-manager/scripts/session-forensics.py <session-id-or-path>
Detects:
- Context growth curve (per-line byte sizes with ASCII chart)
- Oversized attachments (images serialized as JSON dicts — L81)
- Error and Canceled events (context budget exhaustion)
- Tool call distribution
- Crash risk level (LOW / MEDIUM / HIGH / CRITICAL)
Finds sessions by:
- Direct file path
- UUID → searches CLI, VS Code Insiders, VS Code Stable stores
session-image-strip.py — P0: Strip Images
Strips embedded image byte-dicts from VS Code session files. Images pasted into Copilot Chat
are serialized as {"0": 137, "1": 80, ...} — one JSON key per byte, ~2.5× inflate. This causes
V8 heap exhaustion and renderer crashes (L81, microsoft/vscode#295334).
python3 .agents/skills/session-log-manager/scripts/session-image-strip.py --dry-run --all
python3 .agents/skills/session-log-manager/scripts/session-image-strip.py --all
python3 .agents/skills/session-log-manager/scripts/session-image-strip.py --workspace ea03ad
Behavior:
- Scans all JSONL session files for byte-dict patterns (PNG=137, JPEG=255, GIF=71)
- Archives each original to
~/.session-archive/images/<wsid>/ (gzipped)
- Replaces byte-dicts with
[IMAGE_STRIPPED: N bytes, stripped TIMESTAMP]
- Preserves all conversation text, image metadata (name, path, kind)
--dry-run shows what would be cleaned without modifying files
Tiers
| Tier |
Capabilities |
Target Repos |
| Good |
health check, archive (compressed), rotate |
Any repo (T7, T9, T10, T11) |
| Better |
Good + parse_session + search_sessions (from session-log-analysis skill) |
Repos with analysis needs |
| Best |
Better + forensics, monitoring, pre-commit guards |
T1, B5a |
References
- Session Stores — Where logs live (macOS, Linux paths)
- Size Budgets — Thresholds, growth rates, compression ratios
- Session Archive 2026-02-14 — Emergency cleanup: 604 files, 2.3 GB freed, restore instructions
Examples
- Health Check Output — Sample report
- Forensics Report — Sample crash RCA
Related Skills
| Skill |
Relationship |
session-log-analysis |
Analysis (parse + search). Complementary — manager handles storage, analysis handles insights. |
Done When
session-health-check.sh runs without error on macOS, reports per-repo sizessession-archive.sh archives sessions for a named repo with compression and dedupsession-rotate.sh compresses sessions older than thresholdsession-forensics.py produces crash RCA with context growth, attachment detection, error events- All scripts exit 0 on healthy systems
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
1---2name: session-log-manager3description: Manages AI agent session logs across Copilot CLI and VS Code stores. Health checks, per-repo archival with compression, age-based rotation, and crash forensics. Use when you need to monitor session storage growth, archive sessions per-repo, compress old sessions, investigate crashes/stalls, or detect oversized sessions. Keywords: session log, archive, rotate, compress, health check, forensics, crash RCA, disk usage, session storage.4license: MIT5---67# Session Log Manager89Monitor, archive, rotate, and diagnose AI agent session logs across all stores. Deterministic shell scripts for health/archive/rotate; Python for forensics. Operates on system-wide session stores but archives per-repo.1011## Quick Start1213```bash14# Health check — scan all stores, report per-repo sizes, flag hotspots15bash .agents/skills/session-log-manager/scripts/session-health-check.sh1617# Archive — copy & compress sessions for this repo18bash .agents/skills/session-log-manager/scripts/session-archive.sh --repo build-meta-analysis1920# Rotate — compress sessions older than 7 days in the archive21bash .agents/skills/session-log-manager/scripts/session-rotate.sh2223# Forensics — crash/stall RCA from session ID24python3 .agents/skills/session-log-manager/scripts/session-forensics.py <session-id-or-path>2526# Image strip — remove embedded image byte-dicts, archive originals27python3 .agents/skills/session-log-manager/scripts/session-image-strip.py --dry-run --all28python3 .agents/skills/session-log-manager/scripts/session-image-strip.py --all29```3031Or use Makefile targets:3233```bash34make session-health35make session-archive REPO=build-meta-analysis36make session-rotate37```3839## What This Skill Manages4041### System Stores (Source of Truth — never modified)4243| Store | Location (macOS) | Format |44|---|---|---|45| Copilot CLI | `~/.copilot/session-state/<uuid>/events.jsonl` | JSONL (event stream) |46| VS Code Insiders | `~/Library/Application Support/Code - Insiders/User/workspaceStorage/<hash>/chatSessions/*.jsonl` | JSONL (chat log) |47| VS Code Stable | `~/Library/Application Support/Code/User/workspaceStorage/<hash>/chatSessions/*.jsonl` | JSONL (chat log) |4849### Archive (Repo-Local — managed by this skill)5051| Location | Contents |52|---|---|53| `runs/sessions/<repo>/` | Compressed `.jsonl.gz` files, deduplicated by session UUID |5455## Scripts5657### `session-health-check.sh` — P0: Monitor5859Scans all 3 session stores. Reports per-repo sizes. Flags hotspots.6061```bash62bash .agents/skills/session-log-manager/scripts/session-health-check.sh63```6465**Output:** Markdown report with:66- Summary table (files, size, oversized count per store)67- Copilot CLI per-repo breakdown (from `workspace.yaml`)68- VS Code per-workspace breakdown (from `workspace.json`)69- Health warnings (workspace >500 MB, session >10 MB, total >5 GB)7071**Thresholds:**72- Workspace: >500 MB = WARNING73- Individual session: >10 MB = WARNING74- Total: >5 GB = CRITICAL7576### `session-archive.sh` — P0: Archive7778Archives sessions for a specific repo with gzip compression and UUID-based deduplication.7980```bash81bash .agents/skills/session-log-manager/scripts/session-archive.sh --repo <name> [--output-dir <path>] [--dry-run]82```8384**Behavior:**85- Scans CLI sessions via `workspace.yaml` → `git_root` match86- Scans VS Code sessions via `workspace.json` → `folder` URI match87- Compresses each session to `.jsonl.gz` (4-5x compression)88- Names: `{cli|vscode}_{uuid}.jsonl.gz`89- Deduplicates: running twice produces 0 new copies9091### `session-rotate.sh` — P0: Rotate9293Compresses uncompressed sessions older than N days in the archive. Never touches system stores.9495```bash96bash .agents/skills/session-log-manager/scripts/session-rotate.sh [--archive-dir <path>] [--days 7] [--dry-run]97```9899**Retention policy:**100- 0-7 days: Raw `.jsonl` (active, live access)101- 7+ days: Compressed `.jsonl.gz` (searchable via `zgrep`)102- Never delete: Session logs are primary behavioral evidence103104### `session-forensics.py` — P1: Diagnose105106Crash/stall RCA from a session ID or file path.107108```bash109python3 .agents/skills/session-log-manager/scripts/session-forensics.py <session-id-or-path>110```111112**Detects:**113- Context growth curve (per-line byte sizes with ASCII chart)114- Oversized attachments (images serialized as JSON dicts — L81)115- Error and Canceled events (context budget exhaustion)116- Tool call distribution117- Crash risk level (LOW / MEDIUM / HIGH / CRITICAL)118119**Finds sessions by:**120- Direct file path121- UUID → searches CLI, VS Code Insiders, VS Code Stable stores122123### `session-image-strip.py` — P0: Strip Images124125Strips embedded image byte-dicts from VS Code session files. Images pasted into Copilot Chat126are serialized as `{"0": 137, "1": 80, ...}` — one JSON key per byte, ~2.5× inflate. This causes127V8 heap exhaustion and renderer crashes (L81, [microsoft/vscode#295334](https://github.com/microsoft/vscode/issues/295334)).128129```bash130python3 .agents/skills/session-log-manager/scripts/session-image-strip.py --dry-run --all131python3 .agents/skills/session-log-manager/scripts/session-image-strip.py --all132python3 .agents/skills/session-log-manager/scripts/session-image-strip.py --workspace ea03ad133```134135**Behavior:**136- Scans all JSONL session files for byte-dict patterns (PNG=137, JPEG=255, GIF=71)137- Archives each original to `~/.session-archive/images/<wsid>/` (gzipped)138- Replaces byte-dicts with `[IMAGE_STRIPPED: N bytes, stripped TIMESTAMP]`139- Preserves all conversation text, image metadata (name, path, kind)140- `--dry-run` shows what would be cleaned without modifying files141142## Tiers143144| Tier | Capabilities | Target Repos |145|---|---|---|146| **Good** | health check, archive (compressed), rotate | Any repo (T7, T9, T10, T11) |147| **Better** | Good + parse_session + search_sessions (from session-log-analysis skill) | Repos with analysis needs |148| **Best** | Better + forensics, monitoring, pre-commit guards | T1, B5a |149150## References151152- [Session Stores](references/session-stores.md) — Where logs live (macOS, Linux paths)153- [Size Budgets](references/size-budgets.md) — Thresholds, growth rates, compression ratios154- [Session Archive 2026-02-14](references/session-archive-2026-02-14.md) — Emergency cleanup: 604 files, 2.3 GB freed, restore instructions155156## Examples157158- [Health Check Output](examples/health-check-output.md) — Sample report159- [Forensics Report](examples/forensics-report.md) — Sample crash RCA160161## Related Skills162163| Skill | Relationship |164|---|---|165| `session-log-analysis` | Analysis (parse + search). Complementary — manager handles storage, analysis handles insights. |166167## Done When168169- `session-health-check.sh` runs without error on macOS, reports per-repo sizes170- `session-archive.sh` archives sessions for a named repo with compression and dedup171- `session-rotate.sh` compresses sessions older than threshold172- `session-forensics.py` produces crash RCA with context growth, attachment detection, error events173- All scripts exit 0 on healthy systems174175---176> Converted and distributed by [TomeVault](https://tomevault.io/claim/briancl2) — claim your Tome and manage your conversions.177<!-- tomevault:4.0:skill_md:2026-04-12 -->
tomevault-io