agentacta 1.3.4 → 1.4.0

package/README.md

@@ -4,9 +4,11 @@
 [![npm](https://img.shields.io/npm/v/agentacta)](https://www.npmjs.com/package/agentacta)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-**Your AI agent does hundreds of things. Can you find them?**
+**Your agent did 1000s of things today. Can you find the 1 that broke prod?**
 
-AgentActa is an audit trail and search engine for AI agent sessions. It indexes everything your agent did — every message, tool call, file edit, web search, and decision — into a fast, searchable local interface.
+AgentActa is a local audit trail and search engine for AI agent sessions.
+
+It indexes messages, tool calls, file edits, searches, and decisions into a fast UI you can query in seconds.
 
 One command. Zero config. Full visibility.
 
@@ -18,24 +20,25 @@ npx agentacta
   <img src="screenshots/demo.gif" alt="AgentActa demo" width="800">
 </p>
 
----
+## Why this exists
 
-## Why
+Agents move fast. Your memory of what happened doesn’t.
 
-AI agents are powerful. They write code, send emails, manage infrastructure, make decisions on your behalf. But when you need to know *what happened* — what was changed, when, and why — you're digging through scattered logs or asking the agent to remember (it won't).
+When you need to answer “what changed, when, and why,” you’re usually scraping logs, scrolling transcripts, or asking the same assistant that forgot 20 minutes ago.
 
-AgentActa gives you a single, searchable view of everything.
+AgentActa gives you one place to inspect the full trail.
 
-## What You Get
+## What you get
 
-🔍 **Full-text search** across all messages, tool calls, and results
-📋 **Session browser** with summaries, token breakdowns (input/output), and model info
-📅 **Timeline view** — everything that happened on any given day
-📁 **File activity** — every file your agent touched, across all sessions
-📊 **Stats** — sessions, messages, tool usage, token counts
-⚡ **Live indexing** — new sessions appear automatically via file watching
-📱 **Mobile-friendly** — responsive UI with bottom tab navigation
-💡 **Smart suggestions** — quick search chips derived from your actual session data
+- 🔍 Full-text search across messages, tool calls, and results
+- 📋 Session browser with summaries, token breakdowns, and model info
+- 📅 Timeline view with live updates for today
+- 📁 File activity across all indexed sessions
+- 🌗 Light and dark themes
+- 📊 Stats for sessions, messages, tools, and tokens
+- ⚡ Live indexing via file watching
+- 📱 Mobile-friendly UI
+- 💡 Search suggestions based on real data
 
 ## Demo
 
@@ -51,62 +54,81 @@ https://github.com/mirajchokshi/agentacta/raw/main/screenshots/demo-final.mp4
 ![Stats](screenshots/stats.png)
 ![Search Results](screenshots/search-results.png)
 
-## Quick Start
+## Quick start
 
 ```bash
-# Run directly (no install needed)
+# run directly
 npx agentacta
 
-# Or install globally
+# or install globally
 npm install -g agentacta
 agentacta
 ```
 
-Open `http://localhost:4003` in your browser.
+Open: `http://localhost:4003`
 
-AgentActa automatically finds your sessions in:
+Auto-detected session paths:
 - `~/.openclaw/agents/*/sessions/` (OpenClaw)
 - `~/.claude/projects/*/` (Claude Code)
 - `~/.codex/sessions/` (Codex CLI)
 
-Or point it at a custom path:
+Custom path:
 
 ```bash
 AGENTACTA_SESSIONS_PATH=/path/to/sessions agentacta
 ```
 
-## Features
+## Core features
 
 ### Search
-Full-text search powered by SQLite FTS5. Filter by message type (messages, tool calls, results) and role (user, assistant). Quick search suggestions are generated from your actual data — most-used tools, common topics, frequently touched files.
+
+SQLite FTS5 full-text search with filters for message type (messages, tool calls, results) and role (user, assistant).
+
+Suggestions come from your own dataset: top tools, common topics, frequently touched files.
 
 ### Sessions
-Browse all indexed sessions with auto-generated summaries, token breakdowns (output vs input), and model info. Sessions are automatically tagged by type — cron jobs, sub-agent tasks, and heartbeat sessions get distinct badges. Click into any session to see the full event history, most recent first.
+
+Browse indexed sessions with auto-generated summaries, token splits (input/output), and model details. Click into any session to see the full event history.
+
+Session types get tagged so noisy categories are easier to spot (cron, sub-agent, heartbeat).
 
 ### Timeline
-Pick a date, see everything that happened. Messages, tool invocations, file changes — most recent first.
+
+Pick a date, see everything that happened, newest first. Today's view updates live as new events come in.
 
 ### File Activity
-See every file your agent read, wrote, or edited. Sort by most touched, most recent, or most sessions. Filter by extension, group by directory. Click any file to see which sessions touched it and what was done.
+
+See what files were touched, how often, and by which sessions.
+
+Sort by recency, frequency, or session count. Filter by extension. Group by directory. Click any file to see which sessions touched it.
 
 ### Export
-Download any session or search results as Markdown or JSON. Great for sharing, auditing, or archiving.
 
-## How It Works
+Export sessions or search results as Markdown or JSON.
 
-AgentActa reads JSONL session files (including OpenClaw, Claude Code, and Codex CLI formats), parses every message and tool call, and indexes them into a local SQLite database with FTS5 full-text search.
+Useful for handoffs, incident writeups, and audit archives.
 
-The web UI is a single-page app served by a lightweight Node.js HTTP server. No frameworks, no build step, no external dependencies beyond `better-sqlite3`.
+## How it works
 
-```
-Session JSONL files → SQLite + FTS5 index → HTTP API → Web UI
+AgentActa parses JSONL session files (OpenClaw, Claude Code, Codex CLI), then indexes events into local SQLite with FTS5.
+
+The UI is a single-page app served by a lightweight Node HTTP server.
+
+No framework build pipeline. Minimal moving parts.
+
+```text
+Session JSONL files -> SQLite + FTS5 index -> HTTP API -> Web UI
 ```
 
-Data never leaves your machine.
+Everything stays on your machine.
 
 ## Configuration
 
-On first run, AgentActa creates a config file with sensible defaults at `~/.config/agentacta/config.json` (or `agentacta.config.json` in the current directory if it exists):
+On first run, AgentActa creates:
+- `~/.config/agentacta/config.json`
+- or `agentacta.config.json` in current directory (if present)
+
+Default config:
 
 ```json
 {
@@ -118,85 +140,82 @@ On first run, AgentActa creates a config file with sensible defaults at `~/.conf
 }
 ```
 
-### Storage Modes
+### Storage modes
 
-- **`reference`** (default) — Lightweight index. Stores parsed events in SQLite but not the raw JSONL. Source files must remain on disk.
-- **`archive`** — Full JSONL stored in SQLite. Sessions survive even if the original files are deleted. Uses more disk space.
+- `reference` (default): index parsed events in SQLite, keep source JSONL on disk. Lightweight.
+- `archive`: store full JSONL in SQLite. Sessions survive even if original files are deleted. Uses more disk.
 
-### Environment Variables
+### Environment variables
 
 | Variable | Default | Description |
 |---|---|---|
 | `PORT` | `4003` | Server port |
-| `AGENTACTA_HOST` | `127.0.0.1` | Bind address (see [Security](#security)) |
-| `AGENTACTA_SESSIONS_PATH` | Auto-detected | Custom sessions directory |
-| `AGENTACTA_DB_PATH` | `./agentacta.db` | Database file location |
-| `AGENTACTA_STORAGE` | `reference` | Storage mode (`reference` or `archive`) |
-| `AGENTACTA_PROJECT_ALIASES_JSON` | unset | JSON object mapping inferred project names (e.g. `{"old-name":"new-name"}`) |
+| `AGENTACTA_HOST` | `127.0.0.1` | Bind address |
+| `AGENTACTA_SESSIONS_PATH` | auto-detected | Custom sessions directory |
+| `AGENTACTA_DB_PATH` | `./agentacta.db` | Database path |
+| `AGENTACTA_STORAGE` | `reference` | `reference` or `archive` |
+| `AGENTACTA_PROJECT_ALIASES_JSON` | unset | Rename inferred project labels |
 
 ## API
 
-AgentActa exposes a JSON API for programmatic access — useful for integrating search into your agent's workflow.
-
 | Endpoint | Description |
 |---|---|
-| `GET /api/stats` | Overview: session count, messages, tools, tokens |
-| `GET /api/sessions` | List sessions with metadata and token breakdowns |
-| `GET /api/sessions/:id` | Full session with all events |
-| `GET /api/search?q=<query>` | Full-text search with type/role/date filters |
-| `GET /api/suggestions` | Data-driven search suggestions |
-| `GET /api/timeline?date=YYYY-MM-DD` | All events for a given day |
-| `GET /api/files` | All files touched across sessions |
-| `GET /api/export/session/:id?format=md` | Export session as Markdown or JSON |
+| `GET /api/stats` | Session/message/tool/token totals |
+| `GET /api/sessions` | Session list with metadata |
+| `GET /api/sessions/:id` | Full session events |
+| `GET /api/search?q=<query>` | Full-text search + filters |
+| `GET /api/suggestions` | Search suggestions |
+| `GET /api/timeline?date=YYYY-MM-DD` | Events for one day |
+| `GET /api/files` | Touched-file inventory |
+| `GET /api/export/session/:id?format=md` | Export one session |
+| `GET /api/timeline/stream?after=<ts>` | SSE stream for live timeline updates |
+| `POST /api/maintenance` | VACUUM + WAL checkpoint (returns size before/after) |
 | `GET /api/export/search?q=<query>&format=md` | Export search results |
 
-### Agent Integration
-
-Your AI agent can query AgentActa for better recall:
+Agent integration example:
 
 ```javascript
-const results = await fetch('http://localhost:4003/api/search?q=deployment+issue&limit=5');
-const data = await results.json();
-// Agent now has context from past sessions
+const res = await fetch('http://localhost:4003/api/search?q=deployment+issue&limit=5');
+const data = await res.json();
 ```
 
-### Demo Mode
-
-Want to see what AgentActa looks like with data? Run with demo sessions:
+## Demo mode
 
 ```bash
-# Generate demo data and start in demo mode
+# seed demo data + run
 npm run demo
 
-# Or separately:
+# or split steps
 node scripts/seed-demo.js
 node index.js --demo
 ```
 
-This creates 7 realistic sessions simulating a developer building a weather app — scaffolding, API integration, frontend, debugging, deployment, tests, and a sub-agent task.
+Demo mode creates 7 realistic sessions (weather app build path: scaffolding, API, frontend, debugging, deployment, tests, sub-agent task).
 
 ## Security
 
-**AgentActa is a local tool.** It binds to `127.0.0.1` by default — only accessible from your machine.
+AgentActa binds to `127.0.0.1` by default.
 
-To expose on your network (e.g., for Tailscale access):
+If you expose it on a network, do it intentionally:
 
 ```bash
 AGENTACTA_HOST=0.0.0.0 agentacta
 ```
 
-⚠️ **Important:** Agent session data can contain sensitive information — file contents, API responses, personal messages, tool call arguments. If you expose AgentActa on a network, ensure it's a trusted one. There is no built-in authentication.
+**Important:** Session data can contain sensitive content (file snippets, API payloads, personal messages, tool args). There is no built-in auth yet, so only expose on trusted networks.
 
-## Tech Stack
+## Tech stack
 
-- **Node.js** — HTTP server (built-in `http`, no Express)
-- **better-sqlite3** — Fast SQLite with FTS5 full-text search
-- **Vanilla HTML/CSS/JS** — No framework, no build step
-- **PWA** — Installable as a home screen app
+- Node.js (built-in `http`)
+- `better-sqlite3` + SQLite FTS5
+- Vanilla HTML/CSS/JS
+- PWA support
 
 ## Privacy
 
-All data stays local. AgentActa runs entirely on your machine — no cloud services, no telemetry, no external requests. Your agent history is yours.
+No telemetry. No cloud sync. No external indexing service.
+
+Your session history stays local.
 
 ## Compatibility
 
@@ -207,13 +226,15 @@ All data stays local. AgentActa runs entirely on your machine — no cloud servi
 
 ## Contributing
 
-PRs welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for dev setup and guidelines. If you're adding support for a new agent format, add a parser in `indexer.js` and open a PR.
+PRs welcome.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). If you’re adding a new agent format, start in `indexer.js`.
 
-## Etymology
+## Name
 
-*Acta* (Latin) — "things done." In ancient Rome, the *acta diurna* were daily public records of official proceedings — senate decisions, military victories, births and deaths — posted in public spaces for all citizens to read.
+*Acta* is Latin for “things done.”
 
-AgentActa is the same idea: a complete, searchable record of everything your AI agent did.
+That’s the job here: keep a readable record of what your agents actually did.
 
 ## License
 
@@ -221,4 +242,4 @@ MIT
 
 ---
 
-Built in Chicago by humans and agents working together.
+Built in Chicago by humans and agents.

package/db.js

@@ -54,6 +54,7 @@ function init(dbPath) {
       FOREIGN KEY (session_id) REFERENCES sessions(id) ON DELETE CASCADE
     );
 
+    CREATE INDEX IF NOT EXISTS idx_sessions_start_time ON sessions(start_time DESC);
     CREATE INDEX IF NOT EXISTS idx_events_session ON events(session_id);
     CREATE INDEX IF NOT EXISTS idx_events_timestamp ON events(timestamp);
     CREATE INDEX IF NOT EXISTS idx_events_type ON events(type);

package/index.js

@@ -428,13 +428,67 @@ const server = http.createServer((req, res) => {
       const date = query.date || (() => { const n = new Date(); return `${n.getFullYear()}-${String(n.getMonth()+1).padStart(2,'0')}-${String(n.getDate()).padStart(2,'0')}`; })();
       const from = new Date(date + 'T00:00:00').toISOString();
       const to = new Date(date + 'T23:59:59.999').toISOString();
+      const limit = Math.min(parseInt(query.limit || '100', 10) || 100, 500);
+      const offset = Math.max(parseInt(query.offset || '0', 10) || 0, 0);
       const events = db.prepare(
         `SELECT e.*, s.summary as session_summary FROM events e
          JOIN sessions s ON s.id = e.session_id
          WHERE e.timestamp >= ? AND e.timestamp <= ?
-         ORDER BY e.timestamp DESC`
-      ).all(from, to);
-      json(res, { date, events, total: events.length });
+         ORDER BY e.timestamp DESC
+         LIMIT ? OFFSET ?`
+      ).all(from, to, limit, offset);
+      const total = db.prepare(
+        `SELECT COUNT(*) as c FROM events e
+         WHERE e.timestamp >= ? AND e.timestamp <= ?`
+      ).get(from, to).c;
+      json(res, { date, events, total, limit, offset, hasMore: offset + events.length < total });
+    }
+    else if (pathname === '/api/timeline/stream') {
+      res.writeHead(200, {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        'Connection': 'keep-alive',
+        'X-Accel-Buffering': 'no'
+      });
+      res.write(': connected\n\n');
+
+      let lastTs = query.after || new Date().toISOString();
+
+      const onUpdate = () => {
+        try {
+          const rows = db.prepare(
+            `SELECT e.*, s.summary as session_summary FROM events e
+             JOIN sessions s ON s.id = e.session_id
+             WHERE e.timestamp > ?
+             ORDER BY e.timestamp ASC`
+          ).all(lastTs);
+          if (rows.length) {
+            lastTs = rows[rows.length - 1].timestamp;
+            res.write(`id: ${lastTs}\ndata: ${JSON.stringify(rows)}\n\n`);
+          }
+        } catch (err) {
+          console.error('Timeline SSE error:', err.message);
+        }
+      };
+
+      sseEmitter.on('session-update', onUpdate);
+
+      const ping = setInterval(() => {
+        try { res.write(': ping\n\n'); } catch {}
+      }, 30000);
+
+      req.on('close', () => {
+        sseEmitter.off('session-update', onUpdate);
+        clearInterval(ping);
+      });
+    }
+    else if (pathname === '/api/maintenance') {
+      if (req.method !== 'POST') return json(res, { error: 'Method not allowed' }, 405);
+      const sizeBefore = getDbSize();
+      db.pragma('wal_checkpoint(TRUNCATE)');
+      db.exec('VACUUM');
+      const sizeAfter = getDbSize();
+      json(res, { ok: true, sizeBefore, sizeAfter });
     }
     else if (pathname === '/api/files') {
       const limit = parseInt(query.limit) || 100;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentacta",
-  "version": "1.3.4",
+  "version": "1.4.0",
   "description": "Audit trail and search engine for AI agent sessions",
   "main": "index.js",
   "bin": {

package/public/app.js

@@ -3,10 +3,31 @@ const $$ = (s, p = document) => [...p.querySelectorAll(s)];
 const content = $('#content');
 const API = '/api';
 
-async function api(path) {
+const THEME_KEY = 'agentacta-theme';
+
+function applyTheme(theme) {
+  document.documentElement.setAttribute('data-theme', theme);
+  const meta = document.querySelector('meta[name="theme-color"]');
+  if (meta) meta.setAttribute('content', theme === 'light' ? '#f5f7fb' : '#0a0e1a');
+}
+
+function initTheme() {
+  const saved = localStorage.getItem(THEME_KEY);
+  const theme = saved === 'dark' || saved === 'light' ? saved : 'light';
+  applyTheme(theme);
+}
+
+function toggleTheme() {
+  const current = document.documentElement.getAttribute('data-theme') === 'dark' ? 'dark' : 'light';
+  const next = current === 'light' ? 'dark' : 'light';
+  localStorage.setItem(THEME_KEY, next);
+  applyTheme(next);
+}
+
+async function api(path, options = {}) {
   let res;
   try {
-    res = await fetch(API + path);
+    res = await fetch(API + path, options);
   } catch (err) {
     // Network error (server down, offline, etc.)
     return { _error: true, error: 'Network error' };
@@ -71,6 +92,26 @@ function escHtml(s) {
   return s.replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;');
 }
 
+function fmtToolName(name) {
+  if (!name) return '';
+  // MCP tools: mcp__provider__action → mcp_provider_action
+  const mcp = name.match(/^mcp__(.+?)__(.+)$/);
+  if (mcp) {
+    const provider = mcp[1].replace(/__/g, '_');
+    const action = mcp[2].replace(/__/g, '_');
+    return `mcp_${provider}_${action}`;
+  }
+  return name;
+}
+
+function fmtToolGroup(name) {
+  if (!name) return '';
+  // MCP tools: collapse to mcp_provider (no action)
+  const mcp = name.match(/^mcp__(.+?)__/);
+  if (mcp) return 'mcp_' + mcp[1].replace(/__/g, '_');
+  return name;
+}
+
 function truncate(s, n = 200) {
   if (!s) return '';
   return s.length > n ? s.slice(0, n) + '\u2026' : s;
@@ -95,6 +136,48 @@ function transitionView() {
   content.classList.add('view-enter');
 }
 
+function skeletonLine(width = '100%', height = '12px') {
+  return `<div class="skeleton-line" style="width:${width};height:${height}"></div>`;
+}
+
+function skeletonRows(count = 6, kind = 'event') {
+  if (kind === 'session') {
+    return Array.from({ length: count }).map(() => `
+      <div class="session-item skeleton-card">
+        <div class="skeleton-line" style="width:58%;height:12px"></div>
+        <div class="skeleton-line" style="width:90%;height:14px"></div>
+        <div class="skeleton-line" style="width:72%;height:14px"></div>
+      </div>
+    `).join('');
+  }
+  if (kind === 'stats') {
+    return Array.from({ length: count }).map(() => `
+      <div class="stat-card skeleton-card">
+        <div class="skeleton-line" style="width:44%;height:10px"></div>
+        <div class="skeleton-line" style="width:66%;height:28px;margin-top:8px"></div>
+      </div>
+    `).join('');
+  }
+  if (kind === 'file') {
+    return Array.from({ length: count }).map(() => `
+      <div class="file-item skeleton-card">
+        <div class="skeleton-line" style="width:62%;height:13px"></div>
+        <div class="skeleton-line" style="width:86%;height:12px;margin-top:10px"></div>
+      </div>
+    `).join('');
+  }
+  return Array.from({ length: count }).map(() => `
+    <div class="event-item skeleton-row">
+      <div class="skeleton-line" style="width:72px;height:10px"></div>
+      <div class="skeleton-line" style="width:60px;height:16px"></div>
+      <div class="event-body">
+        <div class="skeleton-line" style="width:82%;height:12px"></div>
+        <div class="skeleton-line" style="width:66%;height:12px;margin-top:8px"></div>
+      </div>
+    </div>
+  `).join('');
+}
+
 // --- Hash routing ---
 window._navDepth = 0;
 
@@ -118,6 +201,7 @@ function updateNavActive(view) {
 function handleRoute() {
   const raw = (window.location.hash || '').slice(1) || 'search';
   if (window._sseCleanup) { window._sseCleanup(); window._sseCleanup = null; }
+  if (window._timelineScrollHandler) { window.removeEventListener('scroll', window._timelineScrollHandler); window._timelineScrollHandler = null; }
 
   if (raw.startsWith('session/')) {
     const id = decodeURIComponent(raw.slice('session/'.length));
@@ -144,7 +228,7 @@ function renderEvent(ev) {
   let body = '';
 
   if (ev.type === 'tool_call') {
-    body = `<span class="tool-name">${escHtml(ev.tool_name)}</span>`;
+    body = `<span class="tool-name">${escHtml(fmtToolName(ev.tool_name))}</span>`;
     if (ev.tool_args) {
       try {
         const args = JSON.parse(ev.tool_args);
@@ -154,7 +238,7 @@ function renderEvent(ev) {
       }
     }
   } else if (ev.type === 'tool_result') {
-    body = `<span class="tool-name">\u2192 ${escHtml(ev.tool_name)}</span>`;
+    body = `<span class="tool-name">\u2192 ${escHtml(fmtToolName(ev.tool_name))}</span>`;
     if (ev.content) {
       body += `<div class="tool-args">${escHtml(truncate(ev.content, 500))}</div>`;
     }
@@ -178,7 +262,7 @@ function renderTimelineEvent(ev) {
   let body = '';
 
   if (ev.type === 'tool_call') {
-    body = `<span class="tool-name">${escHtml(ev.tool_name)}</span>`;
+    body = `<span class="tool-name">${escHtml(fmtToolName(ev.tool_name))}</span>`;
     if (ev.tool_args) {
       try {
         const args = JSON.parse(ev.tool_args);
@@ -188,7 +272,7 @@ function renderTimelineEvent(ev) {
       }
     }
   } else if (ev.type === 'tool_result') {
-    body = `<span class="tool-name">\u2192 ${escHtml(ev.tool_name)}</span>`;
+    body = `<span class="tool-name">\u2192 ${escHtml(fmtToolName(ev.tool_name))}</span>`;
     if (ev.content) {
       body += `<div class="tool-args">${escHtml(truncate(ev.content, 500))}</div>`;
     }
@@ -296,7 +380,12 @@ async function viewSearch(query = '') {
       <span class="filter-chip ${roleFilter==='user'?'active':''}" data-filter="role" data-val="user">User</span>
       <span class="filter-chip ${roleFilter==='assistant'?'active':''}" data-filter="role" data-val="assistant">Assistant</span>
     </div>
-    <div id="results"></div>`;
+    <div id="results">
+      <div class="search-bar skeleton-card" style="margin-top:6px">
+        <div class="skeleton-line" style="height:16px;width:40%"></div>
+      </div>
+      ${skeletonRows(4, 'session')}
+    </div>`;
 
   content.innerHTML = html;
   transitionView();
@@ -325,7 +414,7 @@ async function viewSearch(query = '') {
 
 async function showSearchHome() {
   const el = $('#results');
-  el.innerHTML = '<div class="loading">Loading</div>';
+  el.innerHTML = `${skeletonRows(4, 'session')}`;
 
   const stats = await api('/stats');
   const sessions = await api('/sessions?limit=5');
@@ -376,7 +465,7 @@ async function doSearch(q) {
   const el = $('#results');
   if (!q.trim()) { el.innerHTML = '<div class="empty"><h2>Type to search</h2><p>Search across all sessions, messages, and tool calls</p></div>'; return; }
 
-  el.innerHTML = '<div class="loading">Searching</div>';
+  el.innerHTML = `${skeletonRows(6, 'event')}`;
 
   const type = window._searchType || '';
   const role = window._searchRole || '';
@@ -402,7 +491,7 @@ async function doSearch(q) {
       <div class="result-meta">
         <span class="event-badge ${badgeClass(r.type, r.role)}">${r.type === 'tool_call' ? 'tool' : r.role || r.type}</span>
         <span class="session-time">${fmtTime(r.timestamp)}</span>
-        ${r.tool_name ? `<span class="tool-name">${escHtml(r.tool_name)}</span>` : ''}
+        ${r.tool_name ? `<span class="tool-name">${escHtml(fmtToolName(r.tool_name))}</span>` : ''}
         <span class="session-link" data-session="${r.session_id}">view session \u2192</span>
       </div>
       <div class="result-content">${escHtml(truncate(r.content || r.tool_args || r.tool_result || '', 400))}</div>
@@ -420,7 +509,8 @@ async function doSearch(q) {
 
 async function viewSessions() {
   window._currentSessionId = null;
-  content.innerHTML = '<div class="loading">Loading</div>';
+  content.innerHTML = `<div class="page-title">Sessions</div>${skeletonRows(4, 'session')}`;
+  transitionView();
   const data = await api('/sessions?limit=200');
   if (data._error) {
     content.innerHTML = '<div class="empty"><h2>Unable to load</h2><p>Server unavailable. Pull to refresh or try again.</p></div>';
@@ -442,6 +532,12 @@ async function viewSession(id) {
   window._currentSessionId = id;
   setHash('session/' + encodeURIComponent(id));
   window.scrollTo(0, 0);
+  content.innerHTML = `
+    <div class="back-btn">← Back</div>
+    <div class="page-title">Session</div>
+    ${skeletonRows(8, 'event')}
+  `;
+  transitionView();
   const data = await api(`/sessions/${id}`);
 
   if (data._error || data.error) { content.innerHTML = `<div class="empty"><h2>${escHtml(data.error || 'Unable to load')}</h2></div>`; return; }
@@ -674,34 +770,93 @@ async function viewTimeline(date) {
     date = `${now.getFullYear()}-${String(now.getMonth()+1).padStart(2,'0')}-${String(now.getDate()).padStart(2,'0')}`;
   }
   window._lastView = 'timeline';
+  window._timelineState = { date, limit: 100, offset: 0, hasMore: true, loading: false };
 
-  let html = `<div class="page-title">Timeline</div>
+  content.innerHTML = `<div class="page-title">Timeline</div>
     <input type="date" class="date-input" id="dateInput" value="${date}">
-    <div id="timelineContent"><div class="loading">Loading</div></div>`;
-  content.innerHTML = html;
+    <div id="timelineContent">${skeletonRows(8, 'event')}</div>
+    <div id="timelineLoadMore" class="loading-more" style="display:none">Loading more…</div>`;
   transitionView();
 
-  const data = await api(`/timeline?date=${date}`);
-  if (data._error) {
-    $('#timelineContent').innerHTML = '<div class="empty"><h2>Unable to load</h2><p>Server unavailable. Pull to refresh or try again.</p></div>';
-    return;
-  }
   const el = $('#timelineContent');
+  const state = window._timelineState;
 
-  if (!data.events.length) {
-    el.innerHTML = '<div class="empty"><h2>No activity</h2><p>Nothing recorded on this day</p></div>';
-  } else {
-    el.innerHTML = `<div class="timeline-events-wrap">
-      <div class="timeline-line"></div>
-      ${data.events.map(renderTimelineEvent).join('')}
-    </div>`;
+  async function loadTimelinePage(append = false) {
+    if (state.loading || (!state.hasMore && append)) return;
+    state.loading = true;
+    if (append) $('#timelineLoadMore').style.display = 'block';
+
+    const data = await api(`/timeline?date=${state.date}&limit=${state.limit}&offset=${state.offset}`);
+    state.loading = false;
+    $('#timelineLoadMore').style.display = 'none';
+
+    if (data._error) {
+      if (!append) el.innerHTML = '<div class="empty"><h2>Unable to load</h2><p>Server unavailable. Pull to refresh or try again.</p></div>';
+      return;
+    }
+
+    state.hasMore = !!data.hasMore;
+    state.offset += (data.events || []).length;
+
+    if (!append) {
+      if (!data.events.length) {
+        el.innerHTML = '<div class="empty"><h2>No activity</h2><p>Nothing recorded on this day</p></div>';
+        return;
+      }
+      el.innerHTML = `<div class="timeline-events-wrap" id="timelineWrap"><div class="timeline-line"></div>${data.events.map(renderTimelineEvent).join('')}</div>`;
+      return;
+    }
+
+    const wrap = $('#timelineWrap');
+    if (wrap) {
+      wrap.insertAdjacentHTML('beforeend', data.events.map(renderTimelineEvent).join(''));
+    }
+  }
+
+  await loadTimelinePage(false);
+
+  if (window._timelineScrollHandler) window.removeEventListener('scroll', window._timelineScrollHandler);
+  window._timelineScrollHandler = () => {
+    const st = window._timelineState;
+    if (!st || st.loading || !st.hasMore) return;
+    const nearBottom = window.innerHeight + window.scrollY >= document.body.offsetHeight - 300;
+    if (nearBottom) loadTimelinePage(true);
+  };
+  window.addEventListener('scroll', window._timelineScrollHandler, { passive: true });
+
+  // Live updates via SSE (only for today)
+  const today = new Date();
+  const todayStr = `${today.getFullYear()}-${String(today.getMonth()+1).padStart(2,'0')}-${String(today.getDate()).padStart(2,'0')}`;
+  if (window._timelineSse) { window._timelineSse.close(); window._timelineSse = null; }
+  if (date === todayStr) {
+    const sse = new EventSource(`/api/timeline/stream?after=${encodeURIComponent(new Date().toISOString())}`);
+    window._timelineSse = sse;
+    sse.onmessage = (evt) => {
+      try {
+        const rows = JSON.parse(evt.data);
+        const wrap = $('#timelineWrap');
+        if (wrap && rows.length) {
+          const html = rows.map(renderTimelineEvent).join('');
+          wrap.insertAdjacentHTML('afterbegin', html);
+          // Flash new events
+          rows.forEach(r => {
+            const el = wrap.querySelector(`[data-event-id="${r.id}"]`);
+            if (el) { el.classList.add('event-highlight'); setTimeout(() => el.classList.remove('event-highlight'), 2000); }
+          });
+        }
+      } catch {}
+    };
   }
 
-  $('#dateInput').addEventListener('change', e => viewTimeline(e.target.value));
+  $('#dateInput').addEventListener('change', e => {
+    if (window._timelineSse) { window._timelineSse.close(); window._timelineSse = null; }
+    viewTimeline(e.target.value);
+  });
 }
 
 async function viewStats() {
-  content.innerHTML = '<div class="loading">Loading</div>';
+  content.innerHTML = `<div class="page-title">Stats</div><div class="stat-grid">${skeletonRows(5, 'stats')}</div>`;
+  transitionView();
   const data = await api('/stats');
   if (data._error) {
     content.innerHTML = '<div class="empty"><h2>Unable to load</h2><p>Server unavailable. Pull to refresh or try again.</p></div>';
@@ -713,14 +868,19 @@ async function viewStats() {
       <div class="stat-card accent-blue"><div class="label">Sessions</div><div class="value">${data.sessions}</div></div>
       <div class="stat-card accent-green"><div class="label">Messages</div><div class="value">${data.messages.toLocaleString()}</div></div>
       <div class="stat-card accent-amber"><div class="label">Tool Calls</div><div class="value">${data.toolCalls.toLocaleString()}</div></div>
-      <div class="stat-card accent-purple"><div class="label">Unique Tools</div><div class="value">${data.uniqueTools}</div></div>
+      <div class="stat-card accent-purple"><div class="label">Unique Tools</div><div class="value">${new Set((data.tools||[]).filter(t=>t).map(t=>fmtToolGroup(t))).size}</div></div>
       <div class="stat-card accent-teal"><div class="label">Total Tokens</div><div class="value">${(data.totalTokens || 0).toLocaleString()}</div></div>
     </div>
 
     <div class="section-label">Configuration</div>
-    <div style="display:grid;grid-template-columns:repeat(auto-fit, minmax(200px, 1fr));gap:var(--space-md);margin-bottom:var(--space-xl)">
+    <div style="display:grid;grid-template-columns:repeat(auto-fit, minmax(200px, 1fr));gap:var(--space-md);margin-bottom:var(--space-md)">
       <div class="config-card"><div class="config-label">Storage Mode</div><div class="config-value">${escHtml(data.storageMode || 'reference')}</div></div>
-      <div class="config-card"><div class="config-label">DB Size</div><div class="config-value">${escHtml(data.dbSize?.display || 'N/A')}</div></div>
+      <div class="config-card"><div class="config-label">DB Size</div><div class="config-value" id="dbSizeValue">${escHtml(data.dbSize?.display || 'N/A')}</div></div>
+    </div>
+    <div style="display:flex;gap:12px;align-items:center;flex-wrap:wrap;margin-bottom:var(--space-xl)">
+      <button class="export-btn" id="optimizeDbBtn">Optimize Database</button>
+      <span style="color:var(--text-tertiary);font-size:12px;line-height:1.5">Reclaims unused space and merges pending writes. Safe to run anytime, doesn't delete any data.</span>
+      <span id="optimizeDbStatus" style="color:var(--text-tertiary);font-size:12px"></span>
     </div>
 
     ${data.sessionDirs && data.sessionDirs.length ? (() => {
@@ -755,16 +915,35 @@ async function viewStats() {
     <div class="section-label">Date Range</div>
     <p style="color:var(--text-secondary);font-size:13px;margin-bottom:var(--space-xl)">${fmtDate(data.dateRange?.earliest)} \u2014 ${fmtDate(data.dateRange?.latest)}</p>
     <div class="section-label">Tools Used</div>
-    <div class="tools-grid">${(data.tools||[]).filter(t => t).sort().map(t => `<span class="tool-chip">${escHtml(t)}</span>`).join('')}</div>
+    <div class="tools-grid">${[...new Set((data.tools||[]).filter(t => t).map(t => fmtToolGroup(t)))].sort().map(t => `<span class="tool-chip">${escHtml(t)}</span>`).join('')}</div>
   `;
 
   content.innerHTML = html;
   transitionView();
+
+  const optimizeBtn = $('#optimizeDbBtn');
+  const optimizeStatus = $('#optimizeDbStatus');
+  if (optimizeBtn) {
+    optimizeBtn.addEventListener('click', async () => {
+      optimizeBtn.disabled = true;
+      optimizeStatus.textContent = 'Optimizing…';
+      const result = await api('/maintenance', { method: 'POST' });
+      if (result._error || !result.ok) {
+        optimizeStatus.textContent = `Failed: ${result.error || 'Unknown error'}`;
+      } else {
+        optimizeStatus.textContent = `${result.sizeBefore?.display || 'N/A'} → ${result.sizeAfter?.display || 'N/A'}`;
+        const dbSizeValue = $('#dbSizeValue');
+        if (dbSizeValue) dbSizeValue.textContent = result.sizeAfter?.display || 'N/A';
+      }
+      optimizeBtn.disabled = false;
+    });
+  }
 }
 
 async function viewFiles() {
   window._lastView = 'files';
-  content.innerHTML = '<div class="loading">Loading</div>';
+  content.innerHTML = `<div class="page-title">Files</div>${skeletonRows(6, 'file')}`;
+  transitionView();
   const data = await api('/files?limit=500');
   if (data._error) {
     content.innerHTML = '<div class="empty"><h2>Unable to load</h2><p>Server unavailable. Pull to refresh or try again.</p></div>';
@@ -964,6 +1143,8 @@ window._lastView = 'sessions';
 $$('.nav-item').forEach(item => {
   item.addEventListener('click', () => {
     if (window._sseCleanup) { window._sseCleanup(); window._sseCleanup = null; }
+    if (window._timelineScrollHandler) { window.removeEventListener('scroll', window._timelineScrollHandler); window._timelineScrollHandler = null; }
+    if (window._timelineSse) { window._timelineSse.close(); window._timelineSse = null; }
     const view = item.dataset.view;
     window._lastView = view;
     updateNavActive(view);
@@ -976,6 +1157,9 @@ $$('.nav-item').forEach(item => {
   });
 });
 
+initTheme();
+document.getElementById('theme-toggle')?.addEventListener('click', toggleTheme);
+document.getElementById('theme-toggle-mobile')?.addEventListener('click', toggleTheme);
 handleRoute();
 
 // Swipe right from left edge to go back

package/public/index.html

@@ -21,6 +21,7 @@
     <nav class="sidebar">
       <div class="sidebar-header">
         <h1>Agent<span>Acta</span></h1>
+        <button class="theme-toggle" id="theme-toggle" title="Toggle theme" aria-label="Toggle theme"><svg class="theme-icon-sun" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="5"/><path d="M12 1v2M12 21v2M4.22 4.22l1.42 1.42M18.36 18.36l1.42 1.42M1 12h2M21 12h2M4.22 19.78l1.42-1.42M18.36 5.64l1.42-1.42"/></svg><svg class="theme-icon-moon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/></svg></button>
       </div>
       <div class="nav-section">
         <div class="nav-item" data-view="sessions">
@@ -43,9 +44,12 @@
           <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M18 20V10M12 20V4M6 20v-6"/></svg>
           <span>Stats</span>
         </div>
+
       </div>
     </nav>
     <main class="main" id="content"></main>
+    <button class="theme-toggle-mobile" id="theme-toggle-mobile" title="Toggle theme" aria-label="Toggle theme"><svg class="theme-icon-sun" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="5"/><path d="M12 1v2M12 21v2M4.22 4.22l1.42 1.42M18.36 18.36l1.42 1.42M1 12h2M21 12h2M4.22 19.78l1.42-1.42M18.36 5.64l1.42-1.42"/></svg><svg class="theme-icon-moon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/></svg></button>
+
   </div>
   <script src="/app.js"></script>
   <script>

package/public/style.css

@@ -71,6 +71,47 @@
 
   /* Layout */
   --sidebar-width: 240px;
+  --input-scheme: dark;
+}
+
+[data-theme="light"] {
+  --bg-base: #f5f7fb;
+  --bg-surface: #ffffff;
+  --bg-elevated: #f8fafc;
+  --bg-hover: #eef2f7;
+  --bg-active: #e8edf6;
+
+  --border-subtle: rgba(15, 23, 42, 0.06);
+  --border-default: rgba(15, 23, 42, 0.1);
+  --border-hover: rgba(15, 23, 42, 0.16);
+  --border-focus: rgba(36, 89, 214, 0.45);
+
+  --text-primary: #111827;
+  --text-secondary: #5b6678;
+  --text-tertiary: #8793a7;
+  --text-inverse: #ffffff;
+
+  --accent: #2459d6;
+  --accent-soft: rgba(36, 89, 214, 0.12);
+  --accent-medium: rgba(36, 89, 214, 0.2);
+
+  --green: #158f69;
+  --green-soft: rgba(21, 143, 105, 0.12);
+
+  --purple: #7d62eb;
+  --purple-soft: rgba(125, 98, 235, 0.12);
+
+  --amber: #b7791f;
+  --amber-soft: rgba(183, 121, 31, 0.12);
+
+  --red: #c24141;
+  --red-soft: rgba(194, 65, 65, 0.12);
+
+  --teal: #0f9f9a;
+  --teal-soft: rgba(15, 159, 154, 0.12);
+
+  --shadow: 0 8px 24px rgba(15, 23, 42, 0.06);
+  --input-scheme: light;
 }
 
 /* ---- Reset ---- */
@@ -125,6 +166,10 @@ body {
 
 .sidebar-header {
   padding: var(--space-xl) var(--space-xl) var(--space-lg);
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--space-sm);
 }
 
 .sidebar h1 {
@@ -141,6 +186,63 @@ body {
   background-clip: text;
 }
 
+.theme-toggle {
+  width: 30px;
+  height: 30px;
+  border-radius: var(--radius-md);
+  border: 1px solid var(--border-default);
+  background: var(--bg-elevated);
+  color: var(--text-secondary);
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  cursor: pointer;
+  padding: 0;
+}
+
+.theme-toggle:hover {
+  background: var(--bg-hover);
+  color: var(--text-primary);
+}
+
+.theme-toggle svg,
+.theme-toggle-mobile svg {
+  width: 16px;
+  height: 16px;
+}
+
+.theme-icon-moon { display: none; }
+[data-theme="light"] .theme-icon-sun { display: none; }
+[data-theme="light"] .theme-icon-moon { display: block; }
+
+.theme-toggle-mobile {
+  display: none;
+  width: 32px;
+  height: 32px;
+  border-radius: var(--radius-md);
+  border: 1px solid var(--border-default);
+  background: var(--bg-surface);
+  color: var(--text-secondary);
+  align-items: center;
+  justify-content: center;
+  cursor: pointer;
+  padding: 0;
+  position: absolute;
+  top: calc(var(--space-xl) + env(safe-area-inset-top, 0px));
+  right: var(--space-lg);
+  z-index: 10;
+}
+
+.theme-toggle-mobile:hover {
+  background: var(--bg-hover);
+  color: var(--text-primary);
+}
+
+.theme-toggle-mobile svg {
+  width: 16px;
+  height: 16px;
+}
+
 .nav-section {
   display: flex;
   flex-direction: column;
@@ -203,7 +305,7 @@ body {
   flex: 1;
   margin-left: var(--sidebar-width);
   padding: var(--space-2xl) var(--space-3xl);
-  max-width: 1000px;
+  max-width: none;
   min-height: 100vh;
 }
 
@@ -655,6 +757,40 @@ mark {
   font-weight: 500;
 }
 
+/* ---- Skeletons ---- */
+.skeleton-card,
+.skeleton-row {
+  border-color: var(--border-subtle);
+}
+
+.skeleton-line {
+  position: relative;
+  border-radius: var(--radius-sm);
+  background: var(--bg-elevated);
+  border: 1px solid var(--border-subtle);
+  overflow: hidden;
+}
+
+.skeleton-line::after {
+  content: '';
+  position: absolute;
+  inset: 0;
+  transform: translateX(-100%);
+  background: linear-gradient(90deg, transparent, var(--bg-hover), transparent);
+  animation: skeletonShimmer 1.4s ease-in-out infinite;
+}
+
+@keyframes skeletonShimmer {
+  100% { transform: translateX(100%); }
+}
+
+.loading-more {
+  text-align: center;
+  color: var(--text-tertiary);
+  font-size: 12px;
+  padding: var(--space-md) 0;
+}
+
 @keyframes pulse {
   0%, 100% { opacity: 0.4; }
   50% { opacity: 1; }
@@ -683,7 +819,7 @@ mark {
   outline: none;
   margin-bottom: var(--space-lg);
   transition: all var(--duration-normal) var(--ease-out);
-  color-scheme: dark;
+  color-scheme: var(--input-scheme);
 }
 
 .date-input:hover {
@@ -1230,6 +1366,10 @@ mark {
 
   .sidebar-header { display: none; }
 
+  .theme-toggle-mobile {
+    display: flex;
+  }
+
   .nav-section {
     display: flex;
     flex-direction: row;