personal-projects/leo-claude-mktplace
Template
0
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Bug: CLAUDE.md instructs cache clear mid-session, breaking MCP tools #145

New Issue
Closed
opened 2026-01-24 17:51:42 +00:00 by lmiranda · 1 comment
lmiranda commented 2026-01-24 17:51:42 +00:00
Owner
Copy Link

Problem Description

The CLAUDE.md file contains a mandatory rule that instructs Claude to clear the plugin cache after making plugin updates:

rm -rf ~/.claude/plugins/cache/leo-claude-mktplace/
./scripts/verify-hooks.sh

This instruction is fundamentally flawed. Clearing the cache mid-session breaks all MCP tools that were already loaded, because:

  1. MCP tools are loaded into the session with paths pointing to the cache directory
  2. The cache contains the venv with dependencies (including certifi for TLS)
  3. Deleting the cache removes the venv, but tool definitions still reference it
  4. Any MCP tool that makes HTTP requests fails with TLS certificate errors

Reproduction

  1. Start Claude Code session in a project using projman
  2. Use any MCP tool (loads from cache)
  3. Make a plugin edit
  4. Follow CLAUDE.md instruction: rm -rf ~/.claude/plugins/cache/leo-claude-mktplace/
  5. Try to use MCP tools again
  6. Result: All HTTP-based MCP tools fail

Actual Error

Error: Could not find a suitable TLS CA certificate bundle, invalid path: 
/home/lmiranda/.claude/plugins/cache/leo-claude-mktplace/projman/3.1.0/mcp-servers/gitea/.venv/lib/python3.11/site-packages/certifi/cacert.pem

Root Cause

The CLAUDE.md rule was written without understanding that:

  • MCP tools are loaded at session start (or first use)
  • Tool definitions include absolute paths to the venv
  • Clearing cache doesn't reload tool definitions - they're cached in the session
  • Only restarting the Claude Code session reloads tool paths

Required Fixes

1. Update CLAUDE.md

Remove or modify the cache clear instruction:

Current (WRONG):

### 5. AFTER PLUGIN UPDATES - ALWAYS CLEAR CACHE
```bash
rm -rf ~/.claude/plugins/cache/leo-claude-mktplace/
./scripts/verify-hooks.sh

Should be:

### 5. AFTER PLUGIN UPDATES - VERIFY AND RESTART
1. Run `./scripts/verify-hooks.sh` to check hook types
2. If changes affect MCP servers, inform user: "Please restart Claude Code session for changes to take effect"
3. **DO NOT clear cache mid-session** - this breaks MCP tools

2. Update verify-hooks.sh

The script should NOT recommend clearing cache. Instead, it should recommend restarting the session.

3. Document in DEBUGGING-CHECKLIST.md

Add a section explaining:

  • When cache clear is appropriate (before starting a session)
  • When it's destructive (during a session)
  • The correct recovery action (restart session)

Acceptance Criteria

  • CLAUDE.md updated to remove mid-session cache clear instruction
  • verify-hooks.sh updated to recommend session restart instead
  • DEBUGGING-CHECKLIST.md documents cache clear timing
  • Test: Complete a full session with plugin updates without breaking MCP tools
## Problem Description The `CLAUDE.md` file contains a mandatory rule that instructs Claude to clear the plugin cache after making plugin updates: ```bash rm -rf ~/.claude/plugins/cache/leo-claude-mktplace/ ./scripts/verify-hooks.sh ``` **This instruction is fundamentally flawed.** Clearing the cache mid-session breaks all MCP tools that were already loaded, because: 1. MCP tools are loaded into the session with paths pointing to the cache directory 2. The cache contains the venv with dependencies (including `certifi` for TLS) 3. Deleting the cache removes the venv, but tool definitions still reference it 4. Any MCP tool that makes HTTP requests fails with TLS certificate errors ## Reproduction 1. Start Claude Code session in a project using projman 2. Use any MCP tool (loads from cache) 3. Make a plugin edit 4. Follow CLAUDE.md instruction: `rm -rf ~/.claude/plugins/cache/leo-claude-mktplace/` 5. Try to use MCP tools again 6. **Result**: All HTTP-based MCP tools fail ## Actual Error ``` Error: Could not find a suitable TLS CA certificate bundle, invalid path: /home/lmiranda/.claude/plugins/cache/leo-claude-mktplace/projman/3.1.0/mcp-servers/gitea/.venv/lib/python3.11/site-packages/certifi/cacert.pem ``` ## Root Cause The CLAUDE.md rule was written without understanding that: - MCP tools are loaded at session start (or first use) - Tool definitions include absolute paths to the venv - Clearing cache doesn't reload tool definitions - they're cached in the session - Only restarting the Claude Code session reloads tool paths ## Required Fixes ### 1. Update CLAUDE.md Remove or modify the cache clear instruction: **Current (WRONG):** ```markdown ### 5. AFTER PLUGIN UPDATES - ALWAYS CLEAR CACHE ```bash rm -rf ~/.claude/plugins/cache/leo-claude-mktplace/ ./scripts/verify-hooks.sh ``` **Should be:** ```markdown ### 5. AFTER PLUGIN UPDATES - VERIFY AND RESTART 1. Run `./scripts/verify-hooks.sh` to check hook types 2. If changes affect MCP servers, inform user: "Please restart Claude Code session for changes to take effect" 3. **DO NOT clear cache mid-session** - this breaks MCP tools ``` ### 2. Update verify-hooks.sh The script should NOT recommend clearing cache. Instead, it should recommend restarting the session. ### 3. Document in DEBUGGING-CHECKLIST.md Add a section explaining: - When cache clear is appropriate (before starting a session) - When it's destructive (during a session) - The correct recovery action (restart session) ## Acceptance Criteria - [ ] CLAUDE.md updated to remove mid-session cache clear instruction - [ ] verify-hooks.sh updated to recommend session restart instead - [ ] DEBUGGING-CHECKLIST.md documents cache clear timing - [ ] Test: Complete a full session with plugin updates without breaking MCP tools
lmiranda commented 2026-01-24 17:58:03 +00:00
Author
Owner
Copy Link

