ai.log

See what your AI actually did.

A local-first activity log for AI coding agents. Every file read, every command run, every failure — recorded honestly, kept on your machine, never sent anywhere.

Claude Code · Codex · OpenCode · Gemini CLI · Cursor · Aider · Cline

Your AI pair programmer works fast. Do you know what it actually touched?

ai.log answers that question. It watches your project while Claude Code, Codex, OpenCode, Gemini CLI, Cursor, Aider, or Cline work, and records what happened — files read, files written, commands run, tests that failed, dependencies that changed, and anything that looks dangerous. Then it shows you a calm, readable timeline.

$ ai.log
──────────────────────────────────────────────
Session            alog_1m2e563w1x6k0a4f54655245
Started            11:05:56
Duration           42 min
Summary            128 command, 56 filesystem, 3 test, 1 security

11:07:12  CLAUDE    WRITE   src/hooks/useAuth.ts
11:08:01  CODEX     EXECUTE npm run build
11:08:03  SYSTEM    FAIL    npm run build (exit 1)
11:08:31  CLAUDE    WRITE   src/lib/api.ts
11:09:02  CLAUDE    EXECUTE curl https://api.stripe.com/v1 --token=[REDACTED]
11:09:12  SECURITY  SENSITIVE-COMMAND   [medium]

100% local. Zero telemetry. Zero cloud. Zero bullshit.

✨ Highlights

• 🔍 Sees the real thing — reads agent hook streams (PostToolUse, SessionStart, …) instead of guessing from process names
• 🕵️ Honest by design — every event carries a confidence score and an observed flag. Inferred activity is never presented as fact
• 🔐 Secrets never leak — --token=ghp_x, AWS_SECRET_ACCESS_KEY=…, ?api_key=… are redacted to [REDACTED] before they touch disk
• 🛡️ Danger radar — surfaces sudo, rm -rf, credential files, and network calls with a risk level (low → critical)
• 📦 Local-first — SQLite + JSONL in .ailog/, git-ignored by default
• 🧩 Drop-in — installs non-destructive hooks into your agents' configs; re-runnable, reversible, preserves your existing settings
• 📊 Git-aware — tracks branch/HEAD per session, watches dependency manifests across ecosystems (npm, pnpm, yarn, Go, Cargo, Python, PHP, Ruby) for installs/updates/removals

🚀 Quick start

Requires Node.js ≥ 18:

npm install -g ai.log-cli

Then, in any project you work on with an AI agent:

cd my-project

ai.log init     # one-time: creates .ailog/ + installs agent hooks
ai.log start    # start recording (background daemon)

# ... use Claude Code, Codex, OpenCode, Gemini CLI, Cursor, Aider, Cline ...

ai.log          # see what your agents did
ai.log --security  # anything risky?
ai.log stop     # stop recording

That's it. ai.log on its own shows the current session's timeline; the --changes, --commands, --errors, and --security flags give you focused views.

📖 Commands

