claudetools/session-logs/2026-06-02-howard-laptop-claude-setup-fix.md

Session Log — 2026-06-02 — Howard Laptop Claude Setup / Crash Fix

User

• User: Howard Enos (howard)
• Machine: Howard-Home
• Role: tech

Session Summary

Howard reported that the claudesetup.bat he was sent no longer works on his laptop: Claude crashes when it opens. It worked previously but has been broken for many weeks. The goal was to produce a new setup batch file that correctly sets up ClaudeTools on the laptop. Work was performed on Howard's desktop (Howard-Home); the deliverable is to be manually moved to the laptop.

Investigation of the existing bootstrap package (projects/msp-tools/howard-bootstrap/) and the repo's startup configuration identified the root cause. The repo's git-tracked .mcp.json instructs Claude to launch a grepai MCP server via C:\claudetools\grepai.exe mcp-serve on every startup in the claudetools folder. grepai.exe is gitignored (a 23 MB binary that never ships via clone/pull) and was missing on the laptop. With the binary absent, Claude waits on an MCP server that never initializes, producing the observed "hangs then closes with no error" — and only when launched from the claudetools folder, since .mcp.json is project-scoped. Howard confirmed the diagnosis from the laptop: dir C:\claudetools\grepai.exe returned PathNotFound.

A new installer was written at projects/msp-tools/howard-bootstrap/claude-laptop-setup.bat. The first version was a full setup/repair (prereqs, repo+vault clone, git identity/remote, identity.json, submodules, grepai handling, robust launcher). Per Howard's follow-up ("just have it install the needed programs so it will run"), it was trimmed to a focused fix: install required programs (git, Node.js, Claude Code, Python, SOPS), apply the grepai MCP fix, and create a robust desktop launcher. The grepai fix writes disabledMcpjsonServers: ["grepai"] into C:\claudetools\.claude\settings.local.json when the binary is absent (verified disabledMcpjsonServers is a real Claude Code settings key by grepping the installed claude.exe).

Finally, per Howard's request to bundle the binary, grepai.exe was copied into the bootstrap folder and the bat was wired to install it to C:\claudetools\ from alongside the script. When the binary is present, the bat leaves the grepai MCP server enabled (full semantic search); the disable path remains only as a fallback. The bootstrap folder is now a self-contained package to be moved to the laptop together (the binary is gitignored and will not travel via sync).

Key Decisions

• Diagnosed the crash as a project-scoped MCP startup hang, not a broken Claude install or corrupted global config — based on Howard's report that Claude runs fine from a normal folder but not from the claudetools folder.
• Verified disabledMcpjsonServers is a valid Claude Code settings key by grepping the installed claude.exe binary, rather than trusting memory, since the entire fix depends on it.
• Used machine-local .claude/settings.local.json (gitignored) for the disable flag so the fix does not affect other machines via the shared, git-tracked .mcp.json.
• Generated settings.local.json as a clean known-good file (env + optional disable key) instead of attempting a JSON merge in batch; bypassPermissions in the tracked settings.json makes the per-machine permissions allow-list redundant, so clobbering it (with a .bak backup) is safe.
• Trimmed the installer from full-setup to programs+fix per Howard's instruction, while keeping the grepai fix because installing programs alone does not stop the hang.
• Bundled grepai.exe in the bootstrap folder so the laptop gets full semantic search, with the bat copying it into place; kept the disable path as a fallback when the binary is not shipped.
• Added a "re-run after install" flow: when git/node/python are freshly installed (not yet on PATH), the bat exits and asks for a second run rather than failing.
• Launcher rewritten to stay open on a non-zero exit (if errorlevel 1 ... pause) so any future startup error is visible instead of the window vanishing.

Problems Encountered