Fix Proposed

Branch: fix/issue-145-cache-clear-instructions

Changes:

  • CLAUDE.md: Replaced "ALWAYS CLEAR CACHE" rule with "VERIFY AND RESTART" - warns against mid-session cache clearing
  • verify-hooks.sh: Changed cache existence check from error to informational message
  • DEBUGGING-CHECKLIST.md: Added new section "Cache Clearing: When It's Safe vs Destructive"

Create PR:

https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/compare/development...fix/issue-145-cache-clear-instructions

Next Steps:

  1. Create and merge PR
  2. Test in a new session - make plugin edits without clearing cache
  3. Verify MCP tools continue working after edits
  4. Return to close issue and capture lesson learned
## Fix Proposed Branch: `fix/issue-145-cache-clear-instructions` ### Changes: - **CLAUDE.md**: Replaced "ALWAYS CLEAR CACHE" rule with "VERIFY AND RESTART" - warns against mid-session cache clearing - **verify-hooks.sh**: Changed cache existence check from error to informational message - **DEBUGGING-CHECKLIST.md**: Added new section "Cache Clearing: When It's Safe vs Destructive" ### Create PR: https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/compare/development...fix/issue-145-cache-clear-instructions ### Next Steps: 1. Create and merge PR 2. Test in a new session - make plugin edits without clearing cache 3. Verify MCP tools continue working after edits 4. Return to close issue and capture lesson learned
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
Component/API
API endpoints, contracts, and integration
 Component/Auth
Authentication and authorization
 Component/Backend
Backend service code and business logic
 Component/Database
Database schemas, migrations, queries
 Component/Deploy
Deployment, infrastructure, DevOps
 Component/Docs
Documentation and guides
 Component/Frontend
User interface and client-side code
 Component/Infra
Infrastructure and system configuration
 Component/Testing
Test infrastructure and frameworks
 Tech/Docker
Docker containers and compose
 Tech/FastAPI
FastAPI backend framework
 Tech/JavaScript
JavaScript/Node.js code
 Tech/PostgreSQL
PostgreSQL database
 Tech/Python
Python language and libraries
 Tech/Redis
Redis cache and pub/sub
 Tech/Vue
Vue.js frontend framework
Complexity/Complex
High uncertainty or many dependencies
 Complexity/Medium
Some unknowns or dependencies
 Complexity/Simple
Straightforward, well-understood
 Effort/L
3-5 days
 Effort/M
1-2 days
 Effort/S
2-4 hours
 Effort/XL
> 1 week
 Effort/XS
< 2 hours
 Priority/Critical
Immediate attention required
 Priority/High
Important, needs attention soon
 Priority/Low
Nice to have, can wait
 Priority/Medium
Normal priority
 Type/Bug
Something isn't working
 Type/Chore
Maintenance tasks
 Type/Documentation
Documentation improvements
 Type/Feature
New feature or request
 Type/Refactor
Code refactoring without changing behavior
 Type/Test
Testing related
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
lmiranda
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: personal-projects/leo-claude-mktplace#145
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?