agentel 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brian Zhou
+
+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,452 @@
+# agentlog
+
+Local-first archive and recall for agent coding sessions.
+
+Core capabilities:
+
+- raw source-file backup before normalization, so provider history can be
+  re-parsed later
+- markdown-primary, redacted local archive under `~/.agentlog/data/agentlog/`
+- canonical event JSONL alongside each transcript for provider-independent search
+- canonical repo keying from git remotes, first commits, or path hashes
+- Codex CLI, Codex Desktop, ChatGPT export, Claude Code CLI, Claude Code
+  Desktop, Claude Workspace, Claude.ai export, Gemini CLI, Antigravity,
+  Devin CLI, and Cursor imports
+- event-first `agentlog history` search with markdown/transcript fallback
+- `agentlog-recall` MCP stdio server exposing `search_past_sessions`
+- installable recall commands, workflows, skills, and MCP hooks for common
+  coding agents
+- local web viewer for full conversation history inspection
+- device-scoped S3-compatible upload sync for backup and future multi-device recall
+- lifecycle, config, autostart, and MCP config helper commands
+- local reset command for starting init from a clean archive/config state
+
+The local HTTP OTLP collector, S3-compatible remote sync, and team deployment
+surfaces are configurable extension points for environments that install those
+services.
+
+## Install
+
+Install the CLI globally so agent-facing recall commands can call `agentlog`
+from PATH:
+
+```sh
+npm install -g agentlogs
+agentlog init
+```
+
+You can also install directly from the GitHub repository. Use a tag or commit
+ref for repeatable installs:
+
+```sh
+npm install -g brianlzhou/agentlog
+# or
+npm install -g brianlzhou/agentlog#v0.2.0
+agentlog init
+```
+
+You can also install it into a project and run it through npm/npx:
+
+```sh
+npm install agentlogs
+npx agentlogs init
+```
+
+Or run the published package without keeping a local install:
+
+```sh
+npx agentlogs init
+```
+
+Requirements:
+
+- Node.js 20 or newer
+- `sqlite3` for Codex, Cursor, and Devin local database imports
+- `rg`/ripgrep for faster history search
+- `unzip` for ZIP web exports
+- `zstd` or `unzstd` for compressed Codex session files
+
+Run `agentlog doctor` after install to check optional tools and configured
+sources.
+
+## Try From Source
+
+```sh
+npm install
+npm test
+AGENTLOG_HOME=/tmp/agentlog-demo node ./bin/agentlog.js init --yes --skip-import --no-autostart --no-claude --no-recall --no-telemetry
+AGENTLOG_HOME=/tmp/agentlog-demo node ./bin/agentlog.js import --source codex-cli --since 30d
+AGENTLOG_HOME=/tmp/agentlog-demo node ./bin/agentlog.js import --source codex-desktop --since all
+AGENTLOG_HOME=/tmp/agentlog-demo node ./bin/agentlog.js import chatgpt ~/Downloads/chatgpt-export.zip --username you@example.com
+AGENTLOG_HOME=/tmp/agentlog-demo node ./bin/agentlog.js import claude-web ~/Downloads/claude-export --username you --display-name "Personal Claude"
+AGENTLOG_HOME=/tmp/agentlog-demo node ./bin/agentlog.js import --source claude --since 30d
+AGENTLOG_HOME=/tmp/agentlog-demo node ./bin/agentlog.js import --source claude-code-desktop --since all
+AGENTLOG_HOME=/tmp/agentlog-demo node ./bin/agentlog.js import --source claude-workspace --since all
+AGENTLOG_HOME=/tmp/agentlog-demo node ./bin/agentlog.js import --source gemini-cli --since all
+AGENTLOG_HOME=/tmp/agentlog-demo node ./bin/agentlog.js import --source antigravity --since all
+AGENTLOG_HOME=/tmp/agentlog-demo node ./bin/agentlog.js import --source devin-cli --since all
+AGENTLOG_HOME=/tmp/agentlog-demo node ./bin/agentlog.js import --source cursor --since all
+AGENTLOG_HOME=/tmp/agentlog-demo node ./bin/agentlog.js import --source cline --since all
+AGENTLOG_HOME=/tmp/agentlog-demo node ./bin/agentlog.js import --source opencode --since all
+AGENTLOG_HOME=/tmp/agentlog-demo node ./bin/agentlog.js import --source aider --since all
+AGENTLOG_HOME=/tmp/agentlog-demo node ./bin/agentlog.js history "database migration issue"
+AGENTLOG_HOME=/tmp/agentlog-demo node ./bin/agentlog.js reset --yes
+```
+
+Use `AGENTLOG_HOME=/tmp/agentlog-demo` to test without touching the default
+`~/.agentlog` directory. The `--no-autostart --no-claude --no-recall --no-telemetry`
+flags avoid editing launch-agent, Claude, Codex, Gemini, or Cline settings while
+running from source.
+
+Install the source checkout globally while developing:
+
+```sh
+npm install -g .
+# or, while developing from this repo:
+npm link
+```
+
+Then run:
+
+```sh
+agentlog init
+```
+
+Before publishing a release, run:
+
+```sh
+npm run check
+npm test
+npm run pack:dry
+npm run smoke:pack
+```
+
+## Recall
+
+```sh
+agentlog recall add-to codex
+agentlog recall add-to claude
+agentlog recall add-to gemini
+agentlog recall add-to antigravity
+agentlog recall add-to devin
+agentlog recall add-to cursor
+agentlog recall add-to cline
+agentlog recall add-to opencode
+agentlog recall add-to aider
+```
+
+`recall add-to codex` installs the MCP server plus a Codex recall skill.
+`recall add-to claude` installs the MCP server plus a Claude `/recall`
+command plus a Claude skill under `~/.claude/skills/agentlog-recall/SKILL.md`.
+`recall add-to gemini` installs the MCP server plus a Gemini `/recall` command
+under `~/.gemini/commands/recall.toml`.
+
+Additional native surfaces are installed where the client exposes one:
+
+| Agent | Recall surface |
+| --- | --- |
+| Antigravity | MCP config in `~/.gemini/antigravity/mcp_config.json` plus an Agent Skill at `~/.gemini/antigravity/skills/recall/SKILL.md` |
+| Devin | MCP config in `~/.config/devin/config.json` plus `/recall` skill at `~/.config/devin/skills/recall/SKILL.md` |
+| Cursor | MCP config in `~/.cursor/mcp.json` plus project files `.cursor/commands/recall.md` and `.cursor/rules/agentlog-recall.mdc` |
+| Cline | MCP config in `~/.cline/data/settings/cline_mcp_settings.json` plus `/recall.md` workflow at `~/Documents/Cline/Workflows/recall.md` |
+| OpenCode | MCP config in `~/.config/opencode/opencode.json` plus `/recall` command at `~/.config/opencode/commands/recall.md` |
+| Aider | Loadable recall instructions under `~/.agentlog/aider/`; Aider does not expose a documented custom slash-command registry, so load them with `/load ~/.agentlog/aider/load-recall.aider` or configure the generated markdown as `read:` in `.aider.conf.yml` |
+
+The generated recall files use a skill-style layout with command tables,
+workflow steps, query-selection guidance, archive layout notes, and
+troubleshooting. They ask the agent to infer a focused search query, then call
+`agentlog history` and `agentlog show`, so agents do not need direct filesystem
+access to `~/.agentlog`. Users can ask for context naturally, such as `/recall
+the migration bug and update the test`.
+
+Skill/command files can also be installed directly:
+
+```sh
+agentlog recall install-skill codex
+agentlog recall install-skill claude
+agentlog recall install-skill gemini
+agentlog recall install-skill antigravity
+agentlog recall install-skill devin
+agentlog recall install-skill cursor
+agentlog recall install-skill cline
+agentlog recall install-skill opencode
+agentlog recall install-skill aider
+```
+
+The standalone MCP binary remains available for clients that only need the
+tool server:
+
+```sh
+agentlog-recall
+```
+
+## Daily CLI
+
+`agentlog status`, `agentlog history`, `agentlog show`, `agentlog import`, `agentlog index`, and
+`agentlog autostart` use styled human-readable output by default. Use `--json`
+on `status`, `history`, and import status/results for script-friendly
+structured output. `agentlog status` includes the most recently archived
+conversation threads and the sources currently monitored by the supervisor;
+`agentlog history` is for search and recall.
+
+Useful history commands:
+
+```sh
+agentlog history
+agentlog history "codebase explanation" --provider codex-cli --limit 10
+agentlog history --repo github.com/acme/widgets --since 90d
+agentlog show <session-id>
+agentlog show <session-id> --path
+agentlog history --web
+agentlog history --web --no-open
+```
+
+`agentlog history --web` starts the local conversation viewer and opens it in
+your default browser. Use `--no-open` when you only want to print the local URL
+and keep the server running. The left rail is a
+repo tree sorted by the latest updated session, each folder pages through
+sessions with a load-more control, search results reuse the same session
+reader, and the transcript pane can switch between readable chat bubbles and
+the raw markdown archive. The static viewer uses shadcn/ui-style design tokens
+and compact button/input/select/sidebar patterns without requiring a frontend
+build step. Archives still keep stable `path:<hash>` keys for folders without
+git identity, but the UI displays the local path.
+
+Provider filters use one stable order: OpenAI (`codex-cli`, `codex-desktop`,
+`chatgpt`), Anthropic (`claude`, `claude-code-desktop`, `claude-workspace`,
+`claude-web`, `claude-sdk`), Google (`gemini-cli`, `antigravity`), Cognition
+(`devin-cli`), then other local tools (`cursor`, `cline`, `opencode`,
+`aider`).
+
+When running, the supervisor polls the watcher source list chosen during init
+every 30 seconds using the configured import window, defaulting to the last 30
+days. The default watcher choices are Codex CLI, Codex Desktop, Claude Code CLI,
+Claude Code Desktop, Claude Workspace, Gemini CLI, Antigravity, Devin CLI,
+Cursor, Cline, OpenCode, and Aider. New configs still support
+`imports.autoDiscoverSources=true`, but init records the chosen watcher list
+exactly by setting `imports.autoDiscoverSources=false`.
+Cursor raw SQLite recovery is intentionally left to explicit imports such as
+`agentlog import --source cursor --since all`; the supervisor handles
+incremental Cursor logs going forward and prunes duplicate transcript snapshots.
+The detailed watcher/import contract, including sourcePath replacement rules for
+multi-session stores such as Cursor SQLite and Devin `sessions.db`, lives in
+[`docs/history-source-handling.md`](docs/history-source-handling.md).
+
+Remote sync can be configured during init or from the CLI. Local storage remains
+canonical. Current sync is upload-only: this machine pushes changed archive
+objects to the remote target and never deletes objects from the bucket just
+because they are missing locally.
+
+```sh
+agentlog sync \
+  --endpoint https://<account-id>.r2.cloudflarestorage.com/<bucket> \
+  --device-name "work-laptop" \
+  --access-key-id <id> \
+  --secret-access-key <key>
+```
+
+If you prefer to split the values manually, use
+`--endpoint https://<account-id>.r2.cloudflarestorage.com --bucket <bucket>`.
+
+The same values can be supplied with `AGENTLOG_REMOTE_ENDPOINT`,
+`AGENTLOG_REMOTE_BUCKET`, `AGENTLOG_REMOTE_ACCESS_KEY_ID`, and
+`AGENTLOG_REMOTE_SECRET_ACCESS_KEY`. R2 also accepts `R2_ENDPOINT`,
+`R2_BUCKET`, `R2_ACCESS_KEY_ID`, and `R2_SECRET_ACCESS_KEY`.
+
+The bucket should already exist before running sync. For Cloudflare R2, copy the
+S3 API URL from the bucket's Settings > General page. Cloudflare may include the
+bucket in that URL, such as
+`https://<account-id>.r2.cloudflarestorage.com/<bucket>`; agentlog accepts that
+and derives the bucket automatically. Create an R2 API token from the R2 Object
+Storage overview with Manage API Tokens, scoped to the agentlog bucket with
+read, write, and list permissions. For AWS S3, use an IAM access key scoped to
+the bucket or `agentlog/` prefix with `ListBucket` and object read/write
+permissions.
+
+During `agentlog init`, a configured cloud destination is uploaded immediately
+after the initial backfill. If auto-start is enabled, init also asks for a cloud
+autosync cadence; the background supervisor then uploads new archive changes on
+that interval.
+
+Remote objects are namespaced by device so multiple machines can upload into
+one bucket without overwriting each other's archive roots:
+
+```text
+s3://<bucket>/agentlog/
+  devices/
+    work-laptop/
+      sessions/...
+      raw-sources/...
+      indexes/...
+  snapshots/
+    20260504T173000Z/
+      work-laptop/
+        sessions/...
+```
+
+Use `agentlog snapshot` to upload a redundant point-in-time copy under
+`agentlog/snapshots/<timestamp>/<device>/...`:
+
+```sh
+agentlog snapshot --name before-reimport
+```
+
+Receive-only and two-way sync are intentionally not active yet. The intended v1
+shape is to read other device namespaces and merge normalized session metadata
+without treating absence on one machine as a deletion. Remote deletes should be
+an explicit garbage-collection command, not a side effect of sync. For extra
+protection, enable provider-native versioning, retention, or lifecycle rules
+where available so accidental overwrites remain recoverable outside agentlog too.
+
+Archived sessions are stored as readable markdown first, with metadata, raw
+transcript JSONL, normalized canonical event JSONL, and a raw source-file folder
+alongside it:
+
+```text
+~/.agentlog/data/agentlog/
+  sessions/
+    repo=<encoded_repo>/
+      provider=<provider>/
+        year=2026/
+          month=04/
+            day=27/
+              session=<id>.conversation.md
+              session=<id>.metadata.json
+              session=<id>.transcript.jsonl
+              session=<id>.events.jsonl
+              session=<id>.raw/
+                manifest.json
+                001-<original-file-name>
+```
+
+For large multi-session stores such as Cursor SQLite, the per-session raw
+manifest may reference one shared copy under `raw-sources/` instead of copying
+the same database into every session folder.
+
+`events.jsonl` uses the local `agentlog.events.v1` canonical event shape:
+`session.started`, `prompt.submitted`, `response.generated`, `tool.called`, and
+`tool.completed`. Parser versions are stamped by source type so importer output
+changes can trigger reimport with a new fingerprint. Recall/search builds a
+keyword index over event text first and falls back to transcript/markdown for
+legacy archives without events.
+
+Stats are import-time metadata, not viewer-time transcript repair. Archive
+metadata stores message counts, user-message counts, token usage, and models for
+each session, and the web stats view reads those fields directly. During pre-v1
+development, if those stats fields or parser semantics change, rebuild the local
+archive with `agentlog reset --yes`, `agentlog init`, and
+`agentlog import --source all --since all`.
+
+ChatGPT and Claude.ai web exports are imported manually from an official `.zip`,
+an unzipped export folder, or a direct JSON file. These imports are stored as
+local scoped web-chat archives and displayed through virtual conversation roots
+such as `[chatgpt]conversations/<account-id>` and
+`[claude]conversations/<account-id>/<project>`. The importer records account
+metadata in `~/.agentlog/state/web-accounts.json`; use
+`agentlog accounts list` to inspect mappings and
+`agentlog accounts rename <provider> <account-id-or-username> --display-name <name>`
+to change the viewer display name. Repeated manual uploads are incremental:
+unchanged conversations are skipped, and updated conversations replace the
+stable session for that provider/account/conversation id. Existing malformed
+pre-v1 web-chat archives are not migrated automatically; reimport from the
+original export after a reset or cleanup.
+
+Tool calls and tool results are normalized before archive write where provider
+data is available. For example, Devin tool calls live in
+`message.metadata.toolCalls[]` and render as tool cards in the viewer without
+being appended to assistant prose as synthetic `Grep(...)` text. Canonical
+tool events also carry viewer-facing `category`, `categoryLabel`, `icon`,
+`inputPreview`, and `target` fields so the web viewer can render Bash, edit,
+read, search, web, task, skill, and MCP calls consistently across providers.
+
+Use `agentlog reset` to stop agentlog, disable autostart, and remove agentlog's
+local home, config, state, cache, logs, and archive objects. Source application
+histories and MCP configuration files are not changed. Add `--keep-autostart`
+to leave the login item in place.
+
+## Import Windows
+
+`agentlog init` starts with interactive setup: choose archive destinations,
+choose the full local archive/cache path, choose background service behavior and
+recall commands or skills, then discover sources and optionally backfill history.
+After backfill, init asks which sources the background watcher should keep
+polling, then offers local OTel bridges for Claude Code, Gemini CLI, and Cline.
+Local archive storage is always enabled; R2, S3, and custom remote sync targets
+can be added as upload-only optional destinations with a device name for the
+remote namespace. Discovery and import phases show progress bars while they scan
+local stores.
+
+After discovery, init offers a checkbox-style source picker. Claude SDK jobs
+are shown as a separate opt-in source because batch SDK traffic can exceed
+interactive sessions. The selected sources are saved in config and used by
+later `agentlog import --source all` runs unless `--sources` is provided
+explicitly.
+
+Default init sources:
+
+- Codex CLI sessions and Codex Desktop sessions from Codex state, shown as
+  separate toggles
+- Claude Code CLI transcripts from `~/.claude/projects`
+- Claude Code Desktop metadata and Claude Workspace/local-agent sessions from
+  the Claude app data, shown as separate toggles
+- Gemini CLI saved chats/checkpoints under `~/.gemini/tmp`, plus session/export JSONL stores with tool, usage, and checkpoint metadata
+- Antigravity task/plan/walkthrough artifacts under `~/.gemini/antigravity/brain`
+- Devin for Terminal sessions from `~/.local/share/devin/cli/sessions.db`
+- Cursor chats from older workspace `state.vscdb` SQLite stores and global
+  `cursorDiskKV` Composer/Agent rows, including `aiService` prompt/generation
+  fallbacks, raw SQLite salvage from Cursor global/workspace backups and WAL
+  files, conservative matching of raw assistant/tool companion fragments back
+  to same-project workspace sessions, duplicate prefix pruning, and newer
+  `~/.cursor/projects/<project>/agent-transcripts` files
+- Cline task folders from VS Code/JetBrains globalStorage, including checkpoint diffs when present
+- OpenCode JSON session/message/part storage under `~/.local/share/opencode`
+- Aider repo-local `.aider.chat.history.md` transcripts, with `.aider.llm.history`
+  model/usage enrichment, `.aider.input.history` backups, and matching auto-commit diffs
+
+The Claude Code desktop registry mostly stores metadata pointing back to the
+standard Claude Code transcript, so agentlog imports the transcript when it exists
+and only imports Claude Workspace sessions that contain actual prompt
+content.
+
+Windsurf import is disabled for now. Current Cascade transcripts are encrypted
+binary stores, so agentlog can detect that a session exists but cannot archive
+readable conversation text from it yet.
+
+For the full source-by-source implementation map, see
+[History Source Handling](docs/history-source-handling.md).
+For the current module and function map, see
+[Code Reference](docs/code-reference.md).
+
+`agentlog init` also includes a numbered history-import window picker:
+
+- `1` last 30 days
+- `2` last 90 days
+- `3` last 180 days
+- `4` everything
+- `5` custom interval such as `7d`, `12h`, `60m`, or `all`
+- `6` skip
+
+The same choices can be run directly:
+
+```sh
+agentlog import --source all --since all
+agentlog import --sources codex-cli,codex-desktop,claude,claude-code-desktop,claude-workspace,gemini-cli,antigravity,devin-cli,cursor,cline,opencode,aider --since all
+agentlog import --source codex-desktop --since 90d
+agentlog import --source codex-cli --since 30d
+agentlog import chatgpt ~/Downloads/chatgpt-export.zip --username you@example.com
+agentlog import claude-web ~/Downloads/claude-export --username you --display-name "Personal Claude"
+agentlog import --source claude --since 30d
+agentlog import --source claude-code-desktop --since all
+agentlog import --source claude-workspace --since all
+agentlog import --source gemini-cli --since all
+agentlog import --source antigravity --since all
+agentlog import --source devin-cli --since all
+agentlog import --source cursor --since all
+agentlog import --source cursor --since all --explain-skips
+agentlog import --source cline --since all
+agentlog import --source opencode --since all
+agentlog import --source aider --since all
+agentlog import --source claude-sdk --since all
+agentlog accounts list
+agentlog accounts rename claude-web you --display-name "Personal Claude"
+```