feat: npx claude-mem — unified CLI with 13 IDE integrations

[thedotmack]

Summary

• npx claude-mem becomes the single install command, replacing the old git-clone installer
• Supports 13 AI coding tools across 4 integration tiers: hook-based (Gemini CLI, Windsurf), plugin-based (OpenCode, OpenClaw), MCP-based (Copilot CLI, Antigravity, Goose, Crush, Roo Code, Warp), and transcript-based (Codex CLI)
• npm package size reduced from 146MB to 2MB by excluding native binaries and node_modules
• Old installer/ directory removed (16 files, -5431 lines) — fully replaced by src/npx-cli/

What's New

NPX CLI (src/npx-cli/)

• npx claude-mem install — interactive IDE multi-select with auto-detection
• npx claude-mem install --ide <name> — direct IDE setup
• npx claude-mem start/stop/restart/status — worker management (delegates to Bun)
• npx claude-mem search <query> — search memory from terminal
• npx claude-mem update/uninstall/version — lifecycle management
• Pure Node.js install path (no Bun required for installation)

IDE Integrations

IDE	Type	Stars/Users
Claude Code	Plugin (existing)	~25% market
Cursor	Hooks (existing)	Large
Gemini CLI	Hooks (6 of 11 events)	~95k stars
OpenCode	Plugin (interceptor + bus events)	~110k stars
Windsurf	Hooks (5 post-action events)	~1M users
Codex CLI	Transcript watching	Growing (OpenAI)
OpenClaw	Plugin (pre-built)	~196k stars
Copilot CLI	MCP	20M+ combined
Antigravity	MCP
Goose	MCP
Crush	MCP
Roo Code	MCP
Warp	MCP

Build Pipeline

• 6 esbuild targets: worker-service, mcp-server, context-generator, npx-cli, openclaw, opencode-plugin
• .npmignore excludes Bun binary (60MB) and plugin/node_modules (379MB)

Test plan

• npm run build produces all 6 targets
• node dist/npx-cli/index.js --version prints 10.5.2
• node dist/npx-cli/index.js --help shows all commands
• npm pack --dry-run shows ~2MB package size
• No bun:sqlite in dist/npx-cli/index.js
• All 13 IDEs appear in --help output
• Install flow copies plugin without git clone or build-from-source

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This PR successfully replaces the old git-clone installer with a modern NPX CLI and adds support for 13 AI coding tools. The implementation is comprehensive and well-structured.

Key Improvements:

• Unified installation: npx claude-mem install replaces the old curl-pipe-bash method
• Massive size reduction: npm package reduced from 146MB to 2MB by excluding binaries and node_modules via .npmignore
• 13 IDE integrations: Covers hook-based (Gemini CLI, Windsurf), plugin-based (OpenCode, OpenClaw), MCP-based (6 tools), and transcript-based (Codex CLI) approaches
• Pure Node.js install: No Bun required for installation commands, only for runtime
• Old installer removed: 16 files and 5,431 lines cleanly removed from installer/ directory

Architecture:

• 6 esbuild targets in build pipeline (worker-service, mcp-server, context-generator, npx-cli, openclaw, opencode-plugin)
• IDE-specific installers with deep merge strategies to preserve existing user configs
• Interactive IDE multi-select with auto-detection
• Comprehensive lifecycle commands (install, update, uninstall, start, stop, restart, status, search)

Documentation:

• README and installation docs updated with new npx method
• Old install.sh redirects users to new method
• Clear distinction between npm library install vs plugin setup

The code quality is high with proper error handling, cross-platform support, and well-organized modular structure. All test plan items appear achievable.

Confidence Score: 4/5

• Safe to merge after verifying the test plan items - the changes are well-structured and primarily additive
• This is a comprehensive refactoring with 45 files changed, but the changes are well-organized and low-risk. The old installer is cleanly removed, the new NPX CLI is properly structured with good error handling, and IDE integrations use deep merge strategies to preserve user configs. The build pipeline correctly produces 6 targets, and .npmignore properly excludes heavy binaries. The main risk is ensuring all 6 build targets work correctly and the 13 IDE integrations install without issues, but the code quality and structure give high confidence.
• Verify scripts/build-hooks.js produces all 6 targets correctly and test the installation flow for at least 2-3 IDEs from different integration tiers