• Batch + Windows PowerShell 5.1 quoting/JSON pitfalls: PS 5.1 ConvertTo-Json unwraps single-element arrays to scalars, which would corrupt disabledMcpjsonServers. Avoided by writing literal JSON with batch echo rather than serializing.
• Delayed-expansion ! hazard: under EnableDelayedExpansion, ! in echoed [!] markers would be eaten. Resolved by dropping delayed expansion (not needed — no in-block var reads) and using ASCII markers ([OK], [WARNING], etc.).
• grepai.exe is gitignored, so it cannot be delivered to the laptop via git. Resolved by bundling it in the bootstrap folder for manual transfer and documenting that it must move together with the .bat.

Configuration Changes

• Created: projects/msp-tools/howard-bootstrap/claude-laptop-setup.bat — new focused laptop installer/fix.
• Added: projects/msp-tools/howard-bootstrap/grepai.exe — 23 MB binary copied from C:\claudetools\grepai.exe (gitignored; bundled for manual transfer to the laptop).
• The bat, when run on the laptop, will create/overwrite C:\claudetools\.claude\settings.local.json (with a .bak backup) and create %USERPROFILE%\Desktop\ClaudeTools.bat.

Credentials & Secrets

• None created or discovered this session. The bootstrap folder's keys.txt (vault age key) is unchanged and was not modified.

Infrastructure & Servers

• Laptop target paths: ClaudeTools C:\claudetools, Vault D:\vault (per Howard).
• Age key location on Windows: %APPDATA%\sops\age\keys.txt.
• Gitea: https://git.azcomputerguru.com, user howard; claudetools remote https://howard@git.azcomputerguru.com/azcomputerguru/claudetools.git.
• Desktop where work was performed: Howard-Home; Claude Code 2.1.160, Node v24.15.0, npm 11.14.1.

Commands & Outputs

• Root cause confirmation (laptop): dir C:\claudetools\grepai.exe → PathNotFound (binary missing — confirms the hang).
• Settings key verification (desktop): grep of installed claude.exe confirmed disabledMcpjsonServers, enabledMcpjsonServers, enableAllProjectMcpServers are all real keys.
• .mcp.json (git-tracked) content: {"mcpServers":{"grepai":{"command":"C:\\claudetools\\grepai.exe","args":["mcp-serve"]}}}.
• git check-ignore grepai.exe → ignored; git ls-files | grep grepai → only docs tracked, binary not tracked.

Pending / Incomplete Tasks

• Howard to move the howard-bootstrap folder (at minimum claude-laptop-setup.bat + grepai.exe + keys.txt, kept together) to the laptop and run the bat as administrator.
• On first run, if programs are installed fresh, the bat exits and must be run a second time (PATH refresh).
• Verify on the laptop that Claude opens from C:\claudetools without hanging and that grepai semantic search works (binary now bundled).
• Optional future cleanup: consider shipping grepai.exe via a Gitea release artifact so new machines get it without manual transfer.

Reference Information

• Installer: projects/msp-tools/howard-bootstrap/claude-laptop-setup.bat
• Bundled binary: projects/msp-tools/howard-bootstrap/grepai.exe
• Old installer (kept): projects/msp-tools/howard-bootstrap/setup.bat
• Repo startup config: .mcp.json (root), .claude/settings.json, .claude/settings.local.json
• Claude Code MCP-disable key: disabledMcpjsonServers (array) in .claude/settings.local.json
• Desktop launcher created on laptop: %USERPROFILE%\Desktop\ClaudeTools.bat

Update: 20:33 PT — Paused; deliverable staged

Session paused ("come back to this"). State verified and committed:

• claude-laptop-setup.bat is tracked and pushed in the repo at projects/msp-tools/howard-bootstrap/.
• grepai.exe is present in that folder on Howard-Home but gitignored — must be moved to the laptop manually alongside the .bat (it will not sync).
• No code changes since the prior save; nothing left running.

Next step on return: Howard moves claude-laptop-setup.bat + grepai.exe + keys.txt (kept together) to the laptop, runs the .bat as administrator (re-run once if it installs fresh programs), then verifies Claude opens from C:\claudetools without hanging and grepai search works.