| Command | Description | |---|---| | ai.log init | Initialize ai.log in the current workspace | | ai.log start | Start recording a session (background daemon) | | ai.log stop | Stop recording the current session | | ai.log status | Show daemon, session, and event state | | ai.log | Show the latest session activity | | ai.log --changes | Show file changes during the session | | ai.log --commands | Show executed commands | | ai.log --errors | Show failures | | ai.log --security | Show potentially sensitive activity | | ai.log --json | Dump raw normalized events as JSON | | ai.log replay | Full chronological session timeline (exit codes, gaps) | | ai.log report | Daily / weekly activity summary (--period daily\|weekly\|all) | | ai.log undo | Revert what an agent changed during a session (--yes) | | ai.log clear | Delete all recorded history (asks for confirmation, or --yes) | | ai.log install | Re-install agent hooks (non-destructive merge) | | ai.log export | Export session(s) as Markdown / JSON / HTML (--format, --output, --all) | | ai.log watch | Live tail of agent activity as it happens | | ai.log stats | Compare sessions / per-actor productivity across all sessions | | ai.log risks | Cross-session risk-pattern detection | | ai.log review | Flag unreviewed (uncommitted) agent changes | | ai.log hook | Install a git pre-commit reviewer (--remove to uninstall) | | ai.log policy | CI gate / alert on sensitive activity (--gate) | | ai.log cost | Rough token / API-cost estimate per session | | ai.log web | Local web viewer — dashboard over the SQLite store (--port, --host, --open) | | ai.log diff | Git diff of what an agent changed in a session (--stat) | | ai.log search | Search activity by text / actor / category / risk (--text, --actor, --category, --risk, --all) | | ai.log agents | List agents and their hook-install status | | ai.log config | Print (or --get <key>) the resolved configuration | | ai.log audit | Tamper-evident compliance/audit export (--format, --output, --all) | | ai.log rollup | Team-wide rollup across many projects (--root, --depth) | | ai.log alert | Watch for risky activity; desktop-notify the moment it happens (--history, --since, --risk) | | ai.log summary | Natural-language digest of what agents did (standup/PR ready, --json) | | ai.log tag | Label sessions with tags (--add, --untag, --filter, --list) | | ai.log prune | Retention housekeeping (--keep <n> / --older-than <days>, --dry-run) | | ai.log compare | Side-by-side comparison of two sessions (--session, --with) | | ai.log event <id> | Inspect a single event — raw JSON plus readable fields (--json) | | ai.log blame <file\|glob> | Who touched a file, and when — agent git blame (--json) | | ai.log heatmap | GitHub-style contribution heatmap of activity (--days <n>, --session, --json) | | ai.log doctor | Diagnose the local install: db integrity, daemon, inbox backlog (--fix to VACUUM) | | ai.log query | Structured search (--action, --actor, --category, --risk, --file <glob>, --since, --until) | | ai.log --help / --version | Help / version |

Options: --session <id> target a specific session, --limit <n> cap events, --period <daily\|weekly> report period, --yes skip confirmation prompts.

Going deeper

ai.log replay                 # full timeline with exit codes + gaps
ai.log report --period weekly # last week, per actor/category
ai.log report --period daily --json
ai.log undo                   # preview: what the session changed
ai.log undo --yes             # revert modified/deleted files, drop created ones
ai.log undo --session alog_1m2e563w1x6k0a4f54655245
ai.log alert                  # get notified the moment a risky action happens
ai.log alert --history        # replay every past high/critical event
ai.log summary                # standup-ready prose digest of the session
ai.log tag --add feature-auth # label the current session's workstream
ai.log tag --filter feature-auth  # find all sessions in that workstream
ai.log prune --keep 10 --yes  # keep only the 10 most recent sessions
ai.log compare                # side-by-side view of the two latest sessions
ai.log event alog_1m2e563w1x6k0a4f54655245   # inspect one event in depth
ai.log blame src/index.ts     # who touched src/index.ts, and when
ai.log heatmap --days 90      # three months of activity as a heatmap
ai.log doctor --fix           # health-check the install and repair
ai.log query --category filesystem --risk high --file 'src/**/*.ts'

ai.log undo restores the exact files an agent touched during a session back to the git commit recorded when the session started — it never touches .ailog, never rewrites history, and previews every change before asking for confirmation.

🔎 How it works