Important Files Changed

Filename	Overview
src/npx-cli/index.ts	New CLI entry point with clean command routing and help text, correctly separates install vs runtime commands
src/npx-cli/commands/install.ts	Comprehensive installer that copies pre-built plugin, registers marketplace, handles IDE-specific setup, and runs smart-install
src/npx-cli/commands/runtime.ts	Runtime command delegation to Bun worker service, with proper guards and error handling for missing dependencies
package.json	Updated bin entry points to dist/npx-cli, files array correctly includes distributed artifacts
.npmignore	Comprehensive exclusions for source code, development files, and heavy binaries to achieve 2MB target package size
scripts/build-hooks.js	Build pipeline extended with 6 esbuild targets including npx-cli, OpenClaw, and OpenCode plugin bundles
src/services/integrations/GeminiCliHooksInstaller.ts	Hook-based integration with deep merge strategy for 6 Gemini CLI events, includes GEMINI.md context injection
src/services/integrations/OpenClawInstaller.ts	Copies pre-built OpenClaw plugin to ~/.openclaw/extensions, registers in openclaw.json with config merging
src/services/integrations/McpIntegrations.ts	Unified MCP config writer for 6 IDEs (Copilot CLI, Antigravity, Goose, Crush, Roo Code, Warp) with context injection
README.md	Updated quick start to show npx claude-mem install as primary method with clear npm install caveat
docs/public/installation.mdx	Comprehensive installation docs updated with npx method, IDE detection, and post-install verification steps

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    Start([npx claude-mem install]) --> DetectIDEs[Detect Installed IDEs]
    DetectIDEs --> Prompt{Interactive?}
    Prompt -->|Yes| MultiSelect[Multi-select IDE Prompt]
    Prompt -->|No| DefaultIDE[Default: claude-code]
    MultiSelect --> CopyPlugin[Copy Plugin Files to Marketplace]
    DefaultIDE --> CopyPlugin
    
    CopyPlugin --> Cache[Cache Plugin Version]
    Cache --> RegisterMarket[Register in known-marketplaces.json]
    RegisterMarket --> RegisterPlugin[Register in installed-plugins.json]
    RegisterPlugin --> EnablePlugin[Enable in Claude Settings]
    EnablePlugin --> NpmInstall[Run npm install in Marketplace]
    NpmInstall --> SmartInstall[Run smart-install for Bun/uv]
    
    SmartInstall --> IDESetup{IDE Type?}
    
    IDESetup -->|Claude Code| CC[Already Registered]
    IDESetup -->|Hook-Based| Hooks[Gemini CLI / Windsurf]
    IDESetup -->|Plugin-Based| Plugins[OpenCode / OpenClaw]
    IDESetup -->|MCP-Based| MCP[6 MCP Tools]
    IDESetup -->|Transcript| Transcript[Codex CLI]
    
    Hooks --> HookInstall[Install Hooks in settings.json + Context MD]
    Plugins --> PluginInstall[Copy Pre-built Plugin + Register Config]
    MCP --> MCPInstall[Write MCP Config + Context MD]
    Transcript --> TranscriptInstall[Configure Transcript Watching]
    
    CC --> Complete[Installation Complete]
    HookInstall --> Complete
    PluginInstall --> Complete
    MCPInstall --> Complete
    TranscriptInstall --> Complete
    
    Complete --> Runtime[Runtime Commands Available]
    Runtime --> Start[npx claude-mem start/stop/restart/status]
    Runtime --> Search[npx claude-mem search query]
    Runtime --> Update[npx claude-mem update/uninstall]

Loading

_{Last reviewed commit: cc17786}

[claude]

PR Review: feat: npx claude-mem - unified CLI with 13 IDE integrations

This is a substantial, well-structured refactor. The DX improvement (146MB to 2MB package, single install command) is significant, and the architecture cleanly separates the pure-Node install path from the Bun-dependent runtime path. A few issues worth addressing before merge:

---

Bugs / Correctness

1. writeJsonFileAtomic is not atomic (src/npx-cli/utils/paths.ts)

The function calls writeFileSync directly, which is not atomic. A crash or power loss mid-write can corrupt ~/.claude/settings.json, installed_plugins.json, or known_marketplaces.json -- files that Claude Code itself reads at startup. The name creates a false sense of safety.

Fix: write to a temp file first, then renameSync to the target (rename is atomic on the same filesystem).

2. update command does not actually update (src/npx-cli/index.ts L99-103)

update/upgrade just calls runInstallCommand() -- identical to install. A user running npx claude-mem update on an old cached npx installation will silently re-install the same version. Consider checking npm view claude-mem version first, or at minimum printing: run npx claude-mem@latest install to upgrade.

3. Missing await on runtime commands (src/npx-cli/index.ts L123-138)

runStartCommand(), runStopCommand(), runRestartCommand(), and runStatusCommand() are called without await inside an async function. They are currently void, so no runtime error today, but this will silently swallow any future async errors.

---

Architecture / Code Quality

4. Shared utilities imported from CursorHooksInstaller.ts

GeminiCliHooksInstaller.ts, WindsurfHooksInstaller.ts, and McpIntegrations.ts all import helpers (findBunPath, findWorkerServicePath, findMcpServerPath) directly from CursorHooksInstaller.ts. Why does the Gemini installer depend on a Cursor file? These should live in a shared module such as src/services/integrations/shared.ts.

5. Cursor shows in IDE selection but installation is unimplemented (src/npx-cli/commands/install.ts L79-83)

A user who selects Cursor only sees a vague coming soon log after completing the install flow. Either mark Cursor as disabled in the clack multi-select (clack supports disabled on options), or remove it from the list until implemented.

6. readJsonFileSafe / writeJsonFileAtomic use untyped any (src/npx-cli/utils/paths.ts)

McpIntegrations.ts already has the better pattern with readJsonSafe generic. Apply the same generic approach to the shared path utilities.

7. copyPluginToMarketplace copies the entire package root (src/npx-cli/commands/install.ts)

The filter only skips .git and .tgz. The .npmignore rules do not apply to cpSync -- it copies everything on disk. Consider an allowlist filter (plugin/, dist/, package.json, openclaw/) to avoid copying dev artifacts.

---

Security

8. Shell injection pattern in isCommandInPath (src/npx-cli/commands/ide-detection.ts L36-41)

All callers use hardcoded strings, so no immediate risk. But using a template literal with execSync is unsafe for any future caller that might pass user-controlled input. Prefer spawnSync with an args array instead of a shell string.

---

Minor

9. npmPackageRootDirectory() path assumption (src/npx-cli/utils/paths.ts L83-90)

Assumes the bundled entry point lives at dist/npx-cli/index.js (2 levels up from import.meta.url). If the output path changes, the install silently copies the wrong directory. An assertion that plugin/ exists at the resolved root would make failures obvious.

10. No install rollback -- if a step fails after the file copy but before registration completes, the user is left in a partially-installed state. A try/finally that cleans up the marketplace dir on error would be safer.

---

What Is Working Well

• The @clack/prompts UX is clean and consistent throughout
• Deep-merge pattern for IDE hook configs (Gemini, Windsurf) correctly preserves user config
• Separating install-time (pure Node) from runtime (Bun) is the right architectural call
• The .npmignore strategy for package size reduction is well thought out
• CodexCliInstaller.ts correctly uses transcript watching without adding hooks -- the anti-pattern comment is a nice touch

Overall a solid feature. Priority items before merge: (1) non-atomic writes to Claude config files, (2) update command behavior, (4) CursorHooksInstaller coupling.

