Desktop and IDE integrations

Supported approach

An experimental Chrome capture extension lives on the wip/chrome-extension branch. It uses a separately paired local HTTP capture API to save pages and selected text. Gmail and document integrations are coming soon. It is not an automatic host adapter or a mailbox synchronization connector.

Use local stdio MCP as the default integration contract. Register an absolute interpreter path with -m imprint and explicit PYTHONPATH and IMPRINT_DATA_DIR. The client owns the MCP process; Qdrant is a shared local daemon. Installation and client registration are separate operations: imprint bootstrap provisions the backend, and imprint setup <target> registers a detected client.

imprint setup all is the default setup path. It probes hosts, skips absent ones and prepares the backend once per invocation. It does not establish that any client actually connected: verify tools inside the client after reload/restart.

Host	Current adapter	Automatic behavior and limits
Claude Code	setup.go	CLI registration, permissions, managed rules and lifecycle hooks. Verify with claude mcp list and /mcp; hook behavior needs a live client fixture.
Claude Desktop	setup_claude_desktop.go	JSON registration; OS/MSIX paths and WSL bridge supported in source. Guidance comes through MCP instructions. Conversation ingestion uses explicit exports. One server serves every chat, with no project folder: chats use workspace.unassigned or name a workspace per call (workspaces).
Codex CLI / IDE	setup_codex.go	TOML MCP registration, managed AGENTS block, SessionStart/Stop hooks. Paths now honor CODEX_HOME. imprint learn and the Stop hook’s conversation import read current rollouts: session_meta and turn_context working directories, and response_item messages. Config does not imply hooks are trusted or every transcript revision is parsed.
Current ChatGPT desktop	setup_chatgpt_desktop.go	When detected, register through the shared Codex profile. Versions/accounts without local MCP support need an upgrade or in-app capability check. WSL detection reports the Windows app but requires native Windows setup; it does not write Linux interpreter paths into the Windows profile. No public unauthenticated proxy is required.
Cursor	setup_cursor.go	MCP JSON, managed rule and event adapters. Test hook names, matchers and payloads against actual installed versions. imprint learn reads agent conversations from ~/.cursor/projects/*/agent-transcripts; a conversation’s folder name counts as its working directory only when exactly one existing directory has it (ADR 0052).
GitHub Copilot (VS Code, CLI, JetBrains)	setup_copilot.go	VS Code 1.143+ (Copilot harness), Copilot runtime 1.0.x: every surface shares the Copilot home (COPILOT_HOME, else ~/.copilot). Setup registers mcpServers.imprint (type: stdio, tools: ["*"]) in mcp-config.json, which VS Code’s Local harness also discovers; writes a managed block into copilot-instructions.md; and owns hooks/imprint.json with PascalCase SessionStart (top-level additionalContext) and Stop (imports transcript_path), quoted for PowerShell on Windows and bash elsewhere. VS Code’s user mcp.json is no longer written; disconnect removes the old entry and the generated prompts file. imprint learn reads session-state/*/events.jsonl: session context events are the evidence, sessions are keyed by their whole id, and skill, subagent and autopilot messages are left out. The Local harness’s own chat store is not learned (ADR 0057). Validated against fixtures, not a live logged-in Copilot.
Cline	setup_cline.go	Cline 4 (extension 4.0+, CLI 3.0+): every surface reads CLINE_MCP_SETTINGS_PATH, else <data dir>/settings/cline_mcp_settings.json, and the global rules directory <CLINE_DIR>/rules, where setup writes imprint.md. Imprint’s entry is kept flat with no nested transport, which Cline would read first; its other settings stay. Cline’s hooks receive no transcript, so none are wired: conversations arrive through imprint learn or the dashboard’s Learn action, which read its sessions directory. A session’s manifest cwd and workspace_root are its evidence; imported, subagent and pre-SDK sessions are not learned (ADR 0056). Validated against fixtures, not a live Cline.
OpenCode	setup_opencode.go	OpenCode 1.2+ and 2.x, on every platform under XDG directories (OPENCODE_CONFIG_DIR, else $XDG_CONFIG_HOME/opencode, default ~/.config/opencode). Setup registers mcp.imprint (type: local, command array, environment) in the global opencode.json, writes imprint.md beside it and lists it in "instructions". It does not write AGENTS.md, because creating that file would stop OpenCode reading ~/.claude/CLAUDE.md. It also writes plugins/imprint.js, which starts the detached learner when a session goes idle (session.status idle, or session.idle). OpenCode keeps sessions in SQLite ($XDG_DATA_HOME/opencode/opencode*.db): imprint learn and the plugin’s learner export each top-level session to <data>/opencode_sessions/…/<id>.jsonl and learn that; the session’s directory is its working-directory evidence (ADR 0124). Validated against fixtures built from OpenCode’s schema, not a live OpenCode.
OpenClaw	setup_openclaw.go	Existing registration adapter; review its tool-specific semantics before claiming parity.

