From b13ffce0a0f4f3dc2d3c83d8cd219a296ef2cee1 Mon Sep 17 00:00:00 2001 From: lmiranda Date: Sat, 24 Jan 2026 12:57:32 -0500 Subject: [PATCH] fix: remove destructive cache-clear instruction from CLAUDE.md The CLAUDE.md mandatory rule instructed clearing the plugin cache mid-session, which breaks all MCP tools that were already loaded. MCP tools are loaded with absolute paths to the venv, and deleting the cache removes the venv while the session still references it. Changes: - CLAUDE.md: Replace "ALWAYS CLEAR CACHE" with "VERIFY AND RESTART" - verify-hooks.sh: Change cache existence from error to info message - DEBUGGING-CHECKLIST.md: Add section explaining cache timing Fixes #145 Co-Authored-By: Claude Opus 4.5 --- CLAUDE.md | 31 +++++++++++++++---------- docs/DEBUGGING-CHECKLIST.md | 45 +++++++++++++++++++++++++++++++++++++ scripts/verify-hooks.sh | 8 +++---- 3 files changed, 68 insertions(+), 16 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index d80ad4f..8cb14d6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -31,11 +31,16 @@ This file provides guidance to Claude Code when working with code in this reposi - If user asks for output, show the OUTPUT - **Don't interpret or summarize unless asked** -### 5. AFTER PLUGIN UPDATES - ALWAYS CLEAR CACHE -```bash -rm -rf ~/.claude/plugins/cache/leo-claude-mktplace/ -./scripts/verify-hooks.sh -``` +### 5. AFTER PLUGIN UPDATES - VERIFY AND RESTART + +**⚠️ DO NOT clear cache mid-session** - this breaks MCP tools that are already loaded. + +1. Run `./scripts/verify-hooks.sh` to check hook types +2. If changes affect MCP servers or hooks, inform the user: + > "Plugin changes require a session restart to take effect. Please restart Claude Code." +3. Cache clearing is ONLY safe **before** starting a new session (not during) + +See `docs/DEBUGGING-CHECKLIST.md` for details on cache timing. **FAILURE TO FOLLOW THESE RULES = WASTED USER TIME = UNACCEPTABLE** @@ -125,7 +130,9 @@ leo-claude-mktplace/ │ └── project-hygiene/ ├── scripts/ │ ├── setup.sh, post-update.sh -│ └── validate-marketplace.sh # Marketplace compliance validation +│ ├── validate-marketplace.sh # Marketplace compliance validation +│ ├── verify-hooks.sh # Verify all hooks are command type +│ └── check-venv.sh # Check MCP server venvs exist └── docs/ ├── CANONICAL-PATHS.md # Single source of truth for paths └── CONFIGURATION.md # Centralized configuration guide @@ -172,12 +179,12 @@ leo-claude-mktplace/ | Category | Tools | |----------|-------| -| Issues | `list_issues`, `get_issue`, `create_issue`, `update_issue`, `add_comment` | -| Labels | `get_labels`, `suggest_labels`, `create_label` | -| Milestones | `list_milestones`, `get_milestone`, `create_milestone`, `update_milestone` | -| Dependencies | `list_issue_dependencies`, `create_issue_dependency`, `get_execution_order` | -| Wiki | `list_wiki_pages`, `get_wiki_page`, `create_wiki_page`, `create_lesson`, `search_lessons` | -| **Pull Requests** | `list_pull_requests`, `get_pull_request`, `get_pr_diff`, `get_pr_comments`, `create_pr_review`, `add_pr_comment` *(NEW v3.0.0)* | +| Issues | `list_issues`, `get_issue`, `create_issue`, `update_issue`, `add_comment`, `aggregate_issues` | +| Labels | `get_labels`, `suggest_labels`, `create_label`, `create_label_smart` | +| Milestones | `list_milestones`, `get_milestone`, `create_milestone`, `update_milestone`, `delete_milestone` | +| Dependencies | `list_issue_dependencies`, `create_issue_dependency`, `remove_issue_dependency`, `get_execution_order` | +| Wiki | `list_wiki_pages`, `get_wiki_page`, `create_wiki_page`, `update_wiki_page`, `create_lesson`, `search_lessons` | +| **Pull Requests** | `list_pull_requests`, `get_pull_request`, `get_pr_diff`, `get_pr_comments`, `create_pr_review`, `add_pr_comment` | | Validation | `validate_repo_org`, `get_branch_protection` | ### Hybrid Configuration diff --git a/docs/DEBUGGING-CHECKLIST.md b/docs/DEBUGGING-CHECKLIST.md index e0a442a..e4eb2ad 100644 --- a/docs/DEBUGGING-CHECKLIST.md +++ b/docs/DEBUGGING-CHECKLIST.md @@ -197,6 +197,51 @@ echo -e "\n=== Config Files ===" --- +## Cache Clearing: When It's Safe vs Destructive + +**⚠️ CRITICAL: Never clear plugin cache mid-session.** + +### Why Cache Clearing Breaks MCP Tools + +When Claude Code starts a session: +1. MCP tools are loaded from the cache directory +2. Tool definitions include **absolute paths** to the venv (e.g., `~/.claude/plugins/cache/.../venv/`) +3. These paths are cached in the session memory +4. Deleting the cache removes the venv, but the session still references the old paths +5. Any MCP tool making HTTP requests fails with TLS certificate errors + +### When Cache Clearing is SAFE + +| Scenario | Safe? | Action | +|----------|-------|--------| +| Before starting Claude Code | ✅ Yes | Clear cache, then start session | +| Between sessions | ✅ Yes | Clear cache after `/exit`, before next session | +| During a session | ❌ NO | Never - will break MCP tools | +| After plugin source edits | ❌ NO | Restart session instead | + +### Recovery: MCP Tools Broken Mid-Session + +If you accidentally cleared cache during a session and MCP tools fail: + +``` +Error: Could not find a suitable TLS CA certificate bundle, invalid path: +/home/.../.claude/plugins/cache/.../certifi/cacert.pem +``` + +**Fix:** +1. Exit the current session (`/exit` or Ctrl+C) +2. Start a new Claude Code session +3. MCP tools will reload from the reinstalled cache + +### Correct Workflow for Plugin Development + +1. Make changes to plugin source files +2. Run `./scripts/verify-hooks.sh` (verifies hook types) +3. Tell user: "Please restart Claude Code for changes to take effect" +4. **Do NOT clear cache** - session restart handles reloading + +--- + ## Automated Diagnostics Use these commands for automated checking: diff --git a/scripts/verify-hooks.sh b/scripts/verify-hooks.sh index bb6fff8..7247493 100755 --- a/scripts/verify-hooks.sh +++ b/scripts/verify-hooks.sh @@ -15,11 +15,11 @@ for f in $(find ~/.claude -name "hooks.json" 2>/dev/null); do fi done -# Check cache specifically +# Note about cache (informational only - do NOT clear mid-session) if [ -d ~/.claude/plugins/cache/leo-claude-mktplace ]; then - echo "❌ CACHE EXISTS: ~/.claude/plugins/cache/leo-claude-mktplace" - echo " Run: rm -rf ~/.claude/plugins/cache/leo-claude-mktplace/" - FAILED=1 + echo "ℹ️ Cache exists: ~/.claude/plugins/cache/leo-claude-mktplace" + echo " (This is normal - do NOT clear mid-session or MCP tools will break)" + echo " To apply plugin changes: restart Claude Code session" fi # Verify installed hooks are command type -- 2.49.1