Atomic-Term Database
Stores parsed terminal activity for the “Worked Files” feature.Copy
╔═════════════════════════════════════════════════════════════════════╗
║ ATOMIC-TERM.DB OVERVIEW ║
╠═════════════════════════════════════════════════════════════════════╣
║ ║
║ ┌──────────────────────────┐ ┌──────────────────────────┐ ║
║ │ │ │ │ ║
║ │ parsed_activities │ │ file_map │ ║
║ │ │ │ │ ║
║ │ - terminal_id │ │ - project_root (PK) │ ║
║ │ - terminal_name │ │ - rel_path (PK) │ ║
║ │ - session_id │ │ - basename │ ║
║ │ - operation │ │ - last_seen │ ║
║ │ - target │ │ │ ║
║ │ - path (auto-fixed) │ └──────────────────────────┘ ║
║ │ - rel_path │ │ ║
║ │ - ai_provider │ │ Fallback ║
║ │ - content │ │ Search ║
║ │ - raw_log │ ▼ ║
║ │ │◀──────────────┘ ║
║ └──────────────────────────┘ ║
║ ║
║ atomic-term.db ║
╚═════════════════════════════════════════════════════════════════════╝
Purpose
The VTE Parser (Alacritty) processes terminal output and detects file operations. These are logged to atomic-term.db for the “Worked Files” sidebar.Copy
╔═════════════════════════════════════════════════════════════════════╗
║ DATA FLOW ║
╠═════════════════════════════════════════════════════════════════════╣
║ ║
║ ┌───────────────────┐ ║
║ │ PTY Daemon │ Runs terminal shell ║
║ └────────┬──────────┘ ║
║ │ ║
║ │ Unix Socket ║
║ ▼ ║
║ ┌────────┴──────────┐ ║
║ │ SessionActor │ Routes PTY data ║
║ │ (Rust Backend) │ ║
║ └────────┬──────────┘ ║
║ │ ║
║ │ PTY Output ║
║ ▼ ║
║ ┌────────┴──────────┐ ║
║ │ VTE Parser │ Parse escape sequences ║
║ │ (Alacritty) │ Detect file operations ║
║ └────────┬──────────┘ ║
║ │ ║
║ │ Activity detected ║
║ ▼ ║
║ ┌────────┴──────────┐ ║
║ │ PTY Log │ INSERT parsed_activities ║
║ └────────┬──────────┘ ║
║ │ ║
║ ▼ ║
║ ┌────────┴──────────┐ ║
║ │ Auto-fix │ Resolve truncated paths ║
║ │ (Cross-DB) │ UPDATE path column ║
║ └────────┬──────────┘ ║
║ │ ║
║ │ Event emission ║
║ ▼ ║
║ ┌────────┴──────────┐ ║
║ │ Frontend UI │ "Worked Files" sidebar ║
║ └───────────────────┘ ║
║ ║
╚═════════════════════════════════════════════════════════════════════╝
Main Table: parsed_activities
Stores detected file operations from terminal output.Copy
╔═════════════════════════════════════════════════════════════════════╗
║ PARSED_ACTIVITIES TABLE ║
╠═════════════════════════════════════════════════════════════════════╣
║ ║
║ Column │ Type │ Description ║
║ ════════════════│══════════│══════════════════════════════════════║
║ id │ INTEGER │ Unique identifier (auto-increment) ║
║ terminal_id │ TEXT │ Terminal session ID ║
║ terminal_name │ TEXT │ Display name for the terminal ║
║ session_id │ TEXT │ NIIA session reference ║
║ operation │ TEXT │ Read/Write/Edit/Bash/etc. ║
║ target │ TEXT │ Raw path from terminal output ║
║ raw_log │ TEXT │ Full PTY output (for debugging) ║
║ content │ TEXT │ Parsed body content ║
║ details │ TEXT │ Extra information ║
║ line_count │ INTEGER │ Number of lines ║
║ saved_lines │ INTEGER │ Lines actually saved ║
║ ai_provider │ TEXT │ claude/gemini/openai/etc. ║
║ path │ TEXT │ Auto-fixed full path ║
║ rel_path │ TEXT │ Project-relative path ║
║ timestamp │ DATETIME │ When the activity was recorded ║
║ ║
╚═════════════════════════════════════════════════════════════════════╝
Terminal ID Format
How terminal IDs are structured.Copy
╔═════════════════════════════════════════════════════════════════════╗
║ TERMINAL ID FORMATS ║
╠═════════════════════════════════════════════════════════════════════╣
║ ║
║ FORMAT 1: term-{timestamp}-{tabCounter} ║
║ ┌───────────────────────────────────────────────────────────────┐ ║
║ │ │ ║
║ │ term-1764930848817-1002 │ ║
║ │ │ │ │ ║
║ │ ▼ ▼ │ ║
║ │ Unix ms Tab Counter │ ║
║ │ │ ║
║ │ Color calculation for UI: │ ║
║ │ ((tabCounter - 1) % 24) + 1 = colorIndex │ ║
║ │ │ ║
║ └───────────────────────────────────────────────────────────────┘ ║
║ ║
║ FORMAT 2: niia-{uniqueId} ║
║ ┌───────────────────────────────────────────────────────────────┐ ║
║ │ │ ║
║ │ niia-4942218766 │ ║
║ │ │ │ ║
║ │ ▼ │ ║
║ │ Random session ID (from daemon) │ ║
║ │ │ ║
║ └───────────────────────────────────────────────────────────────┘ ║
║ ║
╚═════════════════════════════════════════════════════════════════════╝
Cross-Database Path Resolution
Truncated paths are resolved using the file watcher database.Copy
╔═════════════════════════════════════════════════════════════════════╗
║ CROSS-DB PATH RESOLUTION ║
╠═════════════════════════════════════════════════════════════════════╣
║ ║
║ PROBLEM: Terminal output truncates long paths ║
║ ║
║ Example: ║
║ Terminal shows: "...ponents/button.tsx" ║
║ Real path: "/Users/dev/project/src/components/button.tsx" ║
║ ║
║ SOLUTION: Time-based search in file watcher database ║
║ ║
║ ┌───────────────────┐ ┌───────────────────┐ ║
║ │ niia-watcher.db │ │ atomic-term.db │ ║
║ ├───────────────────┤ ├───────────────────┤ ║
║ │ │ QUERY │ │ ║
║ │ file_events │────────▶│ parsed_activities│ ║
║ │ - basename │ │ - target (trunc) │ ║
║ │ - abs_path │ │ - path (resolved)│ ║
║ │ - ts (timestamp) │ │ - timestamp │ ║
║ └───────────────────┘ └───────────────────┘ ║
║ ║
║ TIME EXPANSION STRATEGY ║
║ ┌───────────────────────────────────────────────────────────────┐ ║
║ │ 1st attempt: +/- 1 minute │ ║
║ │ 2nd attempt: +/- 5 minutes │ ║
║ │ 3rd attempt: +/- 30 minutes │ ║
║ │ Fallback: file_map cache │ ║
║ └───────────────────────────────────────────────────────────────┘ ║
║ ║
╚═════════════════════════════════════════════════════════════════════╝
Write/Read Separation
Copy
╔═════════════════════════════════════════════════════════════════════╗
║ WRITE/READ SEPARATION ║
╠═════════════════════════════════════════════════════════════════════╣
║ ║
║ WRITE (Backend Only - PTY Log Module) ║
║ ┌───────────────────────────────────────────────────────────────┐ ║
║ │ │ ║
║ │ Function │ SQL │ Trigger │ ║
║ │ ════════════════│══════════════════════│═════════════════════│ ║
║ │ save_to_db │ INSERT parsed_ │ PTY stream output │ ║
║ │ │ activities │ │ ║
║ │ fix_row_sync │ UPDATE path, │ Post-INSERT hook │ ║
║ │ (auto-fix) │ rel_path │ │ ║
║ │ │ ║
║ └───────────────────────────────────────────────────────────────┘ ║
║ ║
║ READ (Tauri Commands) ║
║ ┌───────────────────────────────────────────────────────────────┐ ║
║ │ │ ║
║ │ Function │ SQL │ ║
║ │ ════════════════════│═══════════════════════════════════════│ ║
║ │ get_worked_files │ SELECT WHERE operation │ ║
║ │ │ IN (Read,Write,Edit,Bash) │ ║
║ │ get_details │ SELECT WHERE id = ? │ ║
║ │ │ ║
║ └───────────────────────────────────────────────────────────────┘ ║
║ ║
╚═════════════════════════════════════════════════════════════════════╝
Design Principles Applied
Copy
╔═════════════════════════════════════════════════════════════════════╗
║ DESIGN PRINCIPLES ║
╠═════════════════════════════════════════════════════════════════════╣
║ ║
║ SIMPLICITY (SMPC) ║
║ ┌───────────────────────────────────────────────────────────────┐ ║
║ │ [x] PTY Log module is ONLY writer (single responsibility) │ ║
║ │ [x] Post-insert path fix (deferred resolution) │ ║
║ │ [x] Frontend uses invoke() for reads only │ ║
║ │ [x] No complex triggers or stored procedures │ ║
║ └───────────────────────────────────────────────────────────────┘ ║
║ ║
║ ORDER FROM CHAOS (OFAC) ║
║ ┌───────────────────────────────────────────────────────────────┐ ║
║ │ [x] Watcher --> file_map progressive fallback │ ║
║ │ [x] 1min --> 5min --> 30min time-based search expansion │ ║
║ │ [x] emit() + polling hybrid for UI updates │ ║
║ │ [x] Graceful degradation when watcher unavailable │ ║
║ └───────────────────────────────────────────────────────────────┘ ║
║ ║
╚═════════════════════════════════════════════════════════════════════╝
Quick Reference
| Aspect | Value |
|---|---|
| Location | ~/Library/Application Support/monolex/protocols/niia/database/atomic-term.db |
| Primary Owner | PTY Log module |
| Main Table | parsed_activities |
| Write Triggers | PTY stream output, Auto-fix |
| Read By | Frontend “Worked Files” sidebar |