Skip to content

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.md
index 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
### Fixed
diff --git a/docs/desktop/antigravity.md b/docs/desktop/antigravity.md
index 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 be
inferred 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 surface
diff --git a/docs/desktop/capture-and-dedup.md b/docs/desktop/capture-and-dedup.md
index 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: hooks
already 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 same
id across surfaces. ai-memory's `(agent=claude-code, session_id)` key
therefore 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 own
auto-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 in
one pool); or
- (b) leave per-scratch projects but tag them `claude-desktop` via
session 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; not
buildable today.
4. Grok Bot `mcpBoxServers` entry format — reverse-engineer only if the
product 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.md
index 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 the
Linux 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 ordinary
per-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 transcript
store 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 existing
CLI 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 or
relabel 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.md
index 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 tool
on 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 store
diff --git a/docs/desktop/desktop-landscape.md b/docs/desktop/desktop-landscape.md
index 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 RFC
didn'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` (agent
mapping/`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.md
index 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" — still
holds, 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 paths
in 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` project
vs per-scratch projects with a `claude-desktop` tag (see
`capture-and-dedup.md` §2). This is the only dedup work the research
found 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? (No
current 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.md
new file mode 100644
index 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.md
index 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 that
already 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 MCP
servers 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** Claude
Desktop. "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 local
JSON-config path because it works with localhost/LAN servers and does
not 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 writes
to 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.md
index 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`). |