Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

docs(desktop): research notes for desktop-app support (RFC #878)

AkitaOnRailsd690cabdb4d4
diff --git a/AGENTS.md b/AGENTS.md
index 8d20ace2..6c0e8f06 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -624,3 +624,8 @@ Additional boundary rules:
agent-to-agent inbox/queue and the on-start hot-context notice.
- [`docs/companion-crates.md`](docs/companion-crates.md) — boundary for
optional companion projects (e.g. the importer).
+- [`docs/desktop/`](docs/desktop/) — research notes and phased plan for
+ GUI/desktop-app support (Claude Desktop, Codex desktop, Antigravity IDE,
+ ChatGPT/Grok desktop, Zed): verified per-app mechanics, capture/dedup
+ design, installer + CLI coexistence. Reconciles RFC #878; read before
+ any desktop-capture or tray/installer work.
diff --git a/docs/desktop/antigravity.md b/docs/desktop/antigravity.md
new file mode 100644
index 00000000..c0556a1f
--- /dev/null
+++ b/docs/desktop/antigravity.md
@@ -0,0 +1,100 @@
+# Antigravity IDE (research notes)
+
+> Research for RFC #878. Verified against official docs at
+> antigravity.google and the local install. The IDE is closed source
+> (Windsurf/VS Code fork); its agent stack shares `~/.gemini` with the
+> Antigravity CLI (successor to Gemini CLI).
+
+## Product shape (as of 2026-10)
+
+Google ships **Antigravity 2.0** (the desktop agent app), the **Antigravity
+IDE** (standalone Windsurf-derived editor), the **Antigravity CLI** (`agy`),
+and an SDK, all documented at <https://antigravity.google/docs/>. The local
+machine runs the IDE (`/usr/share/applications/antigravity-ide.desktop`,
+`antigravity-ide-url-handler.desktop`, Electron/VS Code profile at
+`~/.config/Antigravity IDE/` — `User/globalStorage/state.vscdb`,
+`workspaceStorage`, `languagepacks.json` confirm the VS Code fork layout).
+`~/.gemini/` exists locally with `antigravity-cli/` and `antigravity-ide/`
+subdirs plus `config/`, `settings.json`, `oauth_creds.json`.
+
+## MCP client support — yes, store-backed and file-configurable
+
+Official: <https://antigravity.google/docs/mcp/>
+
+- Global config: **`~/.gemini/config/mcp_config.json`**; workspace config:
+ **`.agents/mcp_config.json`** in the project root (same file for 2.0, CLI,
+ and IDE).
+- Schema: `mcpServers` object; stdio entries use `command`/`args`/`env`/
+ `cwd`; remote entries use **`serverUrl`** (not `url`/`httpUrl`) +
+ `headers`/`authProviderType`/`oauth`. Optional per-server `disabled`,
+ `disabledTools`.
+- Auth: Google ADC (`authProviderType: "google_credentials"`), OAuth (DCR
+ automatic, or manual `clientId`/`clientSecret` with redirect
+ `https://antigravity.google/oauth-callback`), tokens at
+ `~/.gemini/antigravity/mcp_oauth_tokens.json`.
+- IDE GUI: agent side panel → … → **MCP Servers** (MCP Store + "View raw
+ config" edits the same `mcp_config.json`). CLI: `/mcp` overlay.
+- Permission model keys: `mcp(server/tool)`, `mcp(server/*)`, `mcp(*)`.
+- ai-memory status today: `install-mcp --client antigravity-cli` writes this
+ file (repo `docs/mcp-install.md`). An HTTP ai-memory server fits the
+ `serverUrl` entry shape directly.
+
+## Lifecycle hooks — YES (the standout alongside Claude/Codex/Cursor)
+
+Official: <https://antigravity.google/docs/hooks/>
+
+- Config: workspace **`.agents/hooks.json`** or global
+ **`~/.gemini/config/hooks.json`** (both read by 2.0, CLI, and IDE);
+ plugin-bundled hooks also supported.
+- Events: `PreToolUse`, `PostToolUse` (matcher = tool name regex:
+ `run_command`, `view_file`, `write_to_file`, `replace_file_content`,
+ `grep_search`, `invoke_subagent`, …), `PreInvocation`, `PostInvocation`
+ (around each model call), `Stop`.
+- Payload (stdin JSON, camelCase): `conversationId`, `workspacePaths`,
+ **`transcriptPath`**, `artifactDirectoryPath`, `modelName`, plus
+ `toolCall`, `stepIdx`, etc. Handlers are shell commands with a `timeout`
+ (default 30s).
+- **Crucially, the payload names the transcript file**:
+ `<app_data_dir>/brain/<conversationId>/.system_generated/logs/transcript.jsonl`
+ where `<app_data_dir>` = `~/.gemini/antigravity` (2.0),
+ `~/.gemini/antigravity-cli` (CLI), **`~/.gemini/antigravity-ide` (IDE)**.
+
+**Consequence for ai-memory:** `install-hooks --agent antigravity-cli` writes
+`~/.gemini/config/hooks.json`, which the **IDE also loads** — so global
+capture likely already extends to IDE sessions, with the IDE distinguishable
+by its `transcriptPath` prefix (`antigravity-ide/brain/...`). Differences to
+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.
+
+## Transcript store (local, readable)
+
+`~/.gemini/antigravity-ide/brain/<conversationId>/` per conversation:
+`transcript.jsonl` + artifacts (per hooks doc). A watcher/poll importer over
+`brain/*/` is therefore possible as a fallback capture path.
+
+## Plugin/extension surface
+
+Docs list Skills, Rules, custom subagents, hooks, **Sidecars**, a
+Marketplace, and an SDK; IDE extensions for VS Code/JetBrains/Zed/Xcode also
+exist. (Not yet researched in depth; the marketplace/plugin format was not
+needed for capture conclusions.)
+
+## Open-source status
+
+- Antigravity IDE: **closed** (Windsurf/VS Code-derived binary).
+- Antigravity CLI (`agy`): closed binary per repo docs ("built in Go",
+ per ai-memory's `docs/mcp-install.md`); Gemini CLI
+ (`google-gemini/gemini-cli`) is the open ancestor, and a "GCLI migration"
+ doc exists. Not cloned (nothing directly informative beyond docs).
+- SDK: documented Python SDK (<https://antigravity.google/docs/sdk/overview/>).
+
+## Sources
+
+- <https://antigravity.google/docs/mcp/>, <https://antigravity.google/docs/hooks/>,
+ <https://antigravity.google/docs/cli/overview/>
+- Local: `~/.config/Antigravity IDE/` (VS Code-fork layout,
+ `User/globalStorage/state.vscdb` — no MCP keys configured yet),
+ `~/.gemini/` (config root shared by CLI + IDE),
+ `/usr/share/applications/antigravity-ide*.desktop`
+- ai-memory repo: `docs/mcp-install.md` (Antigravity CLI section)
diff --git a/docs/desktop/capture-and-dedup.md b/docs/desktop/capture-and-dedup.md
new file mode 100644
index 00000000..3a8cff23
--- /dev/null
+++ b/docs/desktop/capture-and-dedup.md
@@ -0,0 +1,134 @@
+# Capture & dedup without lifecycle hooks — and what actually has hooks (research)
+
+> Research for RFC #878. Findings that drive the design; see per-app files
+> for sources. Rule from RFC #878 that still holds: everything entering the
+> store goes through `sanitize()` → `/hook` or `/hook/batch`; never a direct
+> wiki/DB write.
+
+## 1. Revised capture map
+
+RFC #878's core claim ("no clean automatic-capture story for closed desktop
+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 |
+| 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 |
+| Hosted ChatGPT plugins | Remote-only; needs published plugin + reachable server. | new surface |
+
+### What the MCP server can see server-side (all apps)
+
+ai-memory *is* the MCP server, so on any MCP-connected app we observe:
+tool calls (name + args + results), call timestamps, and — through the MCP
+session — nothing else. We do **not** see chat turns, prompts, or model
+output. Practical consequences:
+
+- Server-side observation is enough for **usage telemetry** (which tools an
+ app's model actually calls) and for **recall-effectiveness** signals, not
+ for conversation capture.
+- It is *also* enough to implement an explicit capture primitive the model
+ can be instructed to call (RFC #878 Phase-1 `memory_capture_conversation`
+ idea): on apps without any hook surface this is the only in-band path,
+ and its quality is bounded by the model's willingness to summarize.
+
+### Local-store watchers (option c) — status
+
+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
+ already cover it; a watcher adds value only for hookless flows (e.g.
+ user disabled hooks).
+- `~/.codex/sessions/**/rollout-*.jsonl` + `~/.codex/history.jsonl` — Codex.
+- `~/.gemini/antigravity{,-ide,-cli}/brain/<conversationId>/**/transcript.jsonl`
+ — Antigravity (per hooks doc; not yet verified locally — no IDE chats on
+ the machine).
+- Zed native agent: internal DB in Zed's data dir — **do not** build on it
+ (unstable, version-fragile); rely on ACP agents instead.
+- Claude Chat tab / hosted ChatGPT / Grok Bot: **no local store** — watcher
+ class does not apply.
+
+A watcher/importer remains the importer-envelope (`/hook/batch`) pattern
+from `companions/ai-memory-importer`; keep it out of core (RFC #878 rule).
+
+## 2. Session identity & dedup design
+
+### Claude CLI ↔ Desktop (the case that prompted this)
+
+Verified mechanics (see `claude-desktop.md`):
+
+- Desktop Code sessions **are** Claude Code sessions: one `session_id`
+ (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
+ (`~/.config/Claude/scratch-workspaces/<acct>/<org>/scratch-YYYY-MM-DD-hex`).
+ 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
+ one pool); or
+ - (b) leave per-scratch projects but tag them `claude-desktop` via
+ session metadata for filtering.
+ The desktop-side record (`~/.config/Claude/claude-code-sessions/.../
+ local_*.json`) provides `title`, `createdAt`, account/org and the
+ `local_* ↔ cliSessionId` mapping if we want to enrich/label — but it is
+ an implementation detail of a closed app; treat as optional hint, not
+ a dependency (it can move without notice).
+ 2. **Bridging id exposure**: the desktop id (`local_*`) never reaches
+ hooks, so no collision risk with the CLI UUID.
+- Live-only correlation: `~/.claude/sessions/<pid>.json` gives
+ `entrypoint: claude-desktop` + `hostSessionId` while a process runs. Not
+ archival; useful at most for a tray app's "current desktop sessions" view.
+- The cc-socks Unix sockets (`/run/user/<uid>/cc-socks/<pid>.sock`) are an
+ internal IPC of the closed app — **do not** build on them.
+
+### Codex
+
+One Codex host per user: CLI + desktop + IDE extension share `~/.codex`
+(config **and** session rollout store). Session ids are the rollout UUIDs;
+`(agent=codex, session_id)` is already correct, and a session started in
+the desktop app is distinguishable only by content/absence of TUI markers —
+no id-level split. Hosted ChatGPT/Codex-cloud sessions are cloud ids that
+never touch the local store; if cloud-side capture ever matters it arrives
+via export/API, mapped as a *separate* agent kind (e.g. `codex-cloud`) to
+avoid double-counting with local rollouts.
+
+### Antigravity
+
+`conversationId` (UUID) is the session key, identical across IDE/CLI/2.0
+for the same conversation; the surface is distinguishable by the
+`transcriptPath` prefix (`antigravity-ide/` vs `antigravity-cli/` vs
+`antigravity/`). Map to ai-memory: `agent=antigravity`, session_id =
+`conversationId`, cwd = `workspacePaths[0]` (fallback: last path; the
+payload has no scalar `cwd`). Hook set lacks SessionStart/SessionEnd —
+derive session boundaries from first/last observation timestamps per
+conversation id (ai-memory sessions are already built from observation
+streams, so a Stop-hook flush marker is enough; optional).
+
+### General rule
+
+Dedup key stays `(agent, session_id)`; **surface variants of one agent
+ecosystem that share an id space stay one agent kind** (claude-code covers
+CLI+desktop; codex covers CLI+desktop+IDE ext; antigravity covers
+IDE+CLI+2.0). Where a closed app keeps its own id (desktop `local_*`),
+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.)
+2. Does Antigravity IDE honor `~/.gemini/config/hooks.json` in practice, and
+ does `workspacePaths` ever contain >1 path on this setup? (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`
+ pool vs per-scratch projects (product decision; affects auto-scope).
diff --git a/docs/desktop/chatgpt-desktop.md b/docs/desktop/chatgpt-desktop.md
new file mode 100644
index 00000000..a350276e
--- /dev/null
+++ b/docs/desktop/chatgpt-desktop.md
@@ -0,0 +1,75 @@
+# ChatGPT desktop (research notes)
+
+> Research for RFC #878. Two different things get called "ChatGPT desktop"
+> in late 2026; both are covered. The local machine has no official ChatGPT
+> desktop app — its `ChatGPT.desktop` is an Omarchy webapp launcher
+> (`Exec=omarchy-launch-webapp https://chatgpt.com/`), i.e. a browser
+> wrapper, not the app. Research therefore rests on official docs.
+
+## 1. The ChatGPT desktop app (Codex host) — official
+
+As of 2026-10 OpenAI ships **one desktop app** that hosts both ChatGPT
+(chat/Work) and **Codex** (coding agent): "Download ChatGPT for macOS,
+Windows, or Linux… Choose ChatGPT or Codex. In ChatGPT, use the toggle above
+the composer to select Chat or Work" (<https://developers.openai.com/codex/app>).
+All MCP/hook mechanics of this app are covered in
+[`codex-desktop.md`](codex-desktop.md) — summary:
+
+- **MCP: yes** (stdio + streamable HTTP), configured in
+ `~/.codex/config.toml` `[mcp_servers.*]` or Settings → MCP servers; config
+ shared with Codex CLI and IDE extension.
+- **Lifecycle hooks: yes** (Codex hooks framework, `~/.codex/hooks.json`) on
+ the Codex side; whether hooks fire for Chat-mode conversations is **not
+ documented** — Chat/Work conversations are cloud-thread-shaped and the
+ hooks doc speaks of Codex sessions/turns. Treat Chat-mode auto-capture as
+ unavailable; Codex-mode capture as available (verify live).
+- **Transcripts**: Codex-mode sessions land in `~/.codex/sessions/`
+ rollout JSONL on the Codex host. Chat-mode conversations are cloud-stored;
+ no local transcript store documented.
+
+## 2. ChatGPT web/chat surfaces — connectors (remote MCP only)
+
+- "ChatGPT web can use remote MCP-backed tools supplied by plugins. Local
+ Codex clients can also connect directly to MCP servers… ChatGPT web
+ doesn't read local Codex configuration files"
+ (<https://developers.openai.com/codex/extend/mcp>).
+- The extension surface is **plugins**: MCP server (+ optional UI, events,
+ skills) published to the ChatGPT plugin directory
+ (<https://developers.openai.com/plugins>). Auth is OAuth/Sign-in-with-
+ ChatGPT; no stdio/local servers in hosted Chat.
+- Plugins/connections are administered per workspace for ChatGPT Work
+ (<https://developers.openai.com/codex/enterprise/apps-and-connectors>).
+- **Implication for ai-memory:** an ai-memory *plugin* (hosted remote MCP
+ pointing at a user-run server) is the only sanctioned path into hosted
+ ChatGPT chat — same shape as RFC #878's "remote-only connectors"
+ conclusion. A local loopback ai-memory server cannot be reached from
+ hosted Chat; a tunnel (e.g. OpenAI's "Secure MCP Tunnel" docs exist at
+ <https://developers.openai.com/api/docs/guides/secure-mcp-tunnels>) or a
+ hosted deployment would be required. Not researched further here.
+
+## Linux status
+
+The official app now supports Linux
+(<https://developers.openai.com/codex/linux/linux-app>); historically Linux
+users only had web/wrappers (as on this machine). The AUR `codex-desktop`
+family (distsystem fork) predates/parallels official Linux availability —
+see [`codex-desktop.md`](codex-desktop.md).
+
+## Capture / dedup notes
+
+- Chat-mode: no hooks, no local transcripts → model-discretion memory tool
+ calls only (option (a) in RFC #878) unless a hosted plugin is built.
+- Codex-mode in the desktop app: same store/session identity as Codex CLI
+ (`session_id` from hooks/rollouts under `~/.codex/sessions/`), so
+ ai-memory's `(agent=codex, session_id)` keying applies unchanged.
+- No documented CLI↔desktop session handoff (unlike Claude's `/desktop`).
+
+## Sources
+
+- <https://developers.openai.com/codex/app>,
+ <https://developers.openai.com/codex/extend/mcp>,
+ <https://developers.openai.com/codex/linux/linux-app>,
+ <https://developers.openai.com/plugins>,
+ <https://developers.openai.com/api/docs/guides/secure-mcp-tunnels>
+- Local: `~/.local/share/applications/ChatGPT.desktop` (Omarchy webapp
+ launcher — proves no official app installed here)
diff --git a/docs/desktop/claude-desktop.md b/docs/desktop/claude-desktop.md
new file mode 100644
index 00000000..048ab3a2
--- /dev/null
+++ b/docs/desktop/claude-desktop.md
@@ -0,0 +1,157 @@
+# Claude Desktop (research notes)
+
+> Research for RFC #878. Verified against official docs and the local Linux
+> install on the research machine (Omarchy/Arch, `~/.config/Claude`). Closed
+> source. Facts below cite either a URL or a local path found on this machine.
+
+## Product shape (as of 2026-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
+Linux build (`/usr/share/applications/com.anthropic.Claude.desktop`,
+Electron profile at `~/.config/Claude/`).
+
+The **Code tab runs the same Claude Code engine as the CLI**:
+"Desktop runs the same underlying engine with a graphical interface… They
+share configuration and project memory via CLAUDE.md files" and "The desktop
+app reads the same settings files as the CLI"
+(<https://code.claude.com/docs/en/desktop>).
+
+The desktop app ships and auto-manages its own Claude Code CLI copy:
+`~/.config/Claude/claude-code/2.1.280/claude` (+ `.payload`, `.verified`
+marker files) — found locally.
+
+## MCP client support
+
+Two distinct MCP surfaces:
+
+1. **Chat tab (consumer app)** — local stdio MCP servers via the classic
+ config file `claude_desktop_config.json` under an `mcpServers` key, plus
+ remote HTTPS connectors configured in-app ("Connectors"). Config paths:
+ - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+ - Windows: `%APPDATA%\Claude\claude_desktop_config.json` (or the MSIX
+ AppContainer path — ai-memory's `install-mcp --client claude-desktop`
+ already detects both)
+ - Linux: `~/.config/Claude/claude_desktop_config.json` (**verified
+ locally**; the file exists with a `preferences` object — the Linux beta
+ reuses the same file). Note ai-memory's own `docs/mcp-install.md` still
+ says "Linux: not officially distributed by Anthropic" — that is now
+ outdated versus the official Linux beta and should be updated in a
+ follow-up docs PR.
+ - Source: <https://modelcontextprotocol.io/quickstart/user> (mac/win
+ paths), local file inspection, ai-memory `docs/mcp-install.md`.
+ - Local MCP logs: `~/Library/Logs/Claude/mcp*.log` (mac),
+ `%APPDATA%\Claude\logs` (win) — same source.
+2. **Code tab (Claude Code host)** — the same MCP configuration the CLI uses:
+ `~/.claude.json` (local/user scope), `.mcp.json` (project scope), settings
+ files, and **plugins** (a plugin can bundle MCP servers + hooks; the
+ desktop app has a plugin browser). Connectors in the prompt "+" menu are
+ "MCP servers with a graphical setup flow"
+ (<https://code.claude.com/docs/en/desktop#connect-external-tools>).
+ Transports: stdio, SSE, HTTP (streamable), WebSocket, and an SDK-only
+ in-process `type: "sdk"` reserved for host applications such as the
+ desktop app (<https://code.claude.com/docs/en/mcp>).
+
+Remote per-session MCP servers also appear in desktop session state —
+`~/.config/Claude/claude-code-sessions/<account>/<org>/local_*.json` contains
+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.
+
+## Lifecycle hooks / capture surface
+
+- **No push hooks in the Chat/Cowork tabs.** Capture for consumer-chat
+ conversations stays model-discretion (memory tool calls) — unchanged from
+ RFC #878's conclusion.
+- **The Code tab is full Claude Code**, and it reads the user's
+ `~/.claude/settings.json` — where ai-memory's hooks are already installed
+ (verified locally: `hooks.SessionStart` →
+ `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:
+ `~/.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).
+- 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.
+
+## Session bridging (CLI ↔ Desktop) — verified mechanism
+
+The user report "desktop catches CLI sessions and chat continues on both" is
+real and observable on this machine. Mechanism, from local artifacts:
+
+1. **Every running `claude` process registers a live descriptor** at
+ `~/.claude/sessions/<pid>.json` (verified locally). Fields include:
+ - `sessionId` — the Claude Code session UUID
+ - `entrypoint: "claude-desktop"` when desktop-spawned
+ - `hostSessionId: "local_<uuid>"` — the desktop app's own session id
+ - `cwd`, `version`, `peerProtocol`, `peerFeatures`
+ (`notify_idle`, `reply_across_default_dirs`, `artifact_yield`)
+ - `messagingSocketPath: /run/user/<uid>/cc-socks/<pid>.sock` — a Unix
+ socket used for cross-surface messaging between desktop and CLI peers.
+2. **Desktop-side session records** live at
+ `~/.config/Claude/claude-code-sessions/<account>/<org>/local_<uuid>.json`
+ (verified locally) and carry the join key:
+ - `sessionId: "local_<uuid>"` (desktop id)
+ - `cliSessionId: "<CLI session UUID>"` — **the same UUID as the
+ `~/.claude/projects/.../<uuid>.jsonl` transcript**
+ - plus `cwd`, `originCwd`, `model`, `permissionMode`, `title`,
+ `remoteMcpServersConfig`, timestamps.
+3. **Explicit moves**: `/desktop` inside the CLI "saves your session and
+ 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>).
+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
+ session to Claude Code.
+5. Desktop's "work across sessions" surface only sees sessions the desktop
+ app itself runs (local/SSH/WSL), **not** terminal CLI or VS Code extension
+ sessions; cross-session messaging can additionally reach terminal Claude
+ Code sessions (same doc).
+
+### What ai-memory's `(agent, session_id)` key sees
+
+- 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
+ (`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`
+ is a reliable way to distinguish desktop-spawned sessions post-hoc while
+ the process lives; it is transient (pid-keyed), not archival.
+
+## Open-source status
+
+- Claude Desktop app: **closed** (Electron).
+- Claude Code CLI: distributed via npm/`~/.local/bin/claude`; the GitHub repo
+ `anthropics/claude-code` hosts docs/issues, not full open source. The
+ desktop app's bundled copy (`~/.config/Claude/claude-code/2.1.280/claude`)
+ is the same distribution.
+
+## Sources
+
+- <https://code.claude.com/docs/en/desktop> (desktop app reference, CLI
+ comparison, `/desktop`, settings sharing)
+- <https://code.claude.com/docs/en/mcp> (Claude Code MCP reference)
+- <https://modelcontextprotocol.io/quickstart/user> (claude_desktop_config
+ paths, mcp logs)
+- <https://code.claude.com/docs/en/desktop-linux> (Linux beta)
+- Local: `~/.config/Claude/` (config, sessions, scratch workspaces, bundled
+ CLI), `~/.claude/sessions/`, `~/.claude/projects/`,
+ `~/.local/share/applications/claude-code-url-handler.desktop`
+- ai-memory repo: `docs/mcp-install.md` (claude-desktop section), RFC #878.
diff --git a/docs/desktop/codex-desktop.md b/docs/desktop/codex-desktop.md
new file mode 100644
index 00000000..c2583d1e
--- /dev/null
+++ b/docs/desktop/codex-desktop.md
@@ -0,0 +1,124 @@
+# Codex desktop (the ChatGPT desktop app) (research notes)
+
+> Research for RFC #878. Verified against official docs, the open-source CLI
+> repo (cloned to `~/Projects/_desktop-research/codex-research`), the Linux
+> repackaging project (cloned to
+> `~/Projects/_desktop-research/codex-desktop-linux-research`), and the local
+> install.
+
+## Product shape (as of 2026-10)
+
+OpenAI has merged Codex into the **ChatGPT desktop app**: "Download ChatGPT
+for macOS, Windows, or Linux… Choose ChatGPT or Codex"
+(<https://developers.openai.com/codex/app>). Officially supported on
+**macOS, Windows, and Linux** (docs at
+<https://developers.openai.com/codex/linux/linux-app>). The app is Electron;
+the local machine runs the community Linux repackaging
+`codex-desktop-linux` (AUR `codex-desktop-linux` / originally
+`ilysenko/codex-desktop-linux`, maintained here under the `distsystem` fork)
+which **converts the upstream macOS `Codex.dmg` into Linux .deb/.rpm/pacman
+packages** — i.e. the app itself is closed; the wrapper is open.
+
+Local artifacts: `/usr/share/applications/codex-desktop.desktop`
+(`Exec=... /usr/bin/codex-desktop`), Electron profiles at `~/.config/Codex`
+(release) and `~/.config/Codex (Dev)` (dev build), `~/.config/codex-desktop`
+only holds `electron-flags.conf`.
+
+The desktop app drives the **same Codex core** as the CLI — the open-source
+repo contains `codex-rs/app-server`, `app-server-protocol`,
+`app-server-daemon`, `app-server-transport` crates
+(`~/Projects/_desktop-research/codex-research/codex-rs/`), and docs at
+<https://developers.openai.com/codex/app-server> describe the App Server
+protocol; <https://developers.openai.com/siwc/token-sharing-open-source/codex-app-server>
+documents running your own app-server against the ChatGPT plan.
+
+## MCP client support — shared config with the CLI
+
+"The ChatGPT desktop app, Codex CLI, and IDE extension support MCP servers
+and **share MCP configuration for the same Codex host**"
+(<https://developers.openai.com/codex/extend/mcp>):
+
+- Config file: `~/.codex/config.toml`, `[mcp_servers.<name>]` tables;
+ project scope `.codex/config.toml` (trusted projects only). **Verified
+ locally**: `~/.codex/config.toml` already contains
+ `[mcp_servers.ai-memory] url = "http://192.168.0.90:49374/mcp"` (remote
+ streamable HTTP — works with the desktop app, no Node/npx needed).
+- Desktop app GUI: Settings → MCP servers → Add server (STDIO or Streamable
+ HTTP); `/mcp` in the composer lists servers.
+- CLI: `codex mcp add <name> -- <command>` / `codex mcp list`.
+- Transports: stdio (command/args/env/cwd/env_vars) and streamable HTTP
+ (`url`, `bearer_token_env_var`, `http_headers`, `env_http_headers`,
+ `http_headers_helper`), OAuth incl. CIMD/DCR and ChatGPT session auth.
+ ai-memory's loopback HTTP + optional bearer token maps directly onto this.
+- Server `instructions` field is read as server-wide guidance (keep first
+ 512 chars self-contained) — relevant for how ai-memory's tool-routing
+ guidance is surfaced in Codex.
+
+## Lifecycle hooks — full Claude-Code-style model, in core
+
+Codex has a native lifecycle-hooks framework
+(<https://developers.openai.com/codex/hooks>), confirmed in source
+(`codex-rs/hooks/`, events `user_prompt_submit.rs`, `declarations.rs`):
+
+- Events: `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `PreToolUse`,
+ `PostToolUse`, `PermissionRequest`, `PreCompact`, `PostCompact`,
+ `SubagentStart`, `SubagentStop`, `Stop`, `Interrupt`.
+- Config: `~/.codex/hooks.json` (or inline `[hooks]` in `config.toml`),
+ repo `<repo>/.codex/hooks.json`, plugin-bundled hooks. **Verified
+ locally**: ai-memory already writes `~/.codex/hooks.json` with
+ SessionStart/UserPromptSubmit/PreToolUse/PostToolUse command hooks calling
+ `ai-memory hook --event ... --agent codex --server-url ...`.
+- Hook stdin includes `session_id`, `transcript_path`, `cwd`,
+ `hook_event_name`, `model` — everything ai-memory's capture needs.
+- Trust review: non-managed hooks must be trusted once (`/hooks` in the
+ TUI); trust is recorded against the hook's hash.
+- 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*.
+
+## Transcript store
+
+`~/.codex/sessions/YYYY/MM/DD/rollout-*-<session-uuid>.jsonl` (verified
+locally), plus `~/.codex/history.jsonl` (prompt history keyed by
+`session_id`). Same store for CLI and (expected) desktop sessions — the
+desktop app is the same Codex host.
+
+## Session bridging
+
+No CLI↔desktop bridge equivalent to Claude's `/desktop` is documented.
+CLI and desktop are separate conversation lists over the same host config;
+ChatGPT web/mobile/cloud surfaces are cloud-side and do not read local
+config ("ChatGPT web doesn't read local Codex configuration files",
+<https://developers.openai.com/codex/extend/mcp> — web section). `dots`
+(persistent agents) are cloud-orchestrated; enterprise hooks for dots are
+remote MCP hooks, not local command hooks.
+
+## Open-source status
+
+- `openai/codex` (Apache-2.0): CLI + `codex-rs` core, **hooks crate,
+ codex-mcp, app-server crates** — open.
+- The ChatGPT/Codex **desktop app**: closed (Electron); Linux build only via
+ the community DMG-conversion project (`ilysenko/codex-desktop-linux`,
+ packaged here by `distsystem`).
+
+## Sources
+
+- <https://developers.openai.com/codex/app>,
+ <https://developers.openai.com/codex/extend/mcp>,
+ <https://developers.openai.com/codex/hooks>,
+ <https://developers.openai.com/codex/linux/linux-app>,
+ <https://developers.openai.com/codex/app-server>
+- Clones: `~/Projects/_desktop-research/codex-research` (openai/codex @
+ 5a31401, 2026-10-07), `~/Projects/_desktop-research/codex-desktop-linux-research`
+- Local: `~/.codex/{config.toml,hooks.json,sessions/,history.jsonl}`,
+ `~/.config/Codex/`, `~/.config/'Codex (Dev)'/`,
+ `/usr/share/applications/codex-desktop.desktop` (pacman
+ `codex-desktop-linux 26.707.31428`)
diff --git a/docs/desktop/desktop-landscape.md b/docs/desktop/desktop-landscape.md
new file mode 100644
index 00000000..ee55d78d
--- /dev/null
+++ b/docs/desktop/desktop-landscape.md
@@ -0,0 +1,50 @@
+# Desktop landscape — apps × capabilities (research matrix)
+
+> Research for RFC #878 (2026-10-07). Every row is sourced in the per-app
+> note (`<app>.md`). "Local verified" = confirmed from files on the research
+> machine; otherwise the official-doc URL is the source.
+
+| 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 |
+| **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 |
+| **Grok Bot** (Cursor; native Electron agent) | Yes — MCP machinery in app.asar (`mcpBoxServers` in `~/.grokbot/settings.json`); format/docs **unverified** | unknown | No | No local transcript documented (cloud + leveldb UI state) | plugins evident (`plugin-logo-cache`) — undocumented | Closed (downloads.cursor.com) | n/a |
+| **Zed** | Yes — `context_servers` in settings.json (stdio + url/OAuth); MCP extensions; forwards servers to ACP agents | Yes | No native hooks; ACP/terminal agents bring their own | Native-agent threads in Zed's DB (fragile); terminal/ACP agents use their own stores | Extension API (WASM extensions; MCP extension manifest) | **Open** (`zed-industries/zed`) | n/a (agents run in-place; no bridge needed) |
+
+## 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.
+ - **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
+ target).
+2. **Codex is now the ChatGPT desktop app** with shared `~/.codex` config:
+ one `install-mcp`/`install-hooks` write serves CLI + desktop + IDE
+ extension (desktop-app hook firing needs one live verification).
+3. **Official Linux desktop builds now exist** for Claude Desktop (beta) and
+ the ChatGPT/Codex app — ai-memory's `docs/mcp-install.md` "Linux: not
+ officially distributed" note for claude-desktop is stale.
+4. **Grok Bot is a Cursor product** (not xAI) with embedded MCP support but
+ no public docs — opportunistic, not plannable.
+5. Remote/streamable-HTTP MCP is now the norm across Codex/Antigravity/Zed/
+ Claude(Code) — a loopback ai-memory HTTP server needs **no npx shims** on
+ any researched app except legacy Claude-Desktop-Chat stdio config.
+
+## 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.
+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).
+5. Chat tab / hosted ChatGPT / Grok Bot — model-discretion only (MCP tools);
+ hosted ChatGPT additionally needs a published plugin to reach a
+ user-run server at all.
diff --git a/docs/desktop/grok-desktop.md b/docs/desktop/grok-desktop.md
new file mode 100644
index 00000000..909aec28
--- /dev/null
+++ b/docs/desktop/grok-desktop.md
@@ -0,0 +1,73 @@
+# Grok desktop surfaces (research notes)
+
+> Research for RFC #878. "Grok desktop" on this machine is two different
+> things, both verified locally: (1) a browser webapp launcher for grok.com,
+ and (2) **Grok Bot**, a real native desktop agent from Cursor. xAI's own
+> official desktop app status is also noted.
+
+## 1. Grok webapp launcher (local `Grok.desktop`)
+
+`~/.local/share/applications/Grok.desktop` →
+`Exec=omarchy-launch-webapp https://grok.com/` — an Omarchy browser wrapper,
+not a native app. Nothing to integrate beyond grok.com's own web features
+(remote MCP support on grok.com is **unverified** — xAI docs were not
+fetched; do not assume).
+
+## 2. Grok Bot — Cursor's desktop agent (native, closed)
+
+`/usr/share/applications/grok-bot.desktop` → `/usr/bin/grok-bot`, pacman
+package `grok-bot-bin 0.66.0-1` (AUR; local install). Key verified facts:
+
+- **Distributed by Cursor**: the AUR PKGBUILD pulls
+ `https://downloads.cursor.com/grokbot/stable/<commit>/linux/x64/grok-bot_<ver>_amd64.deb`;
+ package URL/keywords say cursor.com; license `LicenseRef-Proprietary`;
+ installs to `/opt/Grok Bot` (Electron). Formerly/probably codenamed
+ "sand" (`provides=sand`, `sand-*` config files). AUR:
+ <https://aur.archlinux.org/packages/grok-bot-bin>.
+- **Config home**: `~/.grokbot/` (asar strings `.grokbot`,
+ `.grokbot-data-root-v1`; verified `~/.grokbot/settings.json` locally) and
+ Electron profile at `~/.config/Grok Bot/` (Local Storage leveldb, sentry,
+ `dune-reliability` telemetry, `Partitions`, `attachment-image-cache`,
+ `plugin-logo-cache`).
+- **MCP support: yes, embedded.** `strings /opt/Grok Bot/resources/app.asar`
+ shows full MCP machinery (`mcpServers`, `mcpConfigJson`, `McpServer`,
+ `McpExec`, `McpAccount`, `mcp-app`, `McpCustomInstructions`,
+ `mcpDisabledToolsByServerId`, …), and `~/.grokbot/settings.json` has
+ `mcpBoxServers: []`, `mcpCustomInstructions`,
+ `mcpCustomInstructionsByServerId`, `mcpDisabledToolsByServerId` keys
+ (empty — user hasn't configured any). "Box servers" suggests MCP servers
+ run inside Grok Bot's sandboxed "boxes". **No public official docs found**
+ (cursor.com product pages not fetched — Grok Bot appears to be
+ invite/rollout-gated); config format and whether stdio, remote, or both
+ are supported is **unverified**. Next step if pursued: add an MCP entry
+ via the app UI and diff `~/.grokbot/settings.json`.
+- **Local-exec daemon**: `~/.grokbot/local-exec-daemon.log`,
+ `local-exec-supervisor.json`, `local-exec-daemon-credential.json`,
+ `gateway-descriptor.json` — the agent executes tasks locally through a
+ supervised daemon (relevant if we ever need to coexist with it; not an
+ integration surface).
+- **No lifecycle-hook surface** documented or evident; no transcript store
+ documented. Conversation data appears cloud-side (leveldb holds UI state
+ only). Capture options collapse to model-discretion via MCP tools — same
+ as RFC #878's closed-app bucket.
+
+## 3. xAI official desktop app
+
+Not verified. No local install; no official docs fetched. Grok Build CLI
+(xAI's coding CLI) is a *different* product — ai-memory already supports it
+(`install-mcp --client grok`, `install-hooks --agent grok`, repo
+`docs/mcp-install.md`). Keep the two separate in any plan.
+
+## Open-source status
+
+Grok Bot: **closed** (Cursor). No repo to clone. Only external artifact
+inspected: the AUR PKGBUILD + local binary/asar strings.
+
+## Sources
+
+- <https://aur.archlinux.org/packages/grok-bot-bin> (PKGBUILD, cursor.com
+ download URL, comments)
+- Local: `/opt/Grok Bot/resources/app.asar` (strings), `~/.grokbot/`,
+ `~/.config/Grok Bot/`, `/usr/share/applications/grok-bot.desktop`
+- ai-memory repo: `docs/mcp-install.md` (Grok Build CLI section — separate
+ product)
diff --git a/docs/desktop/installer-and-coexistence.md b/docs/desktop/installer-and-coexistence.md
new file mode 100644
index 00000000..fa06d02c
--- /dev/null
+++ b/docs/desktop/installer-and-coexistence.md
@@ -0,0 +1,152 @@
+# Installer & CLI coexistence for a desktop companion (research)
+
+> Research for RFC #878. What it takes to ship an `ai-memory` tray app that
+> a non-developer can install, and how it coexists with an existing
+> `ai-memory` CLI install without breaking it. Verified sources: Tauri v2
+> docs (fetched 2026-10), the existing Swift companion
+> (`companions/ai-memory-macos/README.md`), ai-memory repo layout
+> (`packaging/`, `crates/ai-memory-cli/src/server_profiles*`, hook runner
+> layout observed locally), and well-known behavior of Docker Desktop /
+> Tailscale (pattern references — deep docs not fetched, treat as
+> directional).
+
+## 1. Tray-app implementation options
+
+### Option A — Tauri v2 (recommended baseline)
+
+- **Tray**: first-class `tray-icon` feature (`TrayIconBuilder`, menus,
+ events). Linux note: tray mouse-move/enter events unsupported, but icon +
+ context menu work (<https://v2.tauri.app/learn/system-tray/>).
+- **Bundling the Rust binary**: sidecar/external-binary support
+ (<https://v2.tauri.app/develop/sidecar/>) — the tray app can embed the
+ exact pinned `ai-memory` release binary.
+- **Desktop-app table stakes as plugins**: `single-instance` (avoid two
+ trays), `autostart` (login launch), `updater` (signed updates),
+ deep-linking (`ai-memory://`) (<https://v2.tauri.app/plugin/>).
+- **Packaging matrix from one toolchain** — official distribute targets:
+ Linux deb / rpm / AppImage / AUR / Flathub / Snap, macOS DMG + app bundle
+ (+ pkg), Windows installer (NSIS/MSI) + Microsoft Store; per-OS signing
+ guides (<https://v2.tauri.app/distribute/>).
+- Cost: webview-based UI (small), Rust core is fine; maturities match our
+ Rust-first stack.
+
+### Option B — pure Rust GUI: egui + `tray-icon`
+
+- `tray-icon` (tauri-apps org, <https://docs.rs/tray-icon>) + `muda` menus;
+ egui for the settings window. Lightest stack, no webview, one binary.
+- Cost: we own everything Tauri gives for free — single-instance, updater,
+ signing/packaging pipelines, deep links. Only worth it if the UI stays
+ trivial (menu + one settings pane) — which the Swift companion's scope
+ suggests it might.
+
+### Option C — keep Swift companion + add a Linux counterpart
+
+- macOS: `companions/ai-memory-macos` already works (ships runtime, governs
+ LaunchAgent, data dir survives app replacement, philosophy: "wrapper, not
+ a second operator console").
+- Linux: a counterpart would duplicate the service governance (systemd user
+ unit — templates already exist in `packaging/systemd/`) with a GTK/libadw
+ or Tauri menu. Two codebases for one product; the existing companion
+ explicitly defers notarization/Homebrew cask, so it has not reached the
+ non-dev bar yet either.
+
+**Recommendation (research-level):** Tauri v2 for a cross-platform tray
+companion that *subsumes* the Swift companion's role over time, keeping the
+Swift app as the macOS-first path until parity; OR B if we commit to a
+minimal menu-only surface. Decision point for RFC follow-up, not settled
+here.
+
+## 2. Packaging per OS (end-user installers)
+
+| OS | Formats | Notes |
+| --- | --- | --- |
+| macOS | `.dmg` (drag-install), `.pkg`, Homebrew cask | Gatekeeper: Developer ID + hardened runtime + notarize/staple (RFC #878 cost analysis stands); Swift companion currently ships un-notarized |
+| Windows | NSIS or MSI (WiX) via Tauri; winget | MSIX optional; AppContainer path quirks for Claude Desktop config already handled by `install-mcp`; Authenticode signing (RFC #878: SignPath Foundation free for OSS) |
+| Linux | `.deb`, `.rpm`, AppImage; AUR (we already ship AUR assets in `packaging/aur/`); Flatpak is **problematic** (sandbox vs loopback server + hook execution into arbitrary agent configs — needs portal work; defer) | systemd user unit from `packaging/systemd/`; sysusers/tmpfiles assets exist |
+
+## 3. Coexistence with the existing CLI (the hard constraints)
+
+Ground truth from the repo/local machine:
+
+- **Data dir** holds wiki + SQLite + `config.toml` + spool + models:
+ `~/.local/share/ai-memory` (Linux), `~/Library/Application Support/ai-memory`
+ (macOS — the Swift companion's documented default), `%LOCALAPPDATA%`
+ (Windows). The desktop app MUST detect and reuse it, never fork a second
+ one silently.
+- **One writer, one server**: ai-memory's SQLite is single-writer-actor by
+ design (repo invariants #2, #9). Two server processes on one data dir is
+ forbidden — so the tray app's first job is *detection*, not spawning:
+ 1. Probe the configured/default server (`GET /admin/status` on the port
+ from `config.toml` / default `127.0.0.1:49374`).
+ 2. Check the **`server_profiles` registry** (CLI:
+ `crates/ai-memory-cli/src/server_profiles.rs` — named profiles with
+ url + project roots + token, used by hooks via `--server-url`). On this
+ machine the hooks point at a LAN server (`--server-url
+ http://192.168.0.90:49374`) — the desktop app must respect that
+ instead of assuming localhost.
+ 3. Only if no reachable server: offer (a) start bundled server as a
+ managed service (LaunchAgent/systemd user unit/Startup task — reuse
+ `packaging/` templates), or (b) connect to remote with URL+token.
+- **Hooks are decoupled from app bundles already**: hooks installed by
+ ai-memory invoke `~/.local/share/ai-memory/native-runner/ai-memory` (the
+ native-runner copy inside the data dir; verified in local
+ `~/.claude/settings.json` and `~/.codex/hooks.json`). Replacing a desktop
+ app bundle therefore never rewrites hooks or breaks capture — preserve
+ this invariant: **the tray app must not move or duplicate the
+ native-runner path**; at most refresh it with the user's consent.
+- **Version independence**: bundled binary (in the .app/resources) and any
+ system CLI can differ. Rules: the *server* version wins schema truth
+ (migrations run under the single-writer server); the tray UI talks HTTP
+ only (`/admin/status`, `/web`, `/api/v1`) so it degrades gracefully
+ against older/newer servers; `ai-memory` CLI on PATH is never overwritten
+ by the app (no symlink stomping).
+- **Auto-wiring MCP configs**: reuse `install-mcp` per client (it already
+ knows claude-desktop incl. MSIX paths, codex, antigravity-cli, zed, grok,
+ …). The desktop app should call the same library code, show a checklist
+ of detected apps, and write configs idempotently (preserve unrelated
+ servers — existing behavior).
+
+## 4. The "desktop users don't know Docker" constraint
+
+ai-memory today is a self-contained Rust binary (bundled SQLite, vendored
+libgit2) — **Docker is already optional** (`docs/install.md` ships native
+packages + systemd). The tray app completes that story:
+
+- Default path: bundled binary + local data dir + loopback bind + zero
+ auth (single-user posture from `docs/install.md`).
+- Team/remote path: URL + bearer token (AI_MEMORY_AUTH_TOKEN) fields in the
+ tray settings → written to `server_profiles` so hooks and MCP installs
+ point at the same remote.
+- Anti-goal: the tray app becoming an admin console. Keep the Swift
+ companion's rule — open `/web` and the config file; don't duplicate.
+
+## 5. Comparable tools (pattern reference)
+
+- **Docker Desktop**: bundles engine + CLI, manages the VM/service, and
+ exposes `docker` CLI on PATH from the app bundle; starting the app is
+ starting the service. Pattern to copy: tray == service governor, CLI
+ stays first-class. Pattern to avoid: version-lock pain when the desktop
+ app lags the CLI.
+- **Tailscale**: menu-bar app + `tailscaled` system service + `tailscale`
+ CLI; on macOS the daemon ships inside the .app with a launchd agent, and
+ the CLI is a symlink into the bundle. Pattern to copy: explicit
+ "connected/backend state" tray affordance; CLI/daemon version skew
+ tolerated by protocol.
+- **Raycast**: tray-first launcher without a bundled background *service*
+ — mostly useful as UI scope reference (menu + extensions), not service
+ coexistence.
+
+(These are well-known public behaviors; not re-verified against docs in
+this pass — directional only.)
+
+## 6. Open questions
+
+1. Tauri vs egui decision (scope of UI: menu-only vs settings panes vs
+ conversation viewer).
+2. Flatpak feasibility (portals for background service + host file access
+ to agent configs) or skip Flatpak and ship deb/rpm/AppImage/AUR only.
+3. Auto-update channel policy for the bundled server binary vs CLI-managed
+ installs (Tauri updater is for the app; the embedded `ai-memory`
+ sidecar needs its own update story).
+4. Whether the tray app should also own `install-hooks` for detected
+ agents (it is the natural place for the "enable capture" toggle).
diff --git a/docs/desktop/plan.md b/docs/desktop/plan.md
new file mode 100644
index 00000000..9ced7aaa
--- /dev/null
+++ b/docs/desktop/plan.md
@@ -0,0 +1,105 @@
+# Desktop support — phased plan (research output, reconciled with RFC #878)
+
+> This file reconciles RFC #878 (github.com/akitaonrails/ai-memory#878) with
+> the findings in this directory (2026-10-07). Nothing here is scheduled
+> work; each phase lists what would need to change and where the risk sits.
+
+## What the research changed vs the RFC
+
+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
+ (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.
+
+## 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.
+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).
+
+## Phase 1 — Antigravity IDE capture parity (smallest new-code step)
+
+The research's best new target — not the RFC's `.mcpb`:
+
+- Ensure `install-hooks --agent antigravity-cli` output also satisfies the
+ IDE (same global file; verify; add `.agents/hooks.json` workspace install
+ option).
+- Map hook payloads → `/hook` observations: agent kind `antigravity`
+ (covers CLI+IDE+2.0), session = `conversationId`, cwd =
+ `workspacePaths[0]`, tool events from PreToolUse/PostToolUse; session
+ boundaries from PostInvocation/Stop flushes (no SessionStart/End events).
+- Tests: payload-mapping unit tests against the documented schema
+ (camelCase fields; `<app_data_dir>` variants per surface).
+
+## Phase 2 — scope & dedup polish for desktop-originated sessions
+
+- Decide scratch-workspace routing: single `desktop/claude-cowork` 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
+ id-level dedup layer is needed.
+- Optional metadata enrichment from
+ `~/.config/Claude/claude-code-sessions/**/local_*.json` (titles,
+ account/org) — strictly optional, closed-app internals.
+
+## Phase 3 — explicit capture for hookless surfaces (RFC Phase 1, adjusted)
+
+- Tool-surface change (23-tool count, MEMORY_INSTRUCTIONS/SNIPPET_BODY,
+ prompt-surface regression tests, adversarial boundary test) for an
+ explicit capture tool the model calls on apps without hooks (Claude Chat
+ tab, Grok Bot, hosted ChatGPT chat). Scoping per RFC: fixed
+ `personal/desktop-chat` (optionally per-app) since no cwd exists.
+- Grok Bot MCP entry format: only worth reverse-engineering on demand.
+
+## Phase 4 — the non-dev tray installer (RFC Phase 2, refined)
+
+- Tauri v2 vs egui decision, packaging matrix, and the coexistence rules in
+ `installer-and-coexistence.md` (detect-before-spawn server governance,
+ `server_profiles` inheritance, native-runner path stability, no PATH
+ stomping).
+- Signing/notarization costs as in RFC #878 (unchanged).
+
+## Explicitly deferred / rejected
+
+- Hosted-ChatGPT plugin (remote MCP to a user-run server): real but a new
+ distribution surface; needs published-plugin review requirements
+ (<https://developers.openai.com/plugins/deploy/app-review>) — separate
+ RFC if demand appears.
+- Watching Zed's native-agent database: fragile, version-locked; ACP
+ agents already give us capture for free.
+- Building on `~/.claude/sessions/<pid>.json` cc-socks IPC or Grok Bot's
+ local-exec daemon: closed-app internals, unstable by definition.
+- A session-id mapping/alias table keyed on desktop `local_*` ids: not
+ needed given one-id sessions; revisit only if Anthropic splits ids.
+
+## Open questions (research-level, blocking nothing)
+
+1. Codex-in-app hook firing (Phase 0 verification).
+2. Antigravity IDE honoring global hooks (Phase 0 verification).
+3. `.mcpb` vs plugins for Claude Desktop one-click (re-check docs).
+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.)
diff --git a/docs/desktop/zed.md b/docs/desktop/zed.md
new file mode 100644
index 00000000..168d5400
--- /dev/null
+++ b/docs/desktop/zed.md
@@ -0,0 +1,83 @@
+# Zed (research notes)
+
+> Research for RFC #878. Zed is open source (cloned to
+> `~/Projects/_desktop-research/zed-research`); docs at zed.dev. Local
+> install verified (`~/.config/zed/settings.json`).
+
+## Product shape
+
+Open-source editor (Rust) with an Agent Panel supporting three agent paths
+(<https://zed.dev/docs/ai/mcp>):
+
+1. **Zed Agent** (native, built-in)
+2. **External Agents** via **ACP** (Agent Client Protocol,
+ <https://agentclientprotocol.com/>) — e.g. Gemini CLI, Claude Code,
+ codex-acp, opencode. **Verified locally**: the user's
+ `~/.config/zed/settings.json` configures `agent_servers`:
+ `opencode` (`type: "registry"`), `codex-acp`, `claude-acp`.
+3. **Terminal Threads** — native CLIs run in Zed's terminal with their own
+ config (so a `claude`/`codex` TUI inside Zed behaves exactly like the
+ CLI: ai-memory hooks fire as usual, keyed by cwd).
+
+## MCP client support
+
+- Config: **`context_servers`** in the Zed `settings.json` (Linux
+ `~/.config/zed/settings.json` — verified locally; macOS
+ `~/Library/Application Support/Zed/settings.json` per Zed docs/ai-memory
+ `docs/mcp-install.md`). Entries:
+ - local stdio: `{"command", "args", "env"}`
+ - remote: `{"url", "headers"}`; OAuth flow prompts when no
+ `Authorization` header is configured.
+- GUI: Settings → AI → MCP Servers → Add Server (local/remote).
+- Extensions: MCP servers can ship as Zed extensions
+ (<https://zed.dev/docs/extensions/mcp-extensions>).
+- Feature coverage: **Tools + Prompts only** ("Discovery, Sampling,
+ Elicitation, etc." not yet supported); handles
+ `notifications/tools/list_changed` (same zed.dev/docs/ai/mcp page).
+- MCP servers configured in Zed are **forwarded to External Agents over
+ ACP**; external agents may also read their own native MCP config
+ (configuration boundaries documented at
+ <https://zed.dev/docs/ai/external-agents>).
+- Tool permissions: `agent.tool_permissions.default`
+ (`confirm`/`allow`/`deny`), per-tool rules keyed `mcp:<server>:<tool>`.
+
+ai-memory status today: `install-mcp --client zed` exists (repo
+`docs/mcp-install.md`); remote HTTP ai-memory servers fit the `url` entry.
+
+## Lifecycle hooks / capture surface
+
+- **No push hooks in Zed itself** (no equivalent of Claude Code/Codex/Antigravity
+ hook files). Auto-capture must come from the *agent*, not the editor:
+ - Terminal Threads and ACP external agents (claude-acp / codex-acp /
+ opencode) fire **their own** hooks — ai-memory captures those sessions
+ through the existing per-agent hook integrations (agent kind reported by
+ the CLI; session lands in the project keyed by cwd, which Zed sets to
+ the workspace dir).
+ - The native Zed Agent has no hook surface; its threads are stored in
+ Zed's own database (source: `crates/agent`, `crates/agent_ui` in the
+ clone; a poll/watch importer would be per-version fragile — same bucket
+ as RFC #878 option (c), only if demand appears).
+
+## Session identity / dedup
+
+Zed does not sit in the session path: session ids are whatever the
+underlying agent (Zed Agent / ACP server / terminal CLI) mints. For ACP
+agents, ai-memory sees the agent's own session id via its hooks; a Zed
+ACP-run claude-acp session and a terminal `claude` session in the same repo
+are two sessions in the same project — cwd-keyed project scope already
+merges them correctly. No Zed-specific dedup work identified.
+
+## Open-source status
+
+**Open** — github.com/zed-industries/zed (cloned, shallow, for crate
+layout: `crates/agent`, `crates/agent_servers`, `crates/agent_settings`,
+`crates/language_extension` etc.).
+
+## Sources
+
+- <https://zed.dev/docs/ai/mcp>, <https://zed.dev/docs/ai/external-agents>,
+ <https://zed.dev/docs/extensions/mcp-extensions>,
+ <https://agentclientprotocol.com/>
+- Local: `~/.config/zed/settings.json` (`agent_servers` with opencode /
+ codex-acp / claude-acp), `/usr/share/applications/dev.zed.Zed.desktop`
+- Clone: `~/Projects/_desktop-research/zed-research`