FoundryVTT/.claude/CONTEXT_PERSISTENCE.md

Context Persistence Across Claude Code Sessions

Last Updated: 2025-01-30 Status: ✅ Fully Configured

---

🎯 Overview

This document explains how project instructions and tooling requirements persist across Claude Code conversation sessions.

---

✅ What Happens Automatically

1. CLAUDE.md Loading

• Status: ✅ Automatic (built into Claude Code)
• When: Start of every conversation
• File: CLAUDE.md
• How: Claude Code includes it in the system prompt automatically
• Action Required: None - works out of the box

2. SessionStart Hook

• Status: ✅ Configured and active
• When: Start of every conversation
• File: .claude/hooks/session-start.sh
• Configuration: .claude/settings.json:116-126
• What it does: Displays a prominent reminder about:
  • Available MCP servers
  • Available agents
  • Mandatory tooling usage requirements
  • Links to documentation

3. MCP Servers

• Status: ✅ Auto-connect on every session
• Configuration: .mcp.json + enableAllProjectMcpServers: true
• Servers: serena, sequential-thinking, context7, memory, fetch, windows-mcp, playwright, database-server

4. Specialized Agents

• Status: ✅ Always available
• Location: .claude/agents/
• Count: 8 agents (Explore, Plan, test-engineer, code-reviewer, etc.)
• Access: Via Task tool with subagent_type parameter

5. Slash Commands

• Status: ✅ Always available
• Location: .claude/commands/
• Count: 9 commands (/test, /review, /explain, etc.)
• Access: Via SlashCommand tool

---

📋 Session Initialization Flow

New Conversation Started
    ↓
1. Claude Code loads CLAUDE.md automatically
    ↓
2. SessionStart hook executes (.claude/hooks/session-start.sh)
    ↓
3. Hook outputs reminder message to conversation
    ↓
4. MCP servers auto-connect
    ↓
5. Agents become available
    ↓
6. Slash commands become available
    ↓
✅ Session ready with full context!

---

🧪 Testing

Verify Session Hook Works

Run manually to see output:

bash .claude/hooks/session-start.sh

Expected output:

🚀 **New Session Initialized - Foundry VTT Development Environment**

📋 **MANDATORY REMINDERS FOR THIS SESSION**:
[... reminder content ...]

Verify CLAUDE.md Loading

Start a new conversation and ask:

"What project am I working on?"

Claude should know about:

• Foundry VTT v11.315
• PF1e System v10.8
• Macro development focus
• All project structure details

Verify MCP Servers

In a new conversation, ask:

"What MCP servers are available?"

Should list all 8 servers.

Verify Agents

In a new conversation, ask:

"What specialized agents are available?"

Should list all 8 agents with descriptions.

---

📁 Key Files

File	Purpose	Auto-Load?
CLAUDE.md	Complete project documentation	✅ Yes
.claude/SESSION_INSTRUCTIONS.md	Quick reference for mandatory policies	Manual read
.claude/settings.json	Claude Code configuration	✅ Yes
.claude/hooks/session-start.sh	Session initialization hook	✅ Yes
.mcp.json	MCP server configuration	✅ Yes

---

🔧 Customization

To Modify Session Start Message

Edit: .claude/hooks/session-start.sh

The heredoc section (lines 15-48) contains the message displayed at session start.

To Add More Instructions

Option A: Add to CLAUDE.md (automatically loaded) Option B: Modify session-start.sh hook (shown at session start) Option C: Create new files in .claude/ (manual read required)

To Add More Hooks

Edit: .claude/settings.json

Available hooks:

• SessionStart: Start of session
• SessionEnd: End of session
• PreToolUse: Before any tool use
• PostToolUse: After any tool use
• UserPromptSubmit: When user sends a message
• Stop: When generation is stopped

---

✨ Benefits of This Setup

1. Zero Manual Effort: Everything loads automatically
2. Consistent Reminders: Every session starts with clear instructions
3. Full Context: Claude always knows about agents, MCP servers, and project details
4. Trackable: Session logs in .claude/logs/session.log
5. Customizable: Easy to modify hooks and instructions

---

🎯 What Claude Will See in Every New Session

At the start of every conversation, Claude receives:

1. ✅ System Prompt: Contains full CLAUDE.md automatically
2. ✅ Hook Output: Displays session initialization banner
3. ✅ MCP Tools: All 8 MCP servers' tools are registered
4. ✅ Agents: All 8 agents are available via Task tool
5. ✅ Slash Commands: All 9 commands are available
6. ✅ Permissions: All allowed/denied operations from settings.json

---

📝 Maintenance

When to Update

Update these files when:

• Adding new MCP servers → Update session-start.sh
• Adding new agents → Update session-start.sh
• Changing project focus → Update CLAUDE.md + session-start.sh
• Adding new mandatory policies → Update CLAUDE.md + SESSION_INSTRUCTIONS.md

Backup

Key files to backup:

• CLAUDE.md
• .claude/settings.json
• .claude/hooks/*.sh
• .claude/SESSION_INSTRUCTIONS.md
• .mcp.json

---

🐛 Troubleshooting

Hook Not Running?

Check .claude/settings.json lines 116-126:

"hooks": {
  "SessionStart": [
    {
      "matcher": "*",
      "hooks": [
        {
          "type": "command",
          "command": "bash .claude/hooks/session-start.sh"
        }
      ]
    }
  ]
}

CLAUDE.md Not Loading?

• Ensure file exists at project root: c:\DEV\Foundry\CLAUDE.md
• File is automatically loaded by Claude Code (no configuration needed)

MCP Servers Not Connecting?

• Check .mcp.json exists
• Verify enableAllProjectMcpServers: true in settings.json
• Check MCP server installations

---

Reference: See CLAUDE.md for complete project documentation

Questions?: The session-start hook ensures you see reminders at every session start!