┌─────────────── agent hooks (observed) ───────────────┐
│  Claude Code   .claude/settings.json                  │
│  Codex         .codex/hooks.json                      │
│  Gemini CLI    .gemini/settings.json                  │
│  OpenCode      .opencode/plugin/ailog.js              │
│  Cursor        .cursor/settings.json                  │
│  Cline         .cline/settings.json                   │
└───────────────────────┬──────────────────────────────┘
                        │ JSONL, one line per event
                        ▼
              .ailog/inbox/<agent>.jsonl
                        │
        ┌───────────────┴────────────────┐
        │          daemon (tail)         │
        │  ┌─────────────────────────┐   │
        │  │  attribution engine     │   │
        │  │  • normalize payload    │   │
        │  │  • attach session/repo  │   │
        │  │  • redact secrets       │   │
        │  └───────────┬─────────────┘   │
        │              ▼                 │
        │  security scanner ──► derived security events
        │  dependency tracker ─► install/update/remove events
        │  failure detector ───► test pass/fail events
        │              ▼                 │
        │        SQLite (WAL)            │
        └───────────────┬────────────────┘
                        ▼
              ai.log ──► readable timeline

Three signal sources

| Source | Example | Confidence | |---|---|---| | Agent hooks (observed) | Claude reports PostToolUse: Write src/foo.ts | 0.93 – 0.97 | | Filesystem watcher (inferred) | a file changed near an agent's recent work | 0.25 – 0.85 | | Process poller (inferred) | a claude process is running | 0.5 |

Hooks are the ground truth. The watcher and process poller only fill gaps, and they always say so: lower confidence, observed: false, and an explicit metadata.inferred: true.

🔐 Security model

This is the part we care about most. Your AI's commands can contain real secrets — tokens, keys, passwords — and a naive logger would happily write them to disk.

ai.log doesn't.

1. Redact before disk. Payloads are redacted the moment they're ingested — before a single byte is written to .ailog/inbox/. Key-based flags (--token=…), env assignments (AWS_SECRET_ACCESS_KEY=…), auth headers (Authorization: Bearer …), and secret URL query params (?api_key=…) all become [REDACTED]. The redaction is idempotent — re-reading an already redacted line changes nothing.
2. Sanitize everything. ANSI escapes and control characters are stripped; metadata and targets are size-capped.
3. Parameterized SQL only. No string-built queries, ever.
4. Least privilege. The daemon runs as your user, detached, writing only to the project's .ailog/ directory. Hooks run a single append-only command that never blocks or alters the agent.
5. Risk radar. ai.log --security flags sensitive-file access (.env, .ssh, *.pem, credentials files), dangerous commands (sudo, rm -rf, chmod, git reset --hard, DROP DATABASE, …), and network commands (curl, wget, ssh, scp, nc, …) — each with a risk level.

Everything stays in .ailog/ (SQLite + JSONL), which ai.log init adds to .gitignore automatically. There is no cloud, no telemetry, no analytics.

⚙️ Configuration

.ailog/config.json is created by ai.log init. Everything is optional — missing fields fall back to defaults:

{
  // Agents to install hooks for (on init / install)
  "agents": {
    "claude": true,
    "codex": true,
    "opencode": true,
    "gemini": true,
    "cursor": true,
    "aider": true,
    "cline": true
  },
  // Paths the filesystem watcher never records
  "ignore": [
    "node_modules", ".git", "dist", "build", "coverage", ".ailog",
    ".cache", "tmp", ".venv", "venv", "__pycache__",
    ".turbo", ".svelte-kit", ".gradle", ".idea", ".vscode"
  ],
  // Security scanning toggles
  "security": {
    "detectSecrets": true,
    "detectDangerousCommands": true,
    "detectNetworkCommands": true
  }
}

Aider has no native hook system, so it is captured via process polling (inferred, confidence 0.5) rather than hook events. Disable any agent by setting its flag to false — it will not be watched or installed.

Re-run hook installation anytime with ai.log install — it merges non-destructively, so your own agent settings and custom hooks are preserved.

🧠 Design principles

• Honesty over inference. Observed events and inferred events are never conflated. If ai.log didn't see it, it says so.
• Never disturb the agent. Hooks are append-only, best-effort, silent. A failure in ai.log can never break your agent's workflow.
• Local-first. Your activity log is yours. Deleting .ailog/ deletes everything — no remote copies, no sync, no analytics.
• Defense in depth. Redaction happens at ingest and at read-back; sanitization happens at the adapter layer and in the pipeline.

