logs-locally-plugin: Instructions file for Claude Code

logs-locally-plugin — Claude session JSONL → Local SQLite storage

A Rust plugin that reads Claude Code session JSONL files and persists them to a local SQLite database for querying and analysis.

Build & Run

cargo build --release
cargo run --release       # reads config.json from cwd

Config

See config.json. Key fields:

• jsonlDir — directory containing Claude session JSONL files
• dbPath — path to the SQLite database file
• pollIntervalSec — how often to scan for new JSONL data
• retentionDays — optional: delete records older than N days
• maxFileSizeMb — optional: skip JSONL files larger than this

Architecture

main.rs         — event loop: scan JSONL dir → parse sessions → upsert to SQLite
config.rs       — config.json loading and normalization
db.rs           — SQLite schema, upsert, query, and cleanup logic
parser.rs       — JSONL parsing, session extraction, dedup by session ID
watcher.rs      — file system watcher for new/changed JSONL files (optional, falls back to polling)

state.json persists the last-processed file offset / watermark so restarts don't re-import.

Key Behaviors

• Reads all .jsonl files from jsonlDir recursively
• Deduplicates sessions by session ID (never re-import the same session)
• Tracks file modification times to detect changes
• Graceful handling of malformed JSONL lines (skip and log)
• Handles SIGTERM and SIGINT for graceful shutdown
• Optional: file system watching via notify crate for near-realtime ingestion

Database Schema (SQLite)

CREATE TABLE IF NOT EXISTS sessions (
    id TEXT PRIMARY KEY,          -- Claude session ID
    title TEXT,
    model TEXT,                   -- model used (e.g. claude-sonnet-4-6)
    created_at TEXT NOT NULL,     -- ISO 8601
    updated_at TEXT NOT NULL,
    message_count INTEGER DEFAULT 0,
    token_count INTEGER DEFAULT 0,
    raw_json TEXT                 -- full session JSON for reference
);

CREATE TABLE IF NOT EXISTS messages (
    id TEXT PRIMARY KEY,
    session_id TEXT NOT NULL REFERENCES sessions(id),
    role TEXT NOT NULL,           -- "user" | "assistant"
    content TEXT NOT NULL,
    created_at TEXT NOT NULL,
    token_count INTEGER DEFAULT 0,
    parent_id TEXT REFERENCES messages(id)
);

CREATE INDEX IF NOT EXISTS idx_messages_session ON messages(session_id);
CREATE INDEX IF NOT EXISTS idx_messages_created ON messages(created_at);