Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
docs(desktop): correct the Claude Desktop guidance and record live verification
AkitaOnRailsf72c737c09cd
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 55cc2895..376c5ff1 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]+### Fixed+- Corrected the Claude Desktop documentation: Linux is an Anthropic beta for+ Debian-based distributions with its config at+ `~/.config/Claude/claude_desktop_config.json` (pass it to+ `install-mcp --client claude-desktop` with `--config-file`), the Code tab's+ local sessions are already captured by the Claude Code hooks, and Cowork+ capture is not claimed. The desktop-app research notes record what was+ verified live and what is still open. (#878)+## [2.6.2] - 2026-10-08### Fixeddiff --git a/docs/desktop/antigravity.md b/docs/desktop/antigravity.mdindex c0556a1f..86640a4d 100644--- a/docs/desktop/antigravity.md+++ b/docs/desktop/antigravity.md@@ -67,10 +67,23 @@ handle: no `SessionStart`/`SessionEnd` events (session boundaries must beinferred from PreInvocation/Stop), and `cwd` comes as `workspacePaths[]`rather than a single `cwd`. Needs a live verification pass on the IDE.+**Verified with the CLI (`agy` 1.3.0, 2026-10-08; see+`verification-2026-10.md`):** a workspace `.agents/hooks.json` runs with no+trust prompt; `invocationNum` (and `executionNum`) restart at 0 on every+user turn of one conversation, so `invocationNum == 0` marks a turn, not a+new conversation; a `PreToolUse` reply without a `decision` denies the tool;+`PostToolUse` carries the call but not its output; `transcriptPath` names+`transcript_full.jsonl`, with `transcript.jsonl` beside it. The IDE has not+been verified: its agent has never run on this machine.+## Transcript store (local, readable)`~/.gemini/antigravity-ide/brain/<conversationId>/` per conversation:-`transcript.jsonl` + artifacts (per hooks doc). A watcher/poll importer over+`transcript.jsonl` + artifacts (per hooks doc). The CLI writes both+`transcript.jsonl` and `transcript_full.jsonl` under+`brain/<conversationId>/.system_generated/logs/`, each opening with a+`USER_INPUT` step that holds the prompt, and keeps per-conversation state in+`conversations/<conversationId>.db` (verified 2026-10-08). A watcher/poll importer over`brain/*/` is therefore possible as a fallback capture path.## Plugin/extension surfacediff --git a/docs/desktop/capture-and-dedup.md b/docs/desktop/capture-and-dedup.mdindex 3a8cff23..65775f0b 100644--- a/docs/desktop/capture-and-dedup.md+++ b/docs/desktop/capture-and-dedup.md@@ -12,8 +12,9 @@ apps; Cursor is the exception") needs revision after this research:| Surface | Capture mechanism | Effort || --- | --- | --- |-| Claude Desktop **Code/Cowork** | Already captured: desktop runs Claude Code with user `~/.claude/settings.json` → ai-memory hooks fire (`agent=claude-code`, cwd = scratch workspace). **Zero new code.** | 0 |-| Codex desktop (Codex mode) | Same host config as CLI (`~/.codex/hooks.json`) → hooks expected to fire in-app. **Verify live; then zero code.** | verify |+| Claude Desktop **Code** tab (local) | Already captured: desktop runs Claude Code with user `~/.claude/settings.json` → ai-memory hooks fire (`agent=claude-code`; a folderless session's cwd is a scratch workspace). Verified from transcripts 2026-10-08. **Zero new code.** | 0 |+| Claude Desktop **Cowork** | Unverified: on Linux its tasks run in a QEMU/KVM VM; never run on the research machine. | verify |+| Codex desktop (Codex mode) | Same host config as CLI (`~/.codex/hooks.json`); `codex app-server`, which the app runs, fires trusted hooks (verified 2026-10-08). One in-app prompt still to confirm. **Then zero code.** | verify || Antigravity IDE / 2.0 / CLI | Native hooks (`~/.gemini/config/hooks.json` + `.agents/hooks.json`); payload has `conversationId`, `transcriptPath`, `workspacePaths[]`, `toolCall`. Map to `/hook` observations. ai-memory already ships `install-hooks --agent antigravity-cli`; IDE reads the same global file. | adapter polish || Zed (ACP + terminal agents) | Agent's own hooks; Zed transparent. | 0 || Claude Desktop **Chat tab**, hosted ChatGPT chat, Grok Bot | No hooks, no local store → model-discretion MCP tool calls (option a) and/or explicit capture tool. | RFC Phase 1 |@@ -39,7 +40,7 @@ output. Practical consequences:Now concrete per app (paths verified locally unless noted):- `~/.claude/projects/<munged-cwd>/<session>.jsonl` — Claude Code-family- transcripts (desktop Code/Cowork included). Watcher optional: hooks+ transcripts (desktop Code tab included). Watcher optional: hooksalready cover it; a watcher adds value only for hookless flows (e.g.user disabled hooks).- `~/.codex/sessions/**/rollout-*.jsonl` + `~/.codex/history.jsonl` — Codex.@@ -64,14 +65,17 @@ Verified mechanics (see `claude-desktop.md`):(CLI UUID). `/desktop` and `claude --desktop --resume <id>` move the sameid across surfaces. ai-memory's `(agent=claude-code, session_id)` keytherefore sees **one session**, no dedup needed.-- Desktop Cowork spawns **new** CLI sessions under ephemeral scratch cwds+- A desktop Code session started without a project folder is a **new** CLI+ session under an ephemeral scratch cwd(`~/.config/Claude/scratch-workspaces/<acct>/<org>/scratch-YYYY-MM-DD-hex`).+ An earlier version of this note attributed these to Cowork; the desktop+ records say otherwise (`verification-2026-10.md`).Two effects to design for:1. **Project fragmentation**: every scratch dir becomes its ownauto-named project. Today that means a stream of one-off projects.Options (product decision, not research):- (a) detect the scratch-workspace path prefix in scope resolution and- route to a single `desktop/claude-cowork` project (keeps memory in+ route to a single `desktop/claude-scratch` project (keeps memory inone pool); or- (b) leave per-scratch projects but tag them `claude-desktop` viasession metadata for filtering.@@ -121,14 +125,19 @@ never invent capture from it — treat as metadata only.## 3. Open questions-1. Do Codex hooks fire for desktop-app sessions? (live test; if no, a- `~/.codex/sessions` watcher is the fallback for desktop capture.)+1. Codex desktop: `codex app-server` fires trusted hooks (verified+ 2026-10-08); one in-app prompt remains to rule out a desktop-side+ override.2. Does Antigravity IDE honor `~/.gemini/config/hooks.json` in practice, and- does `workspacePaths` ever contain >1 path on this setup? (live test)+ does `workspacePaths` ever contain >1 path on this setup? (The CLI honors+ `.agents/hooks.json`, verified 2026-10-08; the IDE is still a live test.)3. Claude Desktop Chat tab: is any local conversation cache planned(desktop extensions/plugins evolve fast)? Re-check quarterly; notbuildable today.4. Grok Bot `mcpBoxServers` entry format — reverse-engineer only if theproduct gains traction with users; no docs.-5. Scope for scratch-workspace sessions: single `desktop/claude-cowork`+5. Scope for scratch-workspace sessions: single `desktop/claude-scratch`pool vs per-scratch projects (product decision; affects auto-scope).+6. Antigravity `invocationNum` restarts at 0 on every user turn, so+ ai-memory's SessionStart mapping runs per turn: acceptable, or gate it+ per conversation? (product decision after measuring the server effect)diff --git a/docs/desktop/claude-desktop.md b/docs/desktop/claude-desktop.mdindex 048ab3a2..3bb7333f 100644--- a/docs/desktop/claude-desktop.md+++ b/docs/desktop/claude-desktop.md@@ -9,8 +9,10 @@One Electron app, three tabs: **Chat** (claude.ai consumer chat), **Cowork**(long-running agentic work / Dispatch), **Code** (Claude Code sessions).Officially on macOS and Windows; **Linux is an official beta** (apt/.deb for-Ubuntu and Debian — <https://code.claude.com/docs/en/desktop>,-<https://code.claude.com/docs/en/desktop-linux>). The local machine runs the+Ubuntu 22.04+ and Debian 12+ only; other distributions are pointed at the+CLI — <https://code.claude.com/docs/en/desktop>,+<https://code.claude.com/docs/en/desktop-linux>). On Linux, Cowork runs its+tasks inside a QEMU/KVM virtual machine the app hosts. The local machine runs theLinux build (`/usr/share/applications/com.anthropic.Claude.desktop`,Electron profile at `~/.config/Claude/`).@@ -60,11 +62,12 @@ Remote per-session MCP servers also appear in desktop session state —a `remoteMcpServersConfig` list (verified locally; two remote servers incl.Anthropic's own Docs MCP).-**Desktop Extensions (`.mcpb`)** were announced (Sept 2025) as a one-click-bundle format for local MCP servers. Current official docs route one-click-extensibility through **plugins** (`/plugin install`, marketplaces) rather-than `.mcpb`; the RFC's `.mcpb` assumption needs re-validation before any-Phase-1 work. Ambiguous — flagged rather than guessed.+**Desktop Extensions (`.mcpb`)** are current: Anthropic's support article+presents them as the main way to install a local MCP server in Claude+Desktop, Linux included+(<https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop>,+re-checked 2026-10-08, see `verification-2026-10.md`). Plugins are the Code+tab's extension surface.## Lifecycle hooks / capture surface@@ -77,11 +80,18 @@ Phase-1 work. Ambiguous — flagged rather than guessed.`ai-memory ... hook --event session-start --agent claude-code ...`).Therefore **ai-memory already captures desktop Code sessions today**, keyed`agent=claude-code`, `session_id=<CLI UUID>`, `cwd=<session workspace>`.-- Cowork/local-agent sessions run in per-session scratch workspaces:+- Code-tab sessions started without a project folder run in per-session+ scratch workspaces:`~/.config/Claude/scratch-workspaces/<account>/<org>/scratch-<date>-<hex>/`(verified locally), which show up in `~/.claude/projects/` as ordinaryper-directory projects (verified: several- `-home-...-Claude-scratch-workspaces-...` project dirs).+ `-home-...-Claude-scratch-workspaces-...` project dirs). Their desktop+ records sit under `claude-code-sessions/` with `envScopeId: builtin_local`+ and `scratchOfferFolder: true`; an earlier version of this note+ attributed them to Cowork, which keeps its own store under+ `~/.config/Claude/local-agent-mode-sessions/`. Cowork has not run on this+ machine (its VM images were never downloaded), so its capture is+ unverified.- Consumer-chat transcripts are **cloud-stored**; no stable local transcriptstore for the Chat tab. Code-tab transcripts are the standard`~/.claude/projects/<munged-cwd>/<session-uuid>.jsonl` files.@@ -112,7 +122,10 @@ real and observable on this machine. Mechanism, from local artifacts:opens it in the desktop app, then exits the CLI"; from the shell,`claude --desktop [--continue | --resume <session-id>]` opens an existingCLI session in Desktop and the **session keeps its ID**- (<https://code.claude.com/docs/en/desktop#coming-from-the-cli>).+ (<https://code.claude.com/docs/en/desktop#coming-from-the-cli>). Both are+ documented for macOS and x64 Windows only; on any platform, `/resume`+ inside a local Desktop session picks up a CLI session from this+ computer, again continuing the same session.4. **Deep links**: `claude-cli://` URL scheme handled by`~/.local/share/applications/claude-code-url-handler.desktop` →`claude --handle-uri %u` (verified locally) — how other apps hand a@@ -126,9 +139,10 @@ real and observable on this machine. Mechanism, from local artifacts:- A desktop Code session and the CLI session it came from (via`--resume`/`/desktop`) are **one session id** — capture dedups naturally.-- A desktop Cowork session is a *new* CLI session (new UUID) whose cwd is a- fresh scratch workspace; ai-memory sees it as a claude-code session in an- auto-named project derived from the scratch path. The desktop↔CLI mapping+- A desktop Code session started without a folder is a *new* CLI session+ (new UUID) whose cwd is a fresh scratch workspace; ai-memory sees it as a+ claude-code session in an auto-named project derived from the scratch+ path. Cowork sessions are a separate, unverified case (see above). The desktop↔CLI mapping(`local_* ↔ cliSessionId`) is available on disk if we ever want to join orrelabel desktop-originated sessions (see `capture-and-dedup.md`).- The `entrypoint: "claude-desktop"` marker in `~/.claude/sessions/<pid>.json`diff --git a/docs/desktop/codex-desktop.md b/docs/desktop/codex-desktop.mdindex c2583d1e..7d0674ce 100644--- a/docs/desktop/codex-desktop.md+++ b/docs/desktop/codex-desktop.md@@ -75,14 +75,16 @@ Codex has a native lifecycle-hooks framework- Handlers can be `command` or `mcp_tool` (a lifecycle event can call a toolon a connected MCP server — an interesting future capture path).-**Open question (needs a live test):** the hooks doc does not explicitly-scope hooks to the CLI. Since the desktop app and CLI "share MCP-configuration for the same Codex host" and hooks live in the same config-layers, desktop-app Codex sessions are *expected* to fire the same hooks —-but none of the fetched pages says so in so many words. Verification test:-run a session in the desktop app with ai-memory hooks installed and watch-`/hook` observations arrive (or check `~/.codex/sessions/rollout-*.jsonl`-creation + ai-memory session list). Until then, treat as *likely, unproven*.+**Verified 2026-10-08 (see `verification-2026-10.md`):** the desktop app+spawns `codex app-server` from the `codex` on `PATH` with+`CODEX_HOME=~/.codex`, and app-server runs the same hooks as the TUI once+they are trusted. Untrusted or modified hooks are skipped without any+message, and trust is recorded per hook content (event, matcher, handler),+so changing an installed hook command needs a fresh trust. `SessionEnd`+fires when a thread is archived or app-server shuts down cleanly, not when+a client unsubscribes. The hook payload does not say which client started+the session; the rollout's `session_meta.originator` does. A desktop-app+prompt with the ai-memory hooks in place has not been run yet.## Transcript storediff --git a/docs/desktop/desktop-landscape.md b/docs/desktop/desktop-landscape.mdindex ee55d78d..fa5aa555 100644--- a/docs/desktop/desktop-landscape.md+++ b/docs/desktop/desktop-landscape.md@@ -6,8 +6,8 @@| App | MCP client | Remote HTTP MCP | Lifecycle hooks | Local transcript store | Plugin/extension API | Open source | Session bridge to CLI || --- | --- | --- | --- | --- | --- | --- | --- |-| **Claude Desktop** (Chat+Cowork+Code tabs; Linux beta) | Chat tab: stdio via `claude_desktop_config.json` + GUI connectors. Code tab: full Claude Code MCP (stdio/SSE/HTTP/WS, plugins) | Yes (connectors + Code-tab http) | **Yes for Code/Cowork** — same `~/.claude/settings.json` hooks the CLI uses (local verified); none for Chat tab | Code/Cowork: `~/.claude/projects/<cwd>/<uuid>.jsonl` (local verified). Chat: cloud only | Plugins (marketplace, can bundle MCP+hooks; desktop has plugin browser); `.mcpb` desktop extensions announced 2025 — current status ambiguous | App closed; claude-code CLI distributed not-open | **Yes** — `/desktop`, `claude --desktop --resume <id>`; live registry `~/.claude/sessions/<pid>.json` (`entrypoint`, `hostSessionId`, cc-socks messaging socket); desktop record `local_* ↔ cliSessionId` |-| **Codex desktop** (= ChatGPT desktop app, macOS/Windows/Linux) | Yes — `~/.codex/config.toml` `[mcp_servers.*]` (stdio + streamable HTTP + OAuth/CIMD/DCR), Settings GUI, shared with CLI/IDE | Yes (first-class) | **Yes (core)** — `~/.codex/hooks.json`, 12 events, trust review; firing in desktop app *likely but unverified live* | `~/.codex/sessions/**/rollout-*.jsonl` + `history.jsonl` (local verified) | Plugins (bundle MCP servers + hooks, `PLUGIN_ROOT`); App Server protocol open | Codex core open (`openai/codex`); desktop app closed (Linux via community DMG repack) | None documented |+| **Claude Desktop** (Chat+Cowork+Code tabs; Linux beta) | Chat tab: stdio via `claude_desktop_config.json` + GUI connectors. Code tab: full Claude Code MCP (stdio/SSE/HTTP/WS, plugins) | Yes (connectors + Code-tab http) | **Yes for the Code tab** — same `~/.claude/settings.json` hooks the CLI uses (verified from transcripts); none for Chat tab; Cowork unverified (VM on Linux) | Code tab: `~/.claude/projects/<cwd>/<uuid>.jsonl` (local verified). Cowork: own store under `local-agent-mode-sessions/`. Chat: cloud only | Plugins (marketplace, can bundle MCP+hooks; desktop has plugin browser); `.mcpb` desktop extensions — Anthropic's current route for local MCP servers (re-checked 2026-10-08) | App closed; claude-code CLI distributed not-open | **Yes** — `/desktop`, `claude --desktop --resume <id>` (macOS/x64 Windows only), `/resume` inside Desktop; live registry `~/.claude/sessions/<pid>.json` (`entrypoint`, `hostSessionId`, cc-socks messaging socket); desktop record `local_* ↔ cliSessionId` |+| **Codex desktop** (= ChatGPT desktop app, macOS/Windows/Linux) | Yes — `~/.codex/config.toml` `[mcp_servers.*]` (stdio + streamable HTTP + OAuth/CIMD/DCR), Settings GUI, shared with CLI/IDE | Yes (first-class) | **Yes (core)** — `~/.codex/hooks.json`, 12 events, trust review; `codex app-server` (the desktop's engine) fires trusted hooks, verified; one in-app prompt pending | `~/.codex/sessions/**/rollout-*.jsonl` + `history.jsonl` (local verified) | Plugins (bundle MCP servers + hooks, `PLUGIN_ROOT`); App Server protocol open | Codex core open (`openai/codex`); desktop app closed (Linux via community DMG repack) | None documented || **Antigravity IDE** (Google; 2.0 app + CLI `agy` share `~/.gemini`) | Yes — `~/.gemini/config/mcp_config.json` + `.agents/mcp_config.json`; `serverUrl` schema; ADC/OAuth; MCP Store GUI | Yes (`serverUrl` + headers) | **Yes** — `.agents/hooks.json` / `~/.gemini/config/hooks.json` (PreToolUse/PostToolUse/PreInvocation/PostInvocation/Stop; payload includes `conversationId`, `transcriptPath`, `workspacePaths`) | `~/.gemini/antigravity-ide/brain/<conversationId>/**` incl. `transcript.jsonl` (per docs) | Skills/Rules/subagents/sidecars/marketplace + SDK | IDE closed (VS Code/Windsurf fork); CLI closed; Gemini CLI is open ancestor | None documented (IDE vs CLI share config root, distinct `brain/` roots) || **ChatGPT desktop (hosted chat side)** | Hosted chat: remote MCP **plugins only** (no local config read) | Yes (remote plugins) | No (Chat-mode) | No local store (cloud) | Plugins (remote MCP + UI + events; OAuth/SIWC) | Closed | n/a || **Grok webapp launcher** (local wrapper) | n/a (browser) | unverified | n/a | n/a | n/a | n/a | n/a |@@ -17,10 +17,11 @@## Highlights vs RFC #878's assumptions (what changed)1. **The capture picture improved for two ecosystems:**- - **Claude Desktop's Code/Cowork tabs are literally Claude Code** — hooks- in `~/.claude/settings.json` already capture them (`agent=claude-code`,- scratch-workspace cwd). RFC #878 classed Claude Desktop wholesale as- "no hook/event surface"; that is only true of the Chat tab.+ - **Claude Desktop's Code tab is literally Claude Code** — hooks in+ `~/.claude/settings.json` already capture it (`agent=claude-code`;+ a folderless session gets a scratch-workspace cwd). RFC #878 classed+ Claude Desktop wholesale as "no hook/event surface"; that is true of+ the Chat tab, and Cowork is unverified.- **Antigravity (IDE included) has first-class lifecycle hooks** with`transcriptPath` in every payload — a full auto-capture target the RFCdidn't evaluate (it listed Cursor as the only hook-bearing desktop@@ -39,9 +40,9 @@## Ordered capture opportunity (auto-capture without new product code)-1. Claude Desktop Code/Cowork — works today via existing hooks.-2. Codex desktop (verify hooks fire in app) — works via existing- `~/.codex` hooks if verified.+1. Claude Desktop Code tab — works today via existing hooks (verified).+2. Codex desktop — its engine fires the existing `~/.codex` hooks once+ trusted (verified); one in-app prompt pending.3. Antigravity IDE — via existing `~/.gemini/config/hooks.json` (agentmapping/`workspacePaths` handling + verification needed).4. Zed — via ACP/terminal agents' own hooks (nothing to build).diff --git a/docs/desktop/plan.md b/docs/desktop/plan.mdindex 9ced7aaa..36a896b4 100644--- a/docs/desktop/plan.md+++ b/docs/desktop/plan.md@@ -10,34 +10,42 @@ RFC #878's headline — "connection is solved, capture is the crux" — stillholds, but two of its premises moved:1. **"Most desktop chat apps expose no hook/event surface"** is now false- for the *coding* desktop surfaces: Claude Desktop's Code/Cowork tabs are- Claude Code with the user's hooks (captured today, zero code), Codex- desktop shares `~/.codex` hooks config (verify live), and **Antigravity+ for the *coding* desktop surfaces: Claude Desktop's Code tab is+ Claude Code with the user's hooks (captured today, zero code; Cowork+ unverified), Codex desktop shares `~/.codex` hooks config (its engine+ verified), and **Antigravity(IDE included) has first-class lifecycle hooks** with transcript pathsin the payload. The truly hookless set is now: Claude Desktop Chat tab,hosted ChatGPT chat, Grok Bot.-2. **"Claude Desktop .mcpb bundle"** as the Phase-1 one-click route: the- current official extension surface is **plugins** (marketplace; can- bundle MCP servers + hooks; the desktop app has a plugin browser).- `.mcpb` status is ambiguous in current docs — re-validate before- building anything.+2. **"Claude Desktop .mcpb bundle"** as the Phase-1 one-click route:+ re-validated 2026-10-08 — Anthropic's support article presents `.mcpb`+ desktop extensions as the main way to install a local MCP server in the+ desktop app. Plugins (marketplace; can bundle MCP servers + hooks) are+ the Code tab's extension surface.## Phase 0 — docs + verify the free wins (ship anytime)-1. Update `docs/mcp-install.md`:- - Claude Desktop **Linux** is an official beta; document- `~/.config/Claude/claude_desktop_config.json` (replace the "not- officially distributed" note).- - Add a "desktop apps" section pointing at these research notes.+Status 2026-10-08: docs done, verification mostly done; results in+[`verification-2026-10.md`](verification-2026-10.md).++1. Update `docs/mcp-install.md`: **done** — Linux beta and its config path+ (with the `--config-file` the CLI needs there), the Code tab's capture+ through Claude Code hooks, `.mcpb` status, the Cowork boundary.2. Live verifications (machine with the apps installed):- - [ ] Codex desktop: confirm `~/.codex/hooks.json` fires for- desktop-app sessions (watch ai-memory observations + rollouts).- - [ ] Antigravity IDE: confirm global `~/.gemini/config/hooks.json` is- honored by the IDE; record `workspacePaths` shape and- `transcriptPath` layout under `~/.gemini/antigravity-ide/brain/`.-3. Document that Claude Desktop Code/Cowork sessions already flow into- ai-memory, including the scratch-workspace project naming behavior- (user-facing note: expect `...-Claude-scratch-workspaces-...` projects).+ - [x] Codex desktop engine: `codex app-server` fires trusted hooks with+ the CLI payload; untrusted/modified hooks are skipped silently;+ `SessionEnd` on archive or shutdown.+ - [ ] Codex desktop app: one in-app prompt with the ai-memory hooks in+ place.+ - [x] Antigravity CLI: workspace hooks, per-turn `invocationNum` reset,+ transcript layout.+ - [ ] Antigravity IDE: one prompt in a workspace with a recorder+ `.agents/hooks.json`.+ - [x] Claude Desktop Code tab: hooks fire (from transcripts).+ - [ ] Claude Desktop Cowork: one task once the VM is available.+3. Document that Claude Desktop Code-tab sessions already flow into+ ai-memory, including the scratch-workspace project naming behavior:+ **done** (`docs/mcp-install.md`, `docs/support-matrix.md`).## Phase 1 — Antigravity IDE capture parity (smallest new-code step)@@ -55,7 +63,7 @@ The research's best new target — not the RFC's `.mcpb`:## Phase 2 — scope & dedup polish for desktop-originated sessions-- Decide scratch-workspace routing: single `desktop/claude-cowork` project+- Decide scratch-workspace routing: single `desktop/claude-scratch` projectvs per-scratch projects with a `claude-desktop` tag (see`capture-and-dedup.md` §2). This is the only dedup work the researchfound necessary — CLI↔Desktop handoffs keep one session id, so no@@ -96,10 +104,14 @@ The research's best new target — not the RFC's `.mcpb`:## Open questions (research-level, blocking nothing)-1. Codex-in-app hook firing (Phase 0 verification).+1. Codex-in-app hook firing: engine verified; one in-app prompt left.2. Antigravity IDE honoring global hooks (Phase 0 verification).-3. `.mcpb` vs plugins for Claude Desktop one-click (re-check docs).+3. `.mcpb` vs plugins for Claude Desktop one-click: resolved — `.mcpb` is+ Anthropic's current route for local MCP servers in the desktop app.4. Scratch-workspace scoping product decision (Phase 2).5. Tray stack choice + Flatpak feasibility (Phase 4).6. Does the Claude Desktop Chat tab ever gain a local store/export? (Nocurrent path; re-check quarterly.)+7. Antigravity's SessionStart mapping fires on every user turn+ (`invocationNum` restarts per turn): keep, or gate per conversation?+8. Cowork capture on Linux, where tasks run in a VM.diff --git a/docs/desktop/verification-2026-10.md b/docs/desktop/verification-2026-10.mdnew file mode 100644index 00000000..1c8a20cb--- /dev/null+++ b/docs/desktop/verification-2026-10.md@@ -0,0 +1,152 @@+# Live verification pass (2026-10-08)++> Follow-up to the RFC #878 research notes in this directory. Each finding+> below was observed on the research machine (Omarchy/Arch, Linux) or read+> from current official documentation on this date. Experiments ran in+> scratch directories with scratch `CODEX_HOME`s and workspace-level hook+> files; the operator's global agent configuration was never modified. The+> notes in this directory were corrected where these findings contradicted+> them.++Versions: Claude Desktop 2.9939.4 (bundled Claude Code 2.1.280), Codex+desktop 26.707.31428 (community Linux build) driving Codex CLI 0.156.0,+Antigravity CLI (`agy`) 1.3.0, Antigravity IDE 2.5.5.++## Codex desktop++**How the app runs Codex.** The process tree of the running app shows+`codex -c features.code_mode_host=true app-server --remote-control+--analytics-default-enabled`, spawned by Electron. The binary is the `codex`+found on `PATH` (here the Codex CLI 0.156.0), and the launcher exports+`CODEX_HOME=$HOME/.codex` unless it is already set+(`/opt/codex-desktop/start.sh`). The desktop app and the CLI therefore share+one config, hooks file, trust state and session store.++**Hooks fire under `app-server`.** A scratch `CODEX_HOME` with a recorder+`hooks.json` for six events was driven over stdio with the app-server+protocol (`initialize`, `hooks/list`, `thread/start`, `turn/start`):++| Run | Result |+| --- | --- |+| Hooks untrusted | `hooks/list` reports `trustStatus: untrusted`; no hook runs, no `hook/started` notification, nothing tells the user |+| Hooks trusted (`[hooks.state."<path>:<event>:0:0"] trusted_hash = "<currentHash>"`) | `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop` run, each with `hook/started` and `hook/completed` notifications |++Payload keys match the CLI's: `session_id`, `transcript_path`, `cwd`,+`hook_event_name`, `model`, `permission_mode`, plus `source` (`startup`) on+`SessionStart`, `prompt` and `turn_id` on `UserPromptSubmit`, `tool_name`,+`tool_input`, `tool_use_id` (and `tool_response` after the call) on the tool+events, and `last_assistant_message` on `Stop`. Nothing in the payload+identifies the desktop app; the client name only reaches the rollout's+`session_meta.originator` (whatever the client sends as `clientInfo.name`).++**`SessionEnd` timing.** `thread/unsubscribe` does not fire it.+`thread/archive` fires it at once, and a clean app-server shutdown fires it+for a still-open thread. In the desktop app a conversation left open+therefore gets its `SessionEnd` only when it is archived or the app quits.++**Trust is keyed by content, not by file.** Codex hashes a hook's event,+matcher and handler (`codex-rs/hooks/src/engine/discovery.rs` `hook_hash`);+the path only names the state entry. Loading the operator's restored+`~/.codex/hooks.json` content into a scratch home and comparing the reported+`currentHash` values with the operator's stored `trusted_hash` values showed+all seven ai-memory hooks as trusted. Any change to a hook command (a new+binary path, data dir or server URL) makes it `modified`, and Codex then+skips it without telling the user until it is trusted again.++**Usage on this machine.** No rollout under `~/.codex/sessions` was created+by the desktop app (originators are `codex-tui`, `codex_cli_rs`,+`codex_exec`), so no desktop conversation has been run here yet.++## Antigravity++**CLI hooks, verified with `agy` 1.3.0** (workspace `.agents/hooks.json`+recorder, `agy -p` and the documented stream-json input+`{"event":"user","message":{"content":"…"}}` for two turns in one process):++- The workspace hook file was honored with no trust prompt.+- Events per user turn: `PreInvocation` → (`PreToolUse` → `PostToolUse`)* →+ `PostInvocation`, repeated per model call, then `Stop`+ (`terminationReason: NO_TOOL_CALL`, `fullyIdle: true`). No prompt event+ and no session start or end event, as the docs say.+- **`invocationNum` restarts at 0 on every user turn** within one+ conversation, and `executionNum` was 0 on both turns. `invocationNum == 0`+ therefore marks a user turn, not a new conversation. ai-memory maps that+ event to SessionStart (`should_process_hook_event` in+ `crates/ai-memory-cli/src/commands/hook.rs`), so it posts session-start+ and fetches the handoff on every turn. The brief and the profile digest+ have their own once-per-session markers; whether the per-turn+ session-start post and handoff fetch are acceptable is open.+- **A `PreToolUse` reply without a `decision` denies the tool.** A recorder+ that printed `{}` made the transcript record `tool call denied by+ pre-tool hook` and `PostToolUse` never fired. ai-memory's shell and native+ hooks both print `{"decision": "allow"}` and are unaffected.+- `PostToolUse` carries `toolCall {name, args}`, `stepIdx` and `error`, not+ the tool's output (ai-memory reads it from+ `.system_generated/steps/<stepIdx>/output.txt`, #966).+- `transcriptPath` points at+ `~/.gemini/antigravity-cli/brain/<conversationId>/.system_generated/logs/transcript_full.jsonl`;+ `transcript.jsonl` sits next to it. The docs name only `transcript.jsonl`.+ Both start with a `USER_INPUT` step whose `content` holds the prompt in+ `<USER_REQUEST>` tags, in print mode as well.+- Print mode writes no `~/.gemini/antigravity-cli/history.jsonl` line (the+ #1160 replay therefore has nothing to replay for `agy -p`); the transcript+ does have the prompt.+- Conversation state is kept per conversation in+ `~/.gemini/antigravity-cli/conversations/<id>.db`, with `brain/<id>/`,+ `annotations/<id>.pbtxt` and `presence/<id>.lock` alongside.++**IDE: not verified.** `~/.gemini/antigravity-ide/brain` and+`conversations` are empty: the IDE agent has never run on this machine, and+the IDE has no headless chat command. The docs say the IDE reads+`~/.gemini/config/hooks.json` and `.agents/hooks.json`; one interactive+prompt in a workspace carrying a recorder `.agents/hooks.json` would confirm+it without touching the global config.++## Claude Desktop++**Linux status (official docs).** A beta for Debian-based distributions+only (Ubuntu 22.04+, Debian 12+); other distributions are pointed at the+CLI. Cowork on Linux runs its tasks inside a QEMU/KVM virtual machine the+app hosts. Not in the Linux beta: computer use, dictation, Fedora/RHEL.+`/desktop` and `claude --desktop` are documented for macOS and x64 Windows+only. (<https://code.claude.com/docs/en/desktop-linux>,+<https://code.claude.com/docs/en/desktop>)++**Code tab sessions run the user's hooks.** Every Claude Code transcript+under `~/.claude/projects` was classified by `entrypoint`. The three with+`entrypoint: claude-desktop` (Claude Code 2.1.280, 2026-10-02 to 10-04)+carry `hook_success` attachments for `SessionStart:startup` and+`PreToolUse:Bash` from the ai-memory hooks in `~/.claude/settings.json`, and+an `mcp_instructions_delta` adding the `ai-memory` server.++**Scratch workspaces are Code-tab sessions, not Cowork.** Those three+sessions ran in `~/.config/Claude/scratch-workspaces/<account>/<org>/scratch-<date>-<hex>/`.+Their desktop records sit under `~/.config/Claude/claude-code-sessions/`+with `envScopeId: builtin_local` and `scratchOfferFolder: true`: a Code+session started without a project folder. Cowork keeps its own store under+`~/.config/Claude/local-agent-mode-sessions/`.++**Cowork has never run here.** `~/.config/Claude/logs/cowork_vm_node.log`+reports the VM images missing (`rootfs.img`, `vmlinuz`, `initrd`), so there+is no local evidence about hooks or MCP inside Cowork.++**Chat tab.** `~/.config/Claude/claude_desktop_config.json` exists on Linux+and holds no `mcpServers`; `~/.config/Claude/logs/mcp.log` is empty.+Anthropic's docs say servers defined there reach both the Chat surface and+local Code-tab sessions, and the Code tab prefers that definition on a name+clash. Anthropic's support article now presents `.mcpb` desktop extensions+as the main way to install a local MCP server (it mentions Linux keychains+for their secrets), which settles the `.mcpb` question left open in+`claude-desktop.md`.++`install-mcp --client claude-desktop` refuses to guess a path on Linux and+needs `--config-file ~/.config/Claude/claude_desktop_config.json`.++## Still unverified++| Question | What would settle it |+| --- | --- |+| Does the Codex desktop app pass anything at `thread/start` that disables hooks? | One prompt in the desktop app with the trusted ai-memory hooks in place, then check the hook spool or server for a `codex` session whose rollout originator is the desktop's |+| Does the Antigravity IDE run `.agents/hooks.json` / `~/.gemini/config/hooks.json`, with the same payload as the CLI? | One IDE prompt in a scratch workspace carrying a recorder `.agents/hooks.json` |+| Do host hooks and MCP servers reach Cowork's VM on Linux (and on macOS/Windows)? | One Cowork task after the VM images download, then look for hook output in its transcript |+| Is a per-turn Antigravity session-start acceptable, or should it be gated per conversation? | A product decision once the server-side effect of repeated session-start posts is measured |diff --git a/docs/mcp-install.md b/docs/mcp-install.mdindex 41dce262..e95f3013 100644--- a/docs/mcp-install.md+++ b/docs/mcp-install.md@@ -497,7 +497,9 @@ Sources: <https://dev.meta.ai/docs/muse-code/configuration>,## Claude Desktop-**Status:** ✅ MCP supported (via stdio shim for HTTP). ❌ No lifecycle hooks.+**Status:** ✅ MCP supported (via stdio shim for HTTP). ❌ No lifecycle hooks+in the Chat tab. The Code tab runs Claude Code itself, so its local sessions+are captured by the [Claude Code](#claude-code) hooks.**Config file:**- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`@@ -508,8 +510,11 @@ Sources: <https://dev.meta.ai/docs/muse-code/configuration>,`Claude_*` package directories automatically and prefers one thatalready contains a config. If multiple candidates remain ambiguous,it stops and asks for an explicit `--config-file` instead of guessing.-- Linux: not officially distributed by Anthropic. Use Claude Code- (terminal) instead.+- Linux: `~/.config/Claude/claude_desktop_config.json`. Anthropic ships+ Claude Desktop for Linux as a beta for Debian-based distributions+ (Ubuntu 22.04+, Debian 12+). `install-mcp` does not detect this path on+ Linux yet, so pass it explicitly:+ `ai-memory install-mcp --client claude-desktop --apply --config-file ~/.config/Claude/claude_desktop_config.json`.**Important:** Claude Desktop's JSON config supports stdio MCPservers only. To talk to ai-memory's HTTP endpoint, bridge through@@ -531,16 +536,29 @@ stdio shim. Requires Node.js installed on the same machine.- After editing the config, **fully quit and relaunch** ClaudeDesktop. "Check for Updates…" is not enough.- Claude Desktop also has account-level remote custom connectors and- `.mcpb` desktop extensions. The ai-memory CLI manages the local+ `.mcpb` desktop extensions, which Anthropic now presents as the main way+ to install local MCP servers. The ai-memory CLI manages the localJSON-config path because it works with localhost/LAN servers and doesnot require publishing an HTTPS connector.+- Servers in `claude_desktop_config.json` also reach the Code tab's local+ sessions, alongside `~/.claude.json` and `.mcp.json`; when both define a+ server with the same name, the Code tab uses the+ `claude_desktop_config.json` entry.- Claude Desktop's ordinary Chat surface exposes MCP tools but does not run- plugin lifecycle hooks, so ai-memory cannot automatically capture its- prompts/tools or inject session-boundary handoffs. Cowork is a distinct- surface: Anthropic documents that Cowork plugins can run hooks, but ai-memory- does not yet ship a Cowork plugin or claim its event/payload semantics.+ lifecycle hooks, so ai-memory cannot automatically capture its+ prompts/tools or inject session-boundary handoffs.+- The Code tab reads the same `~/.claude/settings.json` as the CLI, so+ `install-hooks --agent claude-code` already captures its local sessions+ (as `claude-code`). A Code session started without a project folder runs+ in a scratch directory under+ `~/.config/Claude/scratch-workspaces/`, so each one lands in its own+ auto-named project.+- Cowork is a distinct surface whose capture ai-memory does not claim. On+ Linux, Anthropic runs Cowork tasks inside a QEMU/KVM virtual machine;+ whether your host hooks reach it has not been verified.- If the MCP indicator doesn't appear after restart, check the logs:- `~/Library/Logs/Claude/mcp*.log` (macOS). On Windows, check+ `~/Library/Logs/Claude/mcp*.log` (macOS), `~/.config/Claude/logs/`+ (Linux). On Windows, check`%APPDATA%\Claude\logs\` for an unpackaged install or the corresponding`LocalCache\Roaming\Claude\logs\` directory under the detected`%LOCALAPPDATA%\Packages\Claude_<id>\` package.@@ -551,7 +569,9 @@ stdio shim. Requires Node.js installed on the same machine.`install-mcp --client claude-desktop --apply` detects this and writesto the packaged location automatically. On an older ai-memory build,pass `--config-file` pointed at the `LocalCache` path directly.-- Sources: <https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop>,+- Sources: <https://code.claude.com/docs/en/desktop-linux>,+ <https://code.claude.com/docs/en/desktop#shared-configuration>,+ <https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop>,<https://support.claude.com/en/articles/11175166-how-to-connect-remote-mcp-integrations-to-claude>,<https://support.claude.com/en/articles/13837440-use-plugins-in-claude>,<https://learn.microsoft.com/en-us/windows/msix/msix-containerization-overview>diff --git a/docs/support-matrix.md b/docs/support-matrix.mdindex 4a450b6b..780fc811 100644--- a/docs/support-matrix.md+++ b/docs/support-matrix.md@@ -24,7 +24,8 @@| Crush | Managed-only | `ai-memory run crush` resumes its project-local session database and supplies portable context through a temporary supported global-context file; no lifecycle-hook installer is provided. || Managed workstreams | Opt-in | `ai-memory run` provides transparent cross-harness continuity for Claude Code, Codex, OpenCode, OpenCode 2 beta, Pi, Crush, Kimi Code, Command Code, both incompatible Kiro CLI engines, OMP, Grok Build CLI, and Antigravity CLI. Direct launches remain unchanged. See [`docs/managed-workstreams.md`](managed-workstreams.md). || `--yolo` safety + ai-jail | Linux/macOS; Windows partial | `ai-memory run --yolo` warns before it disarms an agent's permission prompts and, on Linux/macOS, offers to re-exec the session inside [ai-jail](https://github.com/akitaonrails/ai-jail) when it is usable — installed and with its sandbox backend present (`bwrap` / `sandbox-exec`); otherwise it asks nothing and proceeds (`--network`, forwarding only already-set credential/config env vars). Accepting the offer shows a checklist of ai-jail toggles pre-marked with smart defaults (credentials present on the host, SSH for an SSH `origin`, worktree metadata in a linked worktree; Docker socket, GPU, display, Pictures, Tailscale unchecked). `--jail` re-runs inside ai-jail without asking (also without `--yolo` and non-interactively; it errors when ai-jail is not usable), `--jail=github,aws,no-mise` is exact (every unnamed checklist row is forced off with `--no-X`; `all`/`none` too; the checklist likewise passes unchecked rows as `--no-X`, while bare `--jail` leaves unmarked rows to your ai-jail config), and `--no-jail` skips the offer. Only toggles the installed ai-jail supports are offered; the credential mounts (`github`, `aws`, `kube`, `gcloud`, `docker-config`) need ai-jail 2.5.0. A project `.ai-jail` in the launch directory replaces the checklist and the bare-`--jail` defaults (ai-jail loads it as-is; `--jail=…` still overrides), and every re-exec passes `--no-save-config` so ai-jail never writes the run's flags into it. Both prompts are skipped on a non-interactive stdin/stderr and when already detected inside ai-jail. Windows gets the warning but never the ai-jail offer (ai-jail is Linux/macOS-only). Opt-in `--true-yolo` implies `--yolo` and, for Claude only, additionally forces `bypassPermissions` over any settings `defaultMode` (interchangeable with `--yolo` for other harnesses); `claude_true_yolo` applies the same Claude extra to `--yolo` launches. Claude's own explicit `ask` rules and command-safety checks still prompt in every mode. See [`docs/design-yolo-safety-ai-jail.md`](design-yolo-safety-ai-jail.md). |-| Claude Desktop (Chat) | MCP-only | Uses `mcp-remote`; the ordinary Chat surface does not run plugin hooks. Cowork plugins can run hooks, but ai-memory does not yet ship a Cowork plugin integration; see the explicit boundary in [`mcp-install.md`](mcp-install.md#claude-desktop). |+| Claude Desktop (Chat) | MCP-only | Uses `mcp-remote`; the ordinary Chat surface does not run lifecycle hooks. macOS, Windows, and Linux (Anthropic's Debian/Ubuntu beta; pass `--config-file ~/.config/Claude/claude_desktop_config.json` there). Cowork capture is not claimed; see the explicit boundary in [`mcp-install.md`](mcp-install.md#claude-desktop). |+| Claude Desktop (Code tab) | Supported | Local Code-tab sessions run Claude Code with the user's `~/.claude/settings.json`, so the Claude Code hooks capture them as `claude-code`; a session without a project folder lands in its own scratch-directory project. || OpenClaw | Supported | MCP config + native plugin lifecycle hooks; generated plugin enforces capture exclusions. || Antigravity CLI | Supported | MCP config (`serverUrl`) + lifecycle hooks (`agy` alias). Only `PreInvocation` with `invocationNum = 0` maps to SessionStart; later model calls cannot consume a next-session handoff. No automatic true session-end hook, so run `ai-memory finalize-session --agent antigravity-cli` after the final turn when you need a summary, handoff, and opt-in SessionEnd consolidation; an interactive session launched with `ai-memory run antigravity` is finalized automatically when it exits if the run can tie the session to itself (see [`docs/managed-workstreams.md`](managed-workstreams.md)). `ai-memory run antigravity` (aliases `antigravity-cli`, `agy`) adds managed workstream resume via `--conversation`; its conversation store is not decoded, so the ledger takes user prompts from `agy`'s `history.jsonl` (only this conversation's lines typed in this checkout) and assistant and tool steps from hook capture. Tool outputs (`run_command`, `view_file`, `list_dir`, etc.) are resolved directly from `.system_generated/steps/<stepIdx>/output.txt` during `post-tool-use` while mutation tools preserve code from arguments (#966). || Grok Build CLI | Supported | MCP config (`install-mcp --client grok` → `$GROK_HOME/config.toml`, default `~/.grok/config.toml`) + lifecycle hooks (`install-hooks --agent grok` → `$GROK_HOME/hooks/ai-memory.json`, default `~/.grok/hooks/ai-memory.json`, Grok-specific hook bundle). Capture works. `SessionStart` and `UserPromptSubmit` do not accept the handoff (Grok discards that stdout). The first `PostToolUse` prints `hookSpecificOutput.additionalContext` with the pending handoff and an opted-in `[briefing]`; the model sees it after that tool result. If no tool runs, recover via MCP `memory_handoff_list` then `memory_handoff_accept` with that `handoff_id`. `ai-memory run grok` adds managed workstream resume with the context packet delivered natively through `--rules`. Skills root: `.grok/skills` / `$GROK_HOME/skills` (default `~/.grok/skills`). |