agentacta 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Miraj Chokshi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,216 @@
+# AgentActa
+
+[![CI](https://github.com/mirajchokshi/agentacta/actions/workflows/ci.yml/badge.svg)](https://github.com/mirajchokshi/agentacta/actions/workflows/ci.yml)
+[![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?**
+
+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.
+
+One command. Zero config. Full visibility.
+
+```bash
+npx agentacta
+```
+
+---
+
+## Why
+
+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).
+
+AgentActa gives you a single, searchable view of everything.
+
+## 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
+
+## Demo
+
+https://github.com/mirajchokshi/agentacta/raw/main/screenshots/demo-final.mp4
+
+## Screenshots
+
+![Search](screenshots/search.png)
+![Sessions](screenshots/sessions.png)
+![Session Detail](screenshots/session-detail.png)
+![Timeline](screenshots/timeline.png)
+![Files](screenshots/files.png)
+![Stats](screenshots/stats.png)
+![Search Results](screenshots/search-results.png)
+
+## Quick Start
+
+```bash
+# Run directly (no install needed)
+npx agentacta
+
+# Or install globally
+npm install -g agentacta
+agentacta
+```
+
+Open `http://localhost:4003` in your browser.
+
+AgentActa automatically finds your sessions in:
+- `~/.openclaw/agents/*/sessions/` (OpenClaw)
+- `~/.claude/projects/*/sessions/` (Claude Code)
+
+Or point it at a custom path:
+
+```bash
+AGENTACTA_SESSIONS_PATH=/path/to/sessions agentacta
+```
+
+## 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.
+
+### Sessions
+Browse all indexed sessions with auto-generated summaries, token breakdowns (output vs input), and model info. Click into any session to see the full event history, most recent first.
+
+### Timeline
+Pick a date, see everything that happened. Messages, tool invocations, file changes — most recent first.
+
+### 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.
+
+### Export
+Download any session or search results as Markdown or JSON. Great for sharing, auditing, or archiving.
+
+## How It Works
+
+AgentActa reads JSONL session files (the standard format used by OpenClaw and Claude Code), parses every message and tool call, and indexes them into a local SQLite database with FTS5 full-text search.
+
+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`.
+
+```
+Session JSONL files → SQLite + FTS5 index → HTTP API → Web UI
+```
+
+Data never leaves your machine.
+
+## Configuration
+
+On first run, AgentActa creates `agentacta.config.json` with sensible defaults:
+
+```json
+{
+  "port": 4003,
+  "storage": "reference",
+  "sessionDirs": []
+}
+```
+
+### 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.
+
+### 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`) |
+
+## 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/export/search?q=<query>&format=md` | Export search results |
+
+### Agent Integration
+
+Your AI agent can query AgentActa for better recall:
+
+```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
+```
+
+### Demo Mode
+
+Want to see what AgentActa looks like with data? Run with demo sessions:
+
+```bash
+# Generate demo data and start in demo mode
+npm run demo
+
+# Or separately:
+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.
+
+## Security
+
+**AgentActa is a local tool.** It binds to `127.0.0.1` by default — only accessible from your machine.
+
+To expose on your network (e.g., for Tailscale access):
+
+```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.
+
+## 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
+
+## Privacy
+
+All data stays local. AgentActa runs entirely on your machine — no cloud services, no telemetry, no external requests. Your agent history is yours.
+
+## Compatibility
+
+- ✅ [OpenClaw](https://github.com/openclaw/openclaw)
+- ✅ Claude Code
+- 🔜 Codex CLI
+- 🔜 Custom JSONL formats
+
+## Contributing
+
+PRs welcome. If you're adding support for a new agent format, add a parser in `indexer.js` and open a PR.
+
+## Etymology
+
+*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.
+
+AgentActa is the same idea: a complete, searchable record of everything your AI agent did.
+
+## License
+
+MIT
+
+---
+
+Built in Chicago by humans and agents working together.

package/config.js

@@ -0,0 +1,55 @@
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const CWD_CONFIG_FILE = path.join(process.cwd(), 'agentacta.config.json');
+const XDG_CONFIG_DIR = path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'agentacta');
+const XDG_CONFIG_FILE = path.join(XDG_CONFIG_DIR, 'config.json');
+
+// Resolve config file: CWD first (backward compat), then XDG default
+function resolveConfigFile() {
+  if (fs.existsSync(CWD_CONFIG_FILE)) return CWD_CONFIG_FILE;
+  return XDG_CONFIG_FILE;
+}
+
+const CONFIG_FILE = resolveConfigFile();
+
+const DEFAULTS = {
+  port: 4003,
+  storage: 'reference',
+  sessionsPath: null,
+  dbPath: './agentacta.db'
+};
+
+function loadConfig() {
+  let fileConfig = {};
+
+  if (fs.existsSync(CONFIG_FILE)) {
+    try {
+      fileConfig = JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+    } catch (err) {
+      console.error(`Warning: Could not parse ${CONFIG_FILE}:`, err.message);
+    }
+  } else {
+    // First-run: create default config in XDG location
+    const dir = path.dirname(CONFIG_FILE);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(CONFIG_FILE, JSON.stringify(DEFAULTS, null, 2) + '\n');
+    console.log(`Created default config: ${CONFIG_FILE}`);
+  }
+
+  const config = { ...DEFAULTS, ...fileConfig };
+
+  // Env var overrides (highest priority)
+  if (process.env.PORT) config.port = parseInt(process.env.PORT);
+  if (process.env.AGENTACTA_STORAGE) config.storage = process.env.AGENTACTA_STORAGE;
+  if (process.env.AGENTACTA_SESSIONS_PATH) config.sessionsPath = process.env.AGENTACTA_SESSIONS_PATH;
+  if (process.env.AGENTACTA_DB_PATH) config.dbPath = process.env.AGENTACTA_DB_PATH;
+
+  // Resolve dbPath relative to cwd
+  config.dbPath = path.resolve(config.dbPath);
+
+  return config;
+}
+
+module.exports = { loadConfig, CONFIG_FILE };

package/db.js

@@ -0,0 +1,137 @@
+const Database = require('better-sqlite3');
+const path = require('path');
+const { loadConfig } = require('./config');
+
+let _config = null;
+function getConfig() {
+  if (!_config) _config = loadConfig();
+  return _config;
+}
+
+function open(dbPath) {
+  const p = dbPath || getConfig().dbPath;
+  const db = new Database(p);
+  db.pragma('journal_mode = WAL');
+  db.pragma('foreign_keys = ON');
+  return db;
+}
+
+function init(dbPath) {
+  const db = open(dbPath);
+
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS sessions (
+      id TEXT PRIMARY KEY,
+      start_time TEXT NOT NULL,
+      end_time TEXT,
+      message_count INTEGER DEFAULT 0,
+      tool_count INTEGER DEFAULT 0,
+      model TEXT,
+      summary TEXT,
+      agent TEXT,
+      session_type TEXT,
+      total_cost REAL DEFAULT 0,
+      total_tokens INTEGER DEFAULT 0,
+      input_tokens INTEGER DEFAULT 0,
+      output_tokens INTEGER DEFAULT 0,
+      cache_read_tokens INTEGER DEFAULT 0,
+      cache_write_tokens INTEGER DEFAULT 0,
+      initial_prompt TEXT,
+      first_message_id TEXT,
+      first_message_timestamp TEXT
+    );
+
+    CREATE TABLE IF NOT EXISTS events (
+      id TEXT PRIMARY KEY,
+      session_id TEXT NOT NULL,
+      timestamp TEXT NOT NULL,
+      type TEXT NOT NULL,
+      role TEXT,
+      content TEXT,
+      tool_name TEXT,
+      tool_args TEXT,
+      tool_result TEXT,
+      FOREIGN KEY (session_id) REFERENCES sessions(id) ON DELETE CASCADE
+    );
+
+    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);
+    CREATE INDEX IF NOT EXISTS idx_events_tool_name ON events(tool_name);
+
+    CREATE VIRTUAL TABLE IF NOT EXISTS events_fts USING fts5(
+      content, tool_name, tool_args,
+      content='events',
+      content_rowid='rowid'
+    );
+
+    CREATE TRIGGER IF NOT EXISTS events_ai AFTER INSERT ON events BEGIN
+      INSERT INTO events_fts(rowid, content, tool_name, tool_args)
+      VALUES (new.rowid, new.content, new.tool_name, new.tool_args);
+    END;
+
+    CREATE TRIGGER IF NOT EXISTS events_ad AFTER DELETE ON events BEGIN
+      INSERT INTO events_fts(events_fts, rowid, content, tool_name, tool_args)
+      VALUES ('delete', old.rowid, old.content, old.tool_name, old.tool_args);
+    END;
+
+    CREATE TABLE IF NOT EXISTS index_state (
+      file_path TEXT PRIMARY KEY,
+      last_offset INTEGER DEFAULT 0,
+      last_modified TEXT
+    );
+
+    CREATE TABLE IF NOT EXISTS file_activity (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      session_id TEXT NOT NULL,
+      file_path TEXT NOT NULL,
+      operation TEXT NOT NULL,
+      timestamp TEXT,
+      FOREIGN KEY (session_id) REFERENCES sessions(id) ON DELETE CASCADE
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_file_activity_path ON file_activity(file_path);
+    CREATE INDEX IF NOT EXISTS idx_file_activity_session ON file_activity(session_id);
+
+    CREATE TABLE IF NOT EXISTS archive (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      session_id TEXT NOT NULL,
+      line_number INTEGER NOT NULL,
+      raw_json TEXT NOT NULL,
+      FOREIGN KEY (session_id) REFERENCES sessions(id) ON DELETE CASCADE
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_archive_session ON archive(session_id);
+  `);
+
+  // Add columns if missing (migration)
+  const cols = db.prepare("PRAGMA table_info(sessions)").all().map(c => c.name);
+  if (!cols.includes('agent')) db.exec("ALTER TABLE sessions ADD COLUMN agent TEXT");
+  if (!cols.includes('session_type')) db.exec("ALTER TABLE sessions ADD COLUMN session_type TEXT");
+  if (!cols.includes('total_cost')) db.exec("ALTER TABLE sessions ADD COLUMN total_cost REAL DEFAULT 0");
+  if (!cols.includes('total_tokens')) db.exec("ALTER TABLE sessions ADD COLUMN total_tokens INTEGER DEFAULT 0");
+  if (!cols.includes('input_tokens')) db.exec("ALTER TABLE sessions ADD COLUMN input_tokens INTEGER DEFAULT 0");
+  if (!cols.includes('output_tokens')) db.exec("ALTER TABLE sessions ADD COLUMN output_tokens INTEGER DEFAULT 0");
+  if (!cols.includes('cache_read_tokens')) db.exec("ALTER TABLE sessions ADD COLUMN cache_read_tokens INTEGER DEFAULT 0");
+  if (!cols.includes('cache_write_tokens')) db.exec("ALTER TABLE sessions ADD COLUMN cache_write_tokens INTEGER DEFAULT 0");
+
+  db.close();
+}
+
+function createStmts(db) {
+  return {
+    getState: db.prepare('SELECT * FROM index_state WHERE file_path = ?'),
+    getSession: db.prepare('SELECT id FROM sessions WHERE id = ?'),
+    deleteEvents: db.prepare('DELETE FROM events WHERE session_id = ?'),
+    deleteSession: db.prepare('DELETE FROM sessions WHERE id = ?'),
+    deleteFileActivity: db.prepare('DELETE FROM file_activity WHERE session_id = ?'),
+    insertEvent: db.prepare(`INSERT OR REPLACE INTO events (id, session_id, timestamp, type, role, content, tool_name, tool_args, tool_result) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`),
+    upsertSession: db.prepare(`INSERT OR REPLACE INTO sessions (id, start_time, end_time, message_count, tool_count, model, summary, agent, session_type, total_cost, total_tokens, input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, initial_prompt, first_message_id, first_message_timestamp) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`),
+    upsertState: db.prepare(`INSERT OR REPLACE INTO index_state (file_path, last_offset, last_modified) VALUES (?, ?, ?)`),
+    insertFileActivity: db.prepare(`INSERT INTO file_activity (session_id, file_path, operation, timestamp) VALUES (?, ?, ?, ?)`),
+    deleteArchive: db.prepare('DELETE FROM archive WHERE session_id = ?'),
+    insertArchive: db.prepare('INSERT INTO archive (session_id, line_number, raw_json) VALUES (?, ?, ?)')
+  };
+}
+
+module.exports = { open, init, createStmts };