One command per agent.

Claude Code

poppy setup claude-code

Writes the Poppy MCP server entry to ~/.claude.json and installs the lifecycle hooks (SessionStart, UserPromptSubmit, PreToolUse, SessionEnd, PostCompact) in ~/.claude/settings.json, plus a managed primer block in ~/.claude/CLAUDE.md. Consolidation runs from the SessionEnd hook when you exit a session. The primer teaches the agent to call remember mid-session.

Cursor

poppy setup cursor

Writes ~/.cursor/mcp.json with the Poppy stdio entry and installs the lifecycle hooks in ~/.cursor/hooks.json, both under $CURSOR_HOME if you have set it. No primer file. Pass --no-hooks to register the MCP server without the hooks.

Codex (OpenAI Codex CLI)

poppy setup codex

Writes the stdio entry to ~/.codex/config.toml, installs capture hooks in ~/.codex/hooks.json, and writes a primer to ~/.codex/AGENTS.md. Codex requires a one-time trust approval before hooks run: start Codex in the TUI once and approve them. All three paths follow $CODEX_HOME if you have set it. Headless codex exec skips untrusted hooks silently, and editing a hook command later changes its hash and needs approval again. Pass --no-hooks to skip the hooks.

VS Code

poppy setup vscode

Writes the Poppy entry to the VS Code user-profile MCP file: ~/Library/Application Support/Code/User/mcp.json on macOS, ~/.config/Code/User/mcp.json on Linux, and %APPDATA%/Code/User/mcp.json on Windows, or $POPPY_VSCODE_MCP_CONFIG if you point it elsewhere. MCP only, no primer.

Windsurf

poppy setup windsurf

Writes ~/.codeium/windsurf/mcp_config.json with the Poppy entry. MCP only, no Cascade primer.

Gemini CLI

poppy setup gemini

Adds the Poppy MCP server to ~/.gemini/settings.json, leaving your other settings in that file alone. MCP only, no primer.

Copilot CLI

poppy setup copilot-cli

Writes ~/.copilot/mcp-config.json and installs the primer at ~/.copilot/copilot-instructions.md, the file Copilot CLI loads on its own. Both paths follow $COPILOT_HOME if you have set it.

Pi (badlogic/pi-mono)

poppy setup pi

Pi has no native MCP. Poppy uses the pi-mcp-adapter shim and writes the adapter entry to ~/.pi/agent/mcp.json. The primer goes to ~/.pi/agent/AGENTS.md. Both follow $PI_CODING_AGENT_DIR if you have set it.

Goose (Block)

poppy setup goose

Writes the extensions.poppy block to ~/.config/goose/config.yaml and installs the primer at ~/.config/goose/.goosehints.

Hermes Agent (Nous Research)

poppy setup hermes-agent

Hermes has no MCP. Poppy installs a native memory-provider plugin at ~/.hermes/plugins/poppy/, sets memory.provider: poppy in ~/.hermes/config.yaml, and writes managed guidance into ~/.hermes/SOUL.md. All three follow $HERMES_HOME if you have set it.

Claude Desktop

poppy setup claude-desktop

Writes the MCP entry to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%/Claude/claude_desktop_config.json (Windows). Run poppy setup claude-desktop --print-instructions to print the primer, then paste it into Settings → General → Profile → Instructions yourself. poppy build mcpb builds the Claude Desktop Extension bundle (.mcpb) if you prefer to install Poppy that way.

Trags (cloud sync)

poppy setup trags

Not an agent: this is the cloud-sync onboarding. The CLI opens a browser to a device-code flow at trags.ai/setup. You authorize the device once and from then on every remember propagates to the cloud. See Cloud sync for what happens after.

Doctor checks

After running any poppy setup <agent>, run:

poppy doctor

The output prints an MCP line for each client whose config file it finds, skipping the ones it does not, plus hook lines for Claude Code, Cursor, and Codex, primer lines for Codex, Copilot CLI, Pi, Goose, and Hermes, and the auto-capture state with the last capture seen. Those MCP checks cover Claude Code, Claude Desktop, Cursor, Windsurf, Codex, Copilot CLI, and Pi. VS Code and Gemini CLI are not among them yet, so verify those two in the client itself. When something is off, doctor prints the exact remediation command.

Removing an integration

There is no uninstall flag yet. --no-hooks only skips installing hooks, it does not remove hooks already on disk, and poppy daemon uninstall removes the shared daemon service rather than any client wiring. Removal is by hand:

• The poppy entry in the client’s MCP config, at the path listed for that agent above.
• The marker-fenced primer block, for the agents that get one.
• The hook entries, for Claude Code, Cursor, and Codex only: five in ~/.claude/settings.json, five in ~/.cursor/hooks.json, and four in ~/.codex/hooks.json.
• If you set $CLAUDE_CONFIG_DIR, every Claude Code path above moves with it: the MCP entry, the hooks, and the CLAUDE.md primer all live under that directory instead of ~/.claude. Setup honours it, so removal has to as well.
• For Hermes, three things rather than two: the plugin directory ~/.hermes/plugins/poppy/, the managed block in ~/.hermes/SOUL.md, and the memory.provider key in ~/.hermes/config.yaml. Set that key back to whichever provider you used before, or delete the line to fall back to the Hermes default. poppy setup hermes-agent overwrote the old value in place and kept no record of it, so you will have to remember what it was. Deleting only the primer leaves Poppy as the active memory provider.

Every hook Poppy installs runs a command of the form poppy hook <event>, which is how the installer recognises its own entries, so that is the string to search for. Delete those entries and leave the rest of the file as it is. Poppy merges into these files rather than owning them, so any hooks you added yourself sit alongside its and should stay. If Poppy’s were the only entries, the whole hooks.json can go. Your memories are untouched either way.