🛠️ Development

npm install
npm run build      # tsc (strict)
npm test           # node --test tests/
npm run typecheck  # tsc --noEmit

# try it in a throwaway project
mkdir /tmp/demo && cd /tmp/demo
node /path/to/ai.log/dist/cli/index.js init
node /path/to/ai.log/dist/cli/index.js start
# ... use an agent ...
node /path/to/ai.log/dist/cli/index.js
node /path/to/ai.log/dist/cli/index.js stop

🗺️ Roadmap

Shipped

• [x] Publish to npm (ai.log-cli)
• [x] ai.log undo — diff/revert what an agent changed
• [x] Session replay with full command/exit timeline
• [x] Support more agents (Aider, Cursor, Cline, …)
• [x] ai.log report — daily/weekly summaries for standups
• [x] Dependency manifests beyond package.json (pnpm, yarn, Go, Cargo)

Proposed / in progress

• [ ] ai.log undo — support non-Git working trees
• [ ] Session replay — interactive player (TUI)
• [ ] More agents (Cody, Zed, Windsurf, …)
• [x] ai.log export — Markdown / JSON / HTML export for standups & sharing
• [x] ai.log watch — live tail of agent activity as it happens
• [x] ai.log stats — compare sessions / per-actor productivity across all sessions
• [x] ai.log risks — cross-session risk-pattern detection
• [x] ai.log review — flag unreviewed (uncommitted) agent changes
• [x] ai.log hook — install a git pre-commit reviewer
• [x] ai.log policy — CI gate / alert on sensitive activity
• [x] ai.log cost — rough token / API-cost estimate per session
• [x] Local web viewer (static server over SQLite) — ai.log web
• [x] ai.log alert — real-time risk alerts with OS desktop notifications
• [x] ai.log summary — natural-language digest of a session
• [x] ai.log tag — label sessions with tags for filtering/organization
• [x] ai.log prune — retention housekeeping (keep N / older than X days)
• [x] ai.log compare — side-by-side two-session comparison, with stats + filters
• [x] ai.log diff — git diff of agent changes in a session
• [x] ai.log search — search by text / actor / category / risk
• [x] ai.log agents — list agents and hook-install status
• [x] ai.log config — print / --get resolved configuration
• [x] ai.log event — inspect a single event in depth (raw JSON + readable fields)
• [x] ai.log blame — per-file attribution timeline (agent git blame)
• [x] ai.log heatmap — GitHub-style per-day contribution heatmap
• [x] ai.log doctor — local install diagnostics (db integrity, daemon, inbox backlog, --fix)
• [x] ai.log query — structured, filter-stack search incl. glob file matching

Enterprise / business (open-core path)

• [x] ai.log audit — tamper-evident (SHA-256 hash chain) compliance/audit export for SOC2/GDPR
• [x] ai.log rollup — team-wide rollup across many projects (multi-.ailog scan)
• [x] ai.log cost --budget — cost governance: budgets per run + --alert gate
• [x] ai.log policy --webhook — stream findings to a webhook / Slack for alerting

Proposed / in progress

• [ ] ai.log undo — support non-Git working trees
• [ ] Session replay — interactive player (TUI)
• [ ] More agents (Cody, Zed, Windsurf, …)
• [ ] Cloud/team tier — shared dashboard, cross-project analytics, managed alerting
• [ ] Adapter plugin marketplace (community agents without forking) — needs architecture work

🤝 Contributing

PRs are welcome! Keep the core principles in mind:

• New agents = new adapter (pure function: payload → event | null)
• Never block or disturb the agent loop
• Keep redaction idempotent and shape-preserving
• Tests live in tests/ and run against dist/

ai.log — see what your AI did.

Built with TypeScript, SQLite, and an unhealthy amount of curiosity.

License: MIT