LSL - Live Session Logging¶
Real-time conversation monitoring and intelligent classification with zero data loss.
What It Does¶
- Real-Time Monitoring - Captures every coding agent conversation as it happens (Claude Code, Copilot CLI, OpenCode)
- Intelligent Classification - 5-layer system routes content (LOCAL vs CODING)
- Zero Data Loss - 4-layer monitoring architecture ensures reliability
- Multi-Project Support - Handles multiple projects with foreign session tracking
- Security Redaction - Automatic sanitization of secrets and credentials
5-Layer Classification¶
| Layer | Name | Function | Speed |
|---|---|---|---|
| 0 | Session Filter | Conversation context and bias tracking | Instant |
| 1 | PathAnalyzer | File operation pattern matching | <1ms |
| 2 | KeywordMatcher | Fast keyword-based classification | <10ms |
| 3 | EmbeddingClassifier | Semantic vector similarity | ~50ms |
| 4 | SemanticAnalyzer | LLM-powered deep understanding | <10ms (cached) |
Early exit optimization: Classification stops at first confident decision.
Supervision & Recovery¶
The transcript monitor is managed by a priority-ordered supervisor chain:
| Priority | Supervisor | Role |
|---|---|---|
| 1 | GlobalLSLCoordinator | Primary (per-session, launched by coding) |
| 2 | GlobalProcessSupervisor | Fallback (defers when coordinator active) |
| 3 | HealthPromptHook | Safety net (spawns coordinator if GPS exhausted) |
Self-protection features:
- Periodic flush: Writes accumulated exchanges every 5 minutes during long agent runs
- Idle timeout with tmux guard: Stays alive while tmux session exists (prevents restart budget waste)
- Auto-recovery: Prompt hook detects LSL down and spawns coordinator (rate-limited 1/min)
Content Routing¶
LOCAL Content (Project-Specific):
- Stored in:
project/.specstory/history/ - Format:
YYYY-MM-DD_HHMM-HHMM_<userhash>.md
CODING Content (Infrastructure):
- Redirected to:
coding/.specstory/history/ - Format:
YYYY-MM-DD_HHMM-HHMM_<userhash>_from-<project>.md
Security Redaction¶
13 pattern types automatically sanitized:
- API keys and tokens
- Passwords and credentials
- URLs with embedded passwords
- Email addresses
- Corporate user IDs
Performance: <5ms overhead per exchange.
Configuration¶
File: config/live-logging-config.json
{
"session_filter": {
"enabled": true,
"bias_threshold": 0.65,
"window_size": 5
},
"embedding_classifier": {
"enabled": true,
"similarity_threshold": 0.65,
"model": "Xenova/all-MiniLM-L6-v2"
},
"semantic_analyzer": {
"enabled": true,
"provider": "groq",
"model": "llama-3.3-70b"
}
}
Transcript Sources¶
The monitor supports three transcript sources, auto-detected per project:
| Source | Format | Agent |
|---|---|---|
| Claude Code | .jsonl files in ~/.claude/projects/ | Claude Code |
| Copilot CLI | events.jsonl in ~/.copilot/session-state/ | GitHub Copilot CLI |
| OpenCode | SQLite database (~/.local/share/opencode/opencode.db) | OpenCode |
All sources are normalized to a common exchange format before processing.
Key Files¶
| File | Purpose |
|---|---|
scripts/enhanced-transcript-monitor.js | Core monitoring process (all 3 transcript sources) |
src/live-logging/ReliableCodingClassifier.js | 5-layer classification |
src/live-logging/ConfigurableRedactor.js | Security redaction |
monitoring/global-monitor-watchdog.js | System-level watchdog |
Troubleshooting¶
Monitor not starting¶
# Check if running
ps aux | grep enhanced-transcript-monitor
# Check ETM heartbeat via coordinator (Phase 33+: .health/*.json files are
# no longer written; coordinator's lsl slice is the source of truth)
curl -fs http://localhost:3034/health/state \
| jq '.lsl | to_entries | map(select(.key | endswith(":coding")))'
# Restart via coding command
coding --restart-monitor
LSL files not generated¶
# Verify monitor is processing
tail -50 .logs/transcript-monitor-test.log
# Check today's files
ls -la .specstory/history/ | grep "$(date +%Y-%m-%d)"
# Recover from transcripts
PROJECT_PATH=/path/to/project CODING_REPO=/path/to/coding \
node scripts/batch-lsl-processor.js from-transcripts ~/.claude/projects/-path-to-project