# Installer Streamline — Eliminate 30s Silent Dead Air

**Goal:** Move all heavy install work (Bun/uv install, `bun install` in plugin cache) into the `npx claude-mem install` flow with a visible spinner. Make hooks runtime-only — never installers.

**Net effect:**
- `smart-install.js` runs in normal Claude Code lifecycle: 3 → 0 (or 1 via `npx claude-mem repair` after `claude plugin update`)
- 30s silent dead air → visible spinner during `npx`
- `npx claude-mem repair` becomes the canonical recovery entry point
- ~420 lines of code deleted (smart-install.js × 2 + tests + docs)

**Out of scope:** `bun-runner.js` deletion (independent rework with Windows/stdin verification needs — ship later).

---

## Phase 0 — Documentation Discovery (already complete)

These facts came from a discovery agent + direct file reads. Each implementation phase below cites them by line number; do not re-derive.

### Allowed APIs / patterns to copy

| Item | Location | What to copy |
|---|---|---|
| NPX command dispatcher | `src/npx-cli/index.ts:39–141` | Manual `switch (command)` on `process.argv.slice(2)`. Each case dynamic-imports its handler. |
| `install` case (template for `repair`) | `src/npx-cli/index.ts:46–52` | `const { runInstallCommand } = await import('./commands/install.js'); await runInstallCommand({ ide: ideValue });` |
| Plugin cache dir helper | `src/npx-cli/utils/paths.ts:32–34` | `pluginCacheDirectory(version)` → `~/.claude/plugins/cache/thedotmack/claude-mem/{version}/` |
| `.install-version` marker readers | `src/services/context/ContextBuilder.ts:36,45` and `src/services/worker/BranchManager.ts:173,228` | These read/delete the marker. Marker schema (`{ version, bun, uv, installedAt }`) MUST be preserved. |
| `clack` task pattern | `src/npx-cli/commands/install.ts:604–664` | `runTasks([{ title, task: async (message) => { … return 'Done OK' } }])` |

### Anti-patterns / API methods that DO NOT exist (avoid inventing)

- There is no existing `version-check.js` helper in `plugin/scripts/`. Phase 4 must create it.
- `package.json#files` already globs `plugin/scripts/*.js` (line 50), so deleting `plugin/scripts/smart-install.js` requires no `package.json` change.
- `scripts/smart-install.js` and `plugin/scripts/smart-install.js` are **both source files** kept in sync manually — there is no build step that copies one to the other. Both must be deleted in Phase 5.
- `runSmartInstall()` (install.ts:325–345) shells `node smart-install.js`. After Phase 1 you can call the new module directly — do NOT shell out.
- The `claude plugin install` exec at install.ts:113 has **only one caller** in the entire repo. Safe to remove.

### File inventory used by this plan

| File | Lines | Disposition |
|---|---|---|
| `src/npx-cli/commands/install.ts` | 761 | Edited heavily (Phase 2) |
| `src/npx-cli/index.ts` | 147 | One case added (Phase 3) |
| `plugin/hooks/hooks.json` | 93 | Setup hook command rewritten, SessionStart smart-install entry deleted (Phase 4) |
| `scripts/smart-install.js` | 264 | DELETED (Phase 5) |
| `plugin/scripts/smart-install.js` | ≈264 | DELETED (Phase 5) |
| `tests/smart-install.test.ts` | 310 | DELETED (Phase 5) |
| `tests/plugin-scripts-line-endings.test.ts` | 33 | One array entry removed (Phase 5) |
| `plugin/scripts/version-check.js` | NEW | CREATED (Phase 4) |
| `src/npx-cli/install/setup-runtime.ts` | NEW | CREATED (Phase 1) |
| Docs (`docs/public/*.mdx`, `docs/architecture-overview.md`) | misc | Light edit (Phase 6) |

---

## Phase 1 — Create `src/npx-cli/install/setup-runtime.ts`

**What to implement:** Port the smart-install.js logic to a TypeScript module that takes a target directory parameter (so it can install into the plugin cache dir, not just the marketplace dir). Three exported functions plus internal helpers.

**File to create:** `src/npx-cli/install/setup-runtime.ts`

**API surface (these names are used by Phase 2 and Phase 3 — do not rename):**