Generated with Claude Code

[Chriscross475]

This PR is too large to review effectively (4902 additions, 5437 deletions, 40+ files changed). It mixes multiple architectural concerns that should be reviewed separately:

Concerns:

1. Cannot thoroughly verify correctness across 13 new IDE integrations
2. Build pipeline changes (6 esbuild targets) mixed with installer removal
3. npm packaging strategy completely overhauled in same PR
4. High risk of introducing bugs that would be hard to bisect
5. Difficult to revert if issues arise in production

Recommendation:
Break this into smaller PRs:

• PR 1: npm packaging changes (.npmignore, package.json files array, bin entry)
• PR 2: Remove old installer/, add npx-cli/ foundation
• PR 3: Add IDE integrations in groups (hooks-based, plugin-based, MCP-based)
• PR 4: Build pipeline updates
• PR 5: Documentation updates

Each can be reviewed thoroughly, tested independently, and reverted if needed.

If you need to ship urgently:
At minimum, provide:

• Test results for all 13 IDE integrations
• npm pack dry-run output showing 2MB package size
• Verification that old git-clone install path still works during transition period
• Rollback plan if npx install fails for users

[thedotmack]

I don't have to ship immediately, we can test systematically, and do a pre release channel

[runzexia]

OpenCode Integration Findings

Hey @thedotmack — I've been testing the OpenCode integration from this branch (feature/npx) and wanted to share some findings that might be useful. I got it working end-to-end but had to make several adjustments.

1. Plugin Hook API Mismatch

The plugin at src/integrations/opencode-plugin/index.ts uses nested object hooks:

hooks: {
  tool: {
    execute: {
      after: (input, output) => { ... }
    }
  }
}

The current @opencode-ai/plugin SDK (v1.2.23) expects flat string keys:

hooks: {
  "tool.execute.after": (input, output) => { ... },
  "chat.message": (input, output) => { ... }
}

The nested form silently fails — hooks never fire, no data is captured.

2. Event Handler Signature Change

The plugin uses:

event(eventName: string, payload: any)

The current SDK uses:

event({ event }: { event: Event })

Where Event is an SDK object with .type ("session.created", "message.updated", etc.) and .properties (containing info with Session/Message objects). The old string-based event names don't match what the SDK dispatches.

3. claude_mem_search Tool Crashes OpenCode

The plugin registers a claude_mem_search tool using raw JSON schema for parameters:

parameters: {
  type: "object",
  properties: { query: { type: "string" } }
}

OpenCode v4 requires Zod schemas for tool parameters. Loading the plugin with raw JSON schema causes OpenCode to crash on startup. Since the MCP server already exposes search, this tool registration can be removed from the plugin entirely.

4. Worker Hardcoded OpenRouter URL

The worker binary has a hardcoded URL: https://openrouter.ai/api/v1/chat/completions. For users with custom LLM proxies or non-OpenRouter providers, this means the worker will always hit OpenRouter regardless of what's configured in settings.json. Would be great to have this respect the configured provider/base URL.

5. UI Files Missing from Manual Install

When installing binaries manually (worker, mcp-server, context-generator), the plugin/ui/ directory (viewer.html, viewer-bundle.js, fonts, images) isn't included. The worker serves static files from {dataDir}/ui/ but that directory doesn't exist, resulting in 500 errors when accessing the web viewer. The npx flow probably handles this, but worth documenting for manual installs.

---

What's working after fixes: Plugin captures session events → worker processes observations via LLM → observations stored in DB → searchable via MCP tool. The full pipeline is functional once the above issues are addressed.

Happy to share the rewritten plugin code if helpful. Great work on claude-mem — the architecture is solid once the integration layer is aligned with the current SDK.

[thedotmack]

@runzexia please do submit the code! Thank you so much for working that out! :)

[thedotmack]

@runzexia let me know if you have issues but i think if you fork the repo and work out of this PR you should be able to submit a PR to THIS PR? or the branch? IDK how this would work here 😭