Official OpenAI documentation describes shared MCP configuration for ChatGPT desktop, Codex CLI and the IDE extension, including local stdio, and user/project configuration scopes. This supersedes the old adapter’s advice to publish a local server through an SSE proxy. See OpenAI MCP documentation.

Codex hooks have a trust lifecycle and support more events than the adapter’s April 2026 comments suggest. Transcript layout is explicitly unstable; JSON output and recursion prevention matter for Stop hooks. Treat the adapter’s narrower coverage as an implementation limitation. See OpenAI hook documentation.

Claude Code supports client-managed stdio registration with explicit scope. Use the host CLI where it provides safe configuration updates. See Claude Code MCP documentation. VS Code’s Copilot harness reads the Copilot home’s mcp-config.json; its Local harness discovers that file beside its own mcp.json (servers); see VS Code MCP documentation and GitHub’s hooks reference.

Windows installation with WSL clients

The Windows installer can register detected default-user Claude Code, Codex, Cursor, GitHub Copilot and Cline profiles in selected WSL distributions. A Cursor registration only lets imprint learn read the conversations Remote-WSL writes there; it writes nothing into the profile. Copilot’s agent host and Cline run inside the distribution, so their registrations write the launcher, MCP entry and instructions into the distribution’s Copilot home or Cline home, and Copilot’s hooks file. imprint wsl setup --distribution <name> --target claude-code|cursor|codex|copilot|cline also supports an explicit Linux user and alternate profile directories. The selected client runs a private imprint-wsl stdio launcher against the existing Windows interpreter and data directory, and the home gets the imprint command, the same bridge’s CLI, in ~/.local/bin unless another imprint is there (ADR 0091). Rules/hooks use the same bridge, including transcript-path translation; workspace approvals remain mandatory. imprint learn reads each registered profile’s conversations in the same path context (ADR 0037). This does not expose the dashboard/Qdrant listener or provision a second Linux runtime.

Registration is opt-in, backed up and idempotent. The adapter verifies that Windows-executable interoperability works, preserves unrelated MCP/settings/hooks/rules, and supports explicit removal. Client trust/restart and the existing Codex transcript limitations remain separate. Custom shell startup files are not sourced to discover environment overrides. See installation, ADR 0026, and native validation.

Automation improvements, in order

1. Extend read-only doctor: basic imprint doctor --json [--probe-mcp] is implemented for Python/dependencies/dashboard, primary Codex registration, Qdrant readiness and timed MCP discovery. Extend it to imprint doctor --json reporting executable, architecture, managed interpreter, dependency versions, model availability, storage health, detected client/version, actual registration and a timed MCP initialize/list-tools probe. Distinguish missing, registered, connected and degraded states.
2. Plan and apply: add imprint integrations list, plan --target, apply and remove. Backups and preservation are implemented in the current helpers; add a preview of exactly the Imprint-owned diff; preserve unrelated settings, comments and custom timeouts. Offer user or project scope explicitly. A detected directory is insufficient evidence of the right profile.
3. Capability adapters: share a backend descriptor and keep per-client config schema, hook events, instructions, transcript normalization, trust and reload guidance separate. Record a tested client-version range rather than hard-coded historical claims.
4. Stable launch command: move client registrations toward a small imprint mcp launcher resolving the current writable runtime. This avoids stale interpreter paths after updates. It must emit protocol traffic only on stdout and startup diagnostics on stderr, with a bounded startup time.
5. Watcher: opt-in source refresh with debouncing, ignore rules, stale-file hashes and visible queue state. Do not silently index every repository or export. Sessions already follow their project’s workspace (ADR 0072).
6. Client packages: evaluate Claude desktop extensions and Codex/ChatGPT plugin packages after the underlying launch and health contracts are stable. A package can improve discovery and configuration, but cannot bypass client trust or turn local-only transport into cloud access.
7. IDE extension only when useful: a small extension can expose connection health, project selection, file-change refresh and quick search. Retrieval should continue to use MCP so each IDE does not acquire a separate memory implementation.

Validation contract

Each adapter needs golden fixtures with unrelated existing configuration, a second run proving idempotence, relocation/update, disable/uninstall, spaces and Unicode, alternate home/profile paths, and malformed/permission-denied files. Add a real MCP handshake test and live hook payload fixtures per supported client. Exports remain explicit user-selected imports; avoid claims of passive desktop conversation capture.

Manual verification: run imprint setup <target>, reload the host, confirm imprint tools appear, search a uniquely indexed fixture, store/retrieve one decision, then confirm removal preserves other servers and memories. Execute this only in disposable profiles during automated tests.

Current configuration guarantees

JSON edits preserve custom server options/environment. Owned hook edits retain other handlers, including handlers sharing an event/matcher. TOML edits validate input/output and preserve unrelated sections, custom options and nested server tables; formatting within an edited owned stanza can normalize. Changed files receive a private .imprint-<timestamp>.bak before an atomic replacement. Invalid or unsupported syntax fails without overwriting the original. JSONC and concurrent edit protection are still open. See ADR 0006.

imprint doctor --json --probe-mcp initializes the installed server and discovers tools without loading an embedding model or editing profiles. A registered entry is not proof of a host-side trusted connection. The diagnostic currently checks the primary Codex profile, not every client/profile. Missing venv is an actionable failure; a daemon not yet started or a client not detected is distinguished from a broken check.

Required client registration, managed rule and hook write failures exit nonzero rather than continuing to a setup-success banner. Missing optional clients still skip, and advisory optional runtime features can degrade with a warning. Installer completion therefore reflects required configuration failures.

Reminders, not gates

Claude Code (and Claude Code inside WSL) and Cursor get a hook that reminds an agent, once per session, to prefer searching Imprint before it reads or greps files, if the session has not searched yet. It never refuses the tool, so automated agents (Cursor’s Bugbot, scripted cursor-agent runs) and sessions where Imprint is unavailable carry on. Claude Code shows the reminder beside the read’s result (PreToolUse additionalContext); Cursor, whose preToolUse hook can only allow or deny, gets it after the result (postToolUse additional_context). Setup removes the earlier Cursor preToolUse gate (ADR 0142).

Tool calls clients get slightly wrong

Agents call Imprint’s tools with arguments other memory servers take. The server runs such a call instead of failing it:

• An argument a tool does not take is left out, and the result names it. store keeps a text one in the note as a line (Reason: …), since what an agent says beside a memory belongs to it; a number such as importance is dropped.
• store takes tags as comma-separated text or as a list.

A client starts Imprint’s server once and keeps that process for as long as it runs, so after imprint update it still runs the old version. The first tool result after the installed files change says so; restart the client, or reload its MCP servers (Cursor: Settings → MCP), to use the new one.