```ts
export async function ensureBun(): Promise<{ bunPath: string; version: string }>;
export async function ensureUv(): Promise<{ uvPath: string; version: string }>;
export async function installPluginDependencies(targetDir: string, bunPath: string): Promise<void>;
export function readInstallMarker(targetDir: string): { version: string; bun?: string; uv?: string; installedAt?: string } | null;
export function writeInstallMarker(targetDir: string, version: string, bunVersion: string, uvVersion: string): void;
export function isInstallCurrent(targetDir: string, expectedVersion: string): boolean;
```

**Reference implementation to port from:** `scripts/smart-install.js:1–264`. Map old → new:

| smart-install.js | setup-runtime.ts |
|---|---|
| `getBunPath()` / `isBunInstalled()` / `installBun()` (lines 42–152) | private helpers consumed by `ensureBun()` |
| `getUvPath()` / `isUvInstalled()` / `installUv()` (lines 77–194) | private helpers consumed by `ensureUv()` |
| `needsInstall()` (lines 196–205) | `isInstallCurrent()` + `readInstallMarker()` |
| `installDeps()` (lines 207–226) | `installPluginDependencies(targetDir, bunPath)` — accepts target dir as parameter |
| `verifyCriticalModules()` (lines 228–246) | private helper called inside `installPluginDependencies` |
| `MARKER` constant (line 32) | derive inside each function: `join(targetDir, '.install-version')` |
| Top-level `try { … }` (lines 248–264) | DELETE — caller orchestrates |

**Key behavioral differences from smart-install.js:**
- All functions take `targetDir` as a parameter (was a top-level `ROOT` constant).
- `ensureBun()` / `ensureUv()` return their version strings rather than logging — caller decides what to display.
- All functions throw on failure with descriptive `Error.message`. The `clack` `runTasks` wrapper in Phase 2 catches and renders.
- `console.error` calls in install/uninstall paths become structured: throw a single `Error` with the manual install instructions in the message body.
- Marker schema is preserved exactly (`{ version, bun, uv, installedAt }`) so existing readers in `ContextBuilder.ts:36` and `BranchManager.ts:173,228` continue to work.

**Verification checklist:**
- [ ] `bun build src/npx-cli/install/setup-runtime.ts --target=node` succeeds (or whatever the project's TS check command is — confirm via `package.json#scripts`)
- [ ] Marker file format is byte-identical to smart-install.js output (write a marker, diff against a marker written by the old code)
- [ ] `grep -rn "ROOT" src/npx-cli/install/setup-runtime.ts` returns nothing — no top-level constants

**Anti-pattern guards:**
- ❌ Do not invent a `bunInstall.ts` or `uvInstall.ts` split — keep all three in one file. They share helper code (paths, version probing).
- ❌ Do not import from `plugin/scripts/smart-install.js` — it gets deleted in Phase 5.
- ❌ Do not change the marker schema. Existing readers depend on `{ version }` field.

---

## Phase 2 — Rework `src/npx-cli/commands/install.ts`

**What to implement:** Drop `needsManualInstall` gating (always run copy/register/enable for every IDE), add a new unconditional "Setting up runtime" task before `setupIDEs`, neuter the claude-code `execSync` shell-out, delete `runSmartInstall()`, and add a `runRepairCommand()` export.

**File to edit:** `src/npx-cli/commands/install.ts`

### Edit 2A — Add import for setup-runtime (top of file, after other imports)

Insert after line 10 (after the `ensureWorkerStarted` import):

```ts
import {
  ensureBun,
  ensureUv,
  installPluginDependencies,
  writeInstallMarker,
  isInstallCurrent,
} from '../install/setup-runtime.js';
```

### Edit 2B — Delete `runSmartInstall()` function

**Delete lines 325–345** (the entire `function runSmartInstall(): boolean { … }` block).

### Edit 2C — Drop `needsManualInstall` gating, ungate the runTasks block

**Line 589** currently reads:
```ts
const needsManualInstall = selectedIDEs.some((id) => id !== 'claude-code');
```
**Delete line 589.** Update line 593's `if (needsManualInstall) {` to just `{` (or unwrap the block — preferred). The `runTasks` block at lines 604–664 now runs unconditionally.

**Within that runTasks block:** delete the "Setting up Bun and uv" task entry (lines 656–663). Replace its slot with the new "Setting up runtime" task (Edit 2D).

### Edit 2D — Insert "Setting up runtime" task

Replace the deleted "Setting up Bun and uv" task (lines 656–663) with:

```ts
{
  title: 'Setting up runtime (first install can take ~30s)',
  task: async (message) => {
    message('Checking Bun…');
    const { version: bunVersion } = await ensureBun();
    message('Checking uv…');
    const { version: uvVersion } = await ensureUv();
    const cacheDir = pluginCacheDirectory(version);
    if (!isInstallCurrent(cacheDir, version)) {
      message('Installing plugin dependencies…');
      const { bunPath } = await ensureBun();
      await installPluginDependencies(cacheDir, bunPath);
      writeInstallMarker(cacheDir, version, bunVersion, uvVersion);
    }
    return `Runtime ready (Bun ${bunVersion}, uv ${uvVersion}) ${pc.green('OK')}`;
  },
},
```

Place this AFTER the "Installing dependencies" (npm install) task — same ordering position the deleted task occupied.

### Edit 2E — Neuter the claude-code shell-out in `setupIDEs`

**Lines 110–123 currently:**
```ts
case 'claude-code': {
  try {
    execSync(
      'claude plugin marketplace add thedotmack/claude-mem && claude plugin install claude-mem',
      { stdio: 'inherit' },
    );
    log.success('Claude Code: plugin installed via CLI.');
  } catch (error: unknown) {
    console.error('[install] Claude Code plugin install error:', …);
    log.error('Claude Code: plugin install failed. Is `claude` CLI on your PATH?');
    failedIDEs.push(ideId);
  }
  break;
}
```

**Replace with:**
```ts
case 'claude-code': {
  log.success('Claude Code: plugin registered (cache + settings written by npx).');
  break;
}
```

The cache dir, marketplace registration, plugin registration, and `enabledPlugins` flag have all been written by the (now ungated) runTasks block before `setupIDEs` is called. `claude plugin install` was duplicating that work and triggering the silent Setup hook — both reasons to drop it.

### Edit 2F — Add `runRepairCommand()` export

After `runInstallCommand()` (after line 761), append:

```ts
export async function runRepairCommand(): Promise<void> {
  const version = readPluginVersion();
  const cacheDir = pluginCacheDirectory(version);

  if (isInteractive) {
    p.intro(pc.bgCyan(pc.black(' claude-mem repair ')));
  } else {
    console.log('claude-mem repair');
  }
  log.info(`Version: ${pc.cyan(version)}`);

  await runTasks([
    {
      title: 'Setting up runtime',
      task: async (message) => {
        message('Checking Bun…');
        const { version: bunVersion } = await ensureBun();
        message('Checking uv…');
        const { version: uvVersion } = await ensureUv();
        message('Reinstalling plugin dependencies…');
        const { bunPath } = await ensureBun();
        await installPluginDependencies(cacheDir, bunPath);
        writeInstallMarker(cacheDir, version, bunVersion, uvVersion);
        return `Runtime ready (Bun ${bunVersion}, uv ${uvVersion}) ${pc.green('OK')}`;
      },
    },
  ]);

  if (isInteractive) {
    p.outro(pc.green('claude-mem repair complete.'));
  } else {
    console.log('claude-mem repair complete.');
  }
}
```

`runRepairCommand` always runs the install (no `isInstallCurrent` short-circuit) — the user invoked `repair` because something is wrong, so don't gate on the marker.

**Verification checklist:**
- [ ] `grep -n "needsManualInstall" src/npx-cli/commands/install.ts` returns nothing
- [ ] `grep -n "runSmartInstall" src/npx-cli/commands/install.ts` returns nothing
- [ ] `grep -n "claude plugin install" src/npx-cli/commands/install.ts` returns nothing
- [ ] `grep -n "claude plugin marketplace add" src/npx-cli/commands/install.ts` returns nothing
- [ ] `runRepairCommand` is exported and TypeScript compiles
- [ ] `runInstallCommand` still exports the same `InstallOptions` shape (Phase 3 needs it untouched)

**Anti-pattern guards:**
- ❌ Do not delete `runNpmInstallInMarketplace()` — it's still needed for the marketplace dir copy step (other IDEs use that dir).
- ❌ Do not delete `copyPluginToMarketplace()` — non-claude-code IDEs read from `marketplaceDirectory()`.
- ❌ Do not delete the `if (alreadyInstalled)` overwrite-confirm block (lines 538–562) — user-facing UX preserved.

---

## Phase 3 — Wire `npx claude-mem repair`

**What to implement:** Add a `repair` case to the npx-cli command dispatcher.

**File to edit:** `src/npx-cli/index.ts`

### Edit 3A — Add `repair` case

In the `switch` block (lines 39–141), copy the `install` case pattern from lines 46–52 and adapt:

```ts
case 'repair': {
  const { runRepairCommand } = await import('./commands/install.js');
  await runRepairCommand();
  break;
}
```

Place it adjacent to the `install` case for discoverability.

### Edit 3B — Help text update (if applicable)

If `src/npx-cli/index.ts` has a help/usage block (look for `case 'help':` or default case), add `repair` to the list of commands with description: `Repair claude-mem runtime (re-runs Bun/uv setup and bun install in plugin cache).`

**Verification checklist:**
- [ ] `npx claude-mem repair --help` (after build) shows the command
- [ ] `npx claude-mem repair` runs `runRepairCommand` end to end on a corrupted cache (delete `.install-version` then run; should reinstall)
- [ ] Help/usage output (if it exists) lists `repair`

**Anti-pattern guards:**
- ❌ Do not add CLI flag parsing for `repair` (no flags needed).
- ❌ Do not duplicate the `runRepairCommand` body in `index.ts` — dynamic import only.

---

## Phase 4 — Strip smart-install from hooks; add `version-check.js`

**What to implement:** Replace the Setup hook's `node smart-install.js` call with a fast version-marker check. Delete the SessionStart smart-install hook entry entirely.

### Edit 4A — Create `plugin/scripts/version-check.js`

**File to create:** `plugin/scripts/version-check.js` (new)

```js
#!/usr/bin/env node
import { existsSync, readFileSync } from 'fs';
import { join, dirname } from 'path';
import { fileURLToPath } from 'url';

function resolveRoot() {
  if (process.env.CLAUDE_PLUGIN_ROOT) {
    const root = process.env.CLAUDE_PLUGIN_ROOT;
    if (existsSync(join(root, 'package.json'))) return root;
  }
  try {
    const scriptDir = dirname(fileURLToPath(import.meta.url));
    const candidate = dirname(scriptDir);
    if (existsSync(join(candidate, 'package.json'))) return candidate;
  } catch {}
  return null;
}

const ROOT = resolveRoot();
if (!ROOT) process.exit(0);

try {
  const pkg = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf-8'));
  const markerPath = join(ROOT, '.install-version');
  if (!existsSync(markerPath)) {
    console.error('claude-mem: runtime not yet set up — run: npx claude-mem repair');
    process.exit(0);
  }
  const marker = JSON.parse(readFileSync(markerPath, 'utf-8'));
  if (marker.version !== pkg.version) {
    console.error(`claude-mem: upgraded to v${pkg.version} — run: npx claude-mem repair`);
  }
} catch {
  console.error('claude-mem: install marker unreadable — run: npx claude-mem repair');
}
process.exit(0);
```

**Behavior:**
- Sub-100ms (two synchronous file reads + JSON.parse + string compare).
- Always exits 0 (non-blocking) per the project's exit-code strategy in CLAUDE.md.
- Stderr message tells the user exactly what to run if a mismatch is detected.

### Edit 4B — Rewrite Setup hook command in `plugin/hooks/hooks.json`

**Lines 4–15** — replace the existing Setup hook command. Current command ends with `node "$_R/scripts/smart-install.js"`. Change it to `node "$_R/scripts/version-check.js"`. Everything before that (PATH export, `_R` resolution, cygpath) stays.

Concretely: the only change to line 11 is the trailing `smart-install.js` → `version-check.js`.

### Edit 4C — Delete SessionStart smart-install entry in `plugin/hooks/hooks.json`

**Lines 17–40** — the SessionStart hook array currently has THREE hook entries:
1. `node "$_R/scripts/smart-install.js"` (lines 21–26) — DELETE this entire entry
2. `node "$_R/scripts/bun-runner.js" "$_R/scripts/worker-service.cjs" start` (lines 27–32) — KEEP
3. `node "$_R/scripts/bun-runner.js" "$_R/scripts/worker-service.cjs" hook claude-code context` (lines 33–38) — KEEP

After edit, the SessionStart `hooks` array has 2 entries instead of 3.

**Verification checklist:**
- [ ] `cat plugin/hooks/hooks.json | jq '.hooks.Setup[0].hooks[0].command' | grep version-check.js` succeeds
- [ ] `cat plugin/hooks/hooks.json | jq '.hooks.SessionStart[0].hooks | length'` returns `2`
- [ ] `grep -c "smart-install" plugin/hooks/hooks.json` returns `0`
- [ ] `node plugin/scripts/version-check.js` exits 0 in <500ms (time it)
- [ ] On a fresh checkout (no `.install-version` marker), version-check stderr says "run: npx claude-mem repair"

**Anti-pattern guards:**
- ❌ Do not change the exit code from 0 — Windows Terminal tab management depends on it (CLAUDE.md exit-code strategy).
- ❌ Do not call out to Bun in version-check.js — Node-only, since this runs before we know Bun exists.
- ❌ Do not add fancy logic (semver compare, partial recovery). String equality is correct: any version mismatch warrants a repair.

---

## Phase 5 — Delete dead code

**What to implement:** Delete smart-install source files and update tests.

### Edit 5A — Delete files

```
rm scripts/smart-install.js
rm plugin/scripts/smart-install.js
rm tests/smart-install.test.ts
```

### Edit 5B — Trim `tests/plugin-scripts-line-endings.test.ts`

**Line 12 (the `SHEBANG_SCRIPTS` array):** remove the `'smart-install.js'` entry. Keep the rest of the array intact.

If the array becomes empty after the removal, also remove the entry — but per discovery report it has multiple entries, so just delete the one line.

### Edit 5C — Add new test for setup-runtime module (optional but recommended)

**File to create:** `tests/setup-runtime.test.ts`

Cover:
- `readInstallMarker` returns `null` for missing file
- `writeInstallMarker` produces a JSON object matching the smart-install.js schema (`{ version, bun, uv, installedAt }`)
- `isInstallCurrent` returns `false` for missing marker, `false` for version mismatch, `true` for match
- (Skip Bun/uv install integration tests — those need a sandbox and fall outside this PR's scope.)

If you skip this, document why in the PR description.

**Verification checklist:**
- [ ] `find . -name "smart-install*" -not -path "*/node_modules/*"` returns no results
- [ ] `grep -rn "smart-install" tests/` returns no results
- [ ] `npm test` (or whatever the project uses) passes
- [ ] If `tests/setup-runtime.test.ts` was added, it passes

**Anti-pattern guards:**
- ❌ Do not delete `tests/plugin-scripts-line-endings.test.ts` entirely — it tests other scripts too.
- ❌ Do not delete `tests/bun-runner.test.ts` — bun-runner.js stays in this PR.

---

## Phase 6 — Update docs

**What to implement:** Sweep documentation to reflect the new install flow.

### Edit 6A — `docs/architecture-overview.md:36`

Update reference to smart-install. New copy: "On first install, `npx claude-mem install` sets up Bun and uv globally and runs `bun install` in the plugin cache. The Setup hook then runs a sub-100ms version check on every Claude Code startup; if the plugin was upgraded externally, the user is prompted to run `npx claude-mem repair`."

### Edit 6B — `docs/public/configuration.mdx:139,163` and `docs/public/development.mdx:42`

Replace any mention of smart-install behavior with the version-check + repair model. Two-sentence patches; preserve surrounding context.

### Edit 6C — `docs/public/hooks-architecture.mdx` (11 references)

This is the largest doc change. Walk each reference (lines 77, 103, 119, 127, 432, 695–696, 703 per discovery report). Update text describing the Setup hook to say it runs `version-check.js` (sub-100ms) instead of `smart-install.js`. Update SessionStart description to reflect 2 entries (worker start + context fetch) instead of 3.

### Edit 6D — `docs/public/architecture/` references (lines 149, 193)

Same pattern — replace smart-install lifecycle description with the npx-installer + version-check model.

### Edit 6E — Skip CHANGELOG

CLAUDE.md says: "No need to edit the changelog ever, it's generated automatically." Don't touch it.

### Edit 6F — Skip docs/reports/

Those are historical incident reports. Do not retroactively edit them — they describe past behavior.

**Verification checklist:**
- [ ] `grep -rn "smart-install" docs/public/` returns no results
- [ ] `grep -rn "smart-install" docs/architecture-overview.md` returns no results
- [ ] (Optional) Render docs locally via Mintlify dev server and visually scan the architecture page

**Anti-pattern guards:**
- ❌ Do not edit `docs/reports/*.md` — those are dated incident reports, leave them alone.
- ❌ Do not edit CHANGELOG.md.

---

## Phase 7 — Build, test, manual verify

**What to implement:** End-to-end validation. This phase is run by the implementer before opening the PR.

### Edit 7A — Build

```bash
npm run build-and-sync
```

This must succeed. If TypeScript fails on the new `setup-runtime.ts`, fix in place.

### Edit 7B — Test suite

```bash
npm test
```

Must be green. Likely failures to anticipate:
- `plugin-scripts-line-endings.test.ts` if the `'smart-install.js'` entry was missed in Phase 5
- Any test that imports from `scripts/smart-install.js` (discovery report says only `tests/smart-install.test.ts`, which Phase 5 deletes)

### Edit 7C — Manual fresh-install verification

1. On a clean machine (or after `rm -rf ~/.claude/plugins/marketplaces/thedotmack ~/.claude/plugins/cache/thedotmack ~/.claude-mem`):
   ```bash
   npx claude-mem install
   ```
   Confirm:
   - Spinner says "Setting up runtime (first install can take ~30s)"
   - No silent dead air
   - Worker starts at the end
2. Open Claude Code in any project. Confirm:
   - Setup hook fires fast (<200ms total)
   - SessionStart fires fast (no smart-install delay)
   - No "claude plugin install" output
3. Simulate a stale install:
   ```bash
   rm ~/.claude/plugins/cache/thedotmack/claude-mem/<version>/.install-version
   ```
   Open a new Claude Code session. Confirm version-check.js prints the "run: npx claude-mem repair" message to stderr.
4. Run repair:
   ```bash
   npx claude-mem repair
   ```
   Confirm spinner runs through Bun/uv check + bun install + marker write, then exits clean.

### Edit 7D — Commit and open PR

Per the PR creation flow in the user's outer task. Don't auto-merge; the user wants a review loop.

**Verification checklist:**
- [ ] `npm run build-and-sync` exits 0
- [ ] `npm test` exits 0
- [ ] Manual fresh install completes with visible spinner, no silent dead air
- [ ] Setup hook fires <200ms after rebuild
- [ ] `npx claude-mem repair` runs end-to-end

**Anti-pattern guards:**
- ❌ Do not skip the manual verification — the whole point of this PR is UX (eliminating dead air). Type checks won't catch a regression.
- ❌ Do not bump the version — version bump is handled separately by the version-bump skill.

---

## Summary of file changes

| Type | Path | Phase |
|---|---|---|
| Created | `src/npx-cli/install/setup-runtime.ts` | 1 |
| Edited | `src/npx-cli/commands/install.ts` | 2 |
| Edited | `src/npx-cli/index.ts` | 3 |
| Created | `plugin/scripts/version-check.js` | 4 |
| Edited | `plugin/hooks/hooks.json` | 4 |
| Deleted | `scripts/smart-install.js` | 5 |
| Deleted | `plugin/scripts/smart-install.js` | 5 |
| Deleted | `tests/smart-install.test.ts` | 5 |
| Edited | `tests/plugin-scripts-line-endings.test.ts` | 5 |
| Created | `tests/setup-runtime.test.ts` (optional) | 5 |
| Edited | `docs/architecture-overview.md` | 6 |
| Edited | `docs/public/configuration.mdx` | 6 |
| Edited | `docs/public/development.mdx` | 6 |
| Edited | `docs/public/hooks-architecture.mdx` | 6 |
| Edited | `docs/public/architecture/*.md` | 6 |

Estimated diff: **+250 / −500 lines** (net deletion).