FoundryVTT/CLAUDE_CODE_SETUP_COMPLETE.md

Claude Code Complete Setup Guide

Comprehensive documentation for the Claude Code Setup project Version: 3.0.0 | Last Updated: 2025-10-20 Completeness: ~95% of Claude Code capabilities implemented

---

Table of Contents

1. Overview
2. Project Structure
3. Core Features
4. MCP Servers
5. Agents & Subagents
6. Slash Commands
7. Output Styles
8. Hooks System
9. Templates
10. Configuration
11. Memory & Context
12. Advanced Features
13. Best Practices
14. Troubleshooting

---

Overview

What is This Project?

This is a production-ready Claude Code setup demonstrating comprehensive configuration of all major features, including:

• ✅ 8 MCP servers configured (code navigation, memory, documentation, automation)
• ✅ 8 specialized agents (architecture, code review, debugging, security, testing)
• ✅ 9 slash commands (adr, analyze, review, implement, test, optimize, explain, scaffold)
• ✅ 6 custom output styles (concise, professional, verbose, learning, explanatory, security)
• ✅ 6 event hooks (session lifecycle, bash commands, file operations, stop tracking)
• ✅ Comprehensive templates for extending all features
• ✅ Custom status line and plugin marketplace access
• ✅ Automatic status summaries showing tool usage for every task

Claude Code Capabilities Overview

Claude Code is an AI-powered development assistant that operates through:

Core Mechanisms:

• Tools: File operations (Read, Write, Edit), code search (Grep, Glob), shell execution (Bash)
• MCP Servers: External integrations extending Claude's capabilities
• Agents/Subagents: Specialized AI assistants for specific domains
• Slash Commands: User-invoked workflows and routines
• Output Styles: Customizable response behaviors
• Hooks: Event-driven automation
• Memory: Persistent and temporary context storage

---

Project Structure

Claude Code Setup/
│
├── .claude/                          # Main Claude Code configuration directory
│   │
│   ├── agents/                       # Specialized AI agents (8 agents)
│   │   ├── architect.md              # System design & technical planning
│   │   ├── code-reviewer.md          # Code quality & review
│   │   ├── debugger.md               # Bug diagnosis & fixing
│   │   ├── documentation-writer.md   # Technical documentation
│   │   ├── project-manager.md        # Project coordination
│   │   ├── refactoring-specialist.md # Code improvement
│   │   ├── security-analyst.md       # Security analysis
│   │   ├── test-engineer.md          # Testing strategy
│   │   └── .AGENT_TEMPLATE.md        # Template for new agents
│   │
│   ├── commands/                     # Slash commands (8 commands)
│   │   ├── analyze.md                # Comprehensive code analysis
│   │   ├── explain.md                # Code explanation
│   │   ├── implement.md              # Feature implementation
│   │   ├── optimize.md               # Performance optimization
│   │   ├── review.md                 # Code review
│   │   ├── scaffold.md               # Project scaffolding
│   │   ├── setup-info.md             # Display setup information
│   │   ├── test.md                   # Test execution
│   │   └── .COMMANDS_TEMPLATE.md     # Template for new commands
│   │
│   ├── output-styles/                # Custom output behaviors (6 styles)
│   │   ├── concise.md                # Brief responses
│   │   ├── professional.md           # Formal tone
│   │   ├── verbose.md                # Detailed explanations
│   │   ├── explanatory.md            # Educational insights
│   │   ├── learning.md               # Interactive learning mode
│   │   ├── security-reviewer.md      # Security-focused
│   │   └── .OUTPUT_STYLES_TEMPLATE.md # Template for new styles
│   │
│   ├── skills/                       # Agent skills (model-invoked)
│   │   └── .SKILL_TEMPLATE.md        # Template for new skills
│   │
│   ├── hooks/                        # Event automation (6 hooks)
│   │   ├── session-start.sh          # Session initialization
│   │   ├── session-end.sh            # Session cleanup
│   │   ├── stop.sh                   # Stop event logging
│   │   ├── pre-bash.sh               # Before bash commands
│   │   ├── post-write.sh             # After file writes
│   │   └── user-prompt-submit.sh     # After prompt submission
│   │
│   ├── tools/                        # Utility scripts
│   │   ├── start-memory.ps1          # PowerShell memory MCP launcher
│   │   └── statusline.sh             # Custom status line script
│   │
│   ├── logs/                         # Session logs
│   │   ├── session.log               # Session activity
│   │   ├── bash.log                  # Bash command log
│   │   └── writes.log                # File write log
│   │
│   ├── settings.json                 # Main configuration (shared)
│   ├── settings.local.json           # Local configuration (personal)
│   ├── statusline.sh                 # Status line configuration
│   │
│   └── [Documentation Files]         # Various guides (see below)
│
├── .mcp.json                         # MCP servers configuration (9 servers)
├── CLAUDE.md                         # Project instructions for Claude
├── CLAUDE_TEMPLATE.md                # Template for CLAUDE.md files
└── TEMPLATES_SUMMARY.md              # Quick reference for all templates

Documentation Files (in .claude/)

• TEMPLATES_README.md - Master guide for all templates
• agents/MCP_USAGE_TEMPLATES.md - MCP usage templates for agents
• CHECKPOINTING_GUIDE.md - Session checkpointing guide
• SETUP_COMPLETE.md - Setup completion summary
• PLUGIN_SETUP.md - Plugin marketplace guide
• STATUS_LINE_SETUP.md - Status line customization
• TEMPLATE_CAPABILITIES_ANALYSIS.md - Template review analysis

---

Core Features

1. File Operations

Claude Code has direct file access through specialized tools:

Read Tool:

• Read any file by absolute path
• Support for images, PDFs, Jupyter notebooks
• Optional line offset and limit for large files

Write Tool:

• Create new files (overwrites existing)
• Must read file first before writing existing files

Edit Tool:

• Exact string replacement
• Must read file first
• Supports replace_all for renaming

Glob Tool:

• Fast file pattern matching
• Returns files sorted by modification time
• Examples: **/*.js, src/**/*.ts

Grep Tool:

• Built on ripgrep for fast searching
• Supports regex patterns
• Context lines (-A, -B, -C options)
• Multiple output modes (content, files_with_matches, count)

2. Shell Execution

Bash Tool:

• Execute shell commands with timeout (default 2 min, max 10 min)
• Background execution supported
• Parallel execution for independent commands
• Sequential execution with && for dependencies

Pre-approved commands (no permission needed):

• ls, dir, git status, git diff, git log
• mkdir, echo, findstr, tree
• npx, uvx, where

3. Specialized Tools

• WebSearch: Search the web for current information
• WebFetch: Retrieve and process web content
• SlashCommand: Execute custom slash commands
• Task: Launch specialized subagents
• TodoWrite: Manage task lists during sessions
• NotebookEdit: Edit Jupyter notebooks

---

MCP Servers

Overview

This project has 8 MCP servers configured, providing extensive capabilities beyond Claude's native tools.

1. Serena MCP

Purpose: IDE assistant with code navigation and persistent memory

Command: uvx --from git+https://github.com/oraios/serena serena start-mcp-server

Capabilities:

Code Navigation:

• find_symbol - Locate code symbols by name/pattern
• find_referencing_symbols - Find all references to a symbol
• get_symbols_overview - Get file structure overview
• search_for_pattern - Search for patterns in code
• rename_symbol - Safely rename across codebase
• replace_symbol_body - Replace function/class body
• insert_after_symbol / insert_before_symbol - Add code at specific locations

Persistent Memory:

• write_memory - Store information that persists across sessions
• read_memory - Recall stored information
• list_memories - Browse all memories
• delete_memory - Remove outdated information

Storage: .serena/memories/ (survives across sessions)

Best Used For:

• ✅ Architectural Decision Records (ADRs)
• ✅ Code review findings and summaries
• ✅ Lessons learned from implementations
• ✅ Project-specific patterns discovered
• ✅ Technical debt registry
• ✅ Security audit results
• ✅ Performance optimization notes

Current Memory: serena-persistence-test

2. Sequential Thinking MCP

Purpose: Enhanced reasoning and complex problem-solving

Command: npx -y @modelcontextprotocol/server-sequential-thinking

Capabilities:

• sequentialthinking - Multi-step reasoning with revision capability
• Adjust thought count dynamically
• Branch and revise previous thoughts
• Generate and verify hypotheses

Best Used For:

• Complex architectural decisions
• Multi-step debugging
• Design pattern selection
• Security analysis

3. Database Server MCP

Purpose: Database query support

Command: npx -y @executeautomation/database-server

Note: Requires database connection configuration

4. Context7 MCP

Purpose: Real-time library documentation lookup

Command: npx -y @upstash/context7-mcp

Capabilities:

• resolve-library-id - Find library identifier for documentation
• get-library-docs - Get current framework/library documentation

Best Used For:

• Learning new frameworks
• Getting up-to-date API references
• Finding best practices for libraries
• Code examples from official docs

API Key: Configured in .mcp.json

5. Memory MCP (Knowledge Graph)

Purpose: Temporary in-memory knowledge graph for current session

Command: powershell -ExecutionPolicy Bypass -File .\.claude\tools\start-memory.ps1

Capabilities:

• create_entities - Create entities (Features, Classes, Services, etc.)
• create_relations - Define relationships between entities
• add_observations - Add details to entities
• search_nodes - Search the knowledge graph
• read_graph - View entire graph state
• open_nodes - Retrieve specific entities
• delete_entities / delete_relations / delete_observations - Remove items

Storage: In-memory only, cleared after session ends

Best Used For:

• ✅ Current conversation context
• ✅ Temporary analysis during current task
• ✅ Entity relationships in current work
• ✅ Cross-file refactoring state
• ✅ Session-specific tracking

Storage Location: .mcp-data\memory\ (managed by PowerShell script)

6. Fetch MCP

Purpose: Web content retrieval and processing

Command: uvx mcp-server-fetch

Capabilities:

• fetch - Retrieve URLs and convert to markdown
• Support for HTML parsing
• Configurable content length

Best Used For:

• API documentation scraping
• Web content analysis
• Integration documentation

7. Windows MCP

Purpose: Windows desktop automation

Command: uv --directory ./.windows-mcp run main.py

Capabilities:

• Launch applications
• PowerShell execution
• Desktop state capture
• Clipboard operations
• Mouse and keyboard control
• Window management
• Screen scraping

Best Used For:

• GUI automation
• Desktop testing
• Windows-specific operations

8. Playwright MCP

Purpose: Browser automation and testing

Command: npx -y @playwright/mcp

Capabilities:

• Browser navigation and interaction
• Form filling and clicking
• Screenshot capture
• Network request monitoring
• Console message capture
• File uploads
• JavaScript evaluation

Best Used For:

• E2E testing
• Web scraping
• UI automation
• Browser-based workflows

MCP Quick Decision Tree

Question: Should this information exist next week?

• YES → Use Serena write_memory
• NO → Use Memory graph

Question: Am I navigating or editing code?

• YES → Use Serena code functions

Question: Am I building temporary context for current task?

• YES → Use Memory graph

Question: Do I need current library documentation?

• YES → Use Context7

Question: Do I need to automate a browser?

• YES → Use Playwright

---

Agents & Subagents

Overview

8 specialized agents handle specific domains, each with isolated context and focused expertise.

How Agents Work

Invocation:

• Automatic: Claude invokes based on task description matching
• Manual: User explicitly requests with "Use the [agent-name] agent to..."

Isolation: Each agent operates in its own context window, preventing main conversation pollution.

Configuration: Agents can have custom:

• allowed-tools - Restricted tool access
• model - Specific Claude model (Sonnet, Opus, Haiku)
• description - Triggers automatic invocation

Available Agents

1. Architect Agent

File: .claude/agents/architect.md

Purpose: System design, architecture planning, technical decisions

Keywords: architecture, design, technical decisions, scalability, system design

Responsibilities:

• System architecture design
• Technology evaluation
• Technical planning
• Architecture review
• Technical documentation

When to Use:

• Designing new systems
• Evaluating technology choices
• Planning major refactors
• Reviewing architecture
• Creating ADRs

2. Code Reviewer Agent

File: .claude/agents/code-reviewer.md

Purpose: Code quality review and best practices enforcement

Keywords: code review, quality, best practices, review

Responsibilities:

• Code quality assessment
• Best practices verification
• Security review
• Performance analysis
• Documentation review

When to Use:

• Reviewing pull requests
• Pre-commit quality checks
• Security audits
• Performance reviews

3. Debugger Agent

File: .claude/agents/debugger.md

Purpose: Bug diagnosis and troubleshooting

Keywords: debug, troubleshoot, error, bug, issue

Responsibilities:

• Error analysis
• Stack trace interpretation
• Root cause identification
• Fix recommendations
• Debugging strategies

When to Use:

• Investigating bugs
• Analyzing errors
• Troubleshooting issues
• Performance problems

4. Documentation Writer Agent

File: .claude/agents/documentation-writer.md

Purpose: Technical documentation creation

Keywords: documentation, docs, readme, comments, docstrings

Responsibilities:

• API documentation
• README files
• Code comments
• User guides
• Architecture docs

When to Use:

• Creating documentation
• Updating docs
• Generating API references
• Writing user guides

5. Project Manager Agent

File: .claude/agents/project-manager.md

Purpose: Project coordination and workflow management

Keywords: project, manage, coordinate, workflow, plan

Responsibilities:

• Task breakdown
• Workflow coordination
• Progress tracking
• Resource allocation
• Timeline planning

When to Use:

• Planning large features
• Coordinating multiple tasks
• Breaking down projects
• Managing workflows

6. Refactoring Specialist Agent

File: .claude/agents/refactoring-specialist.md

Purpose: Code improvement and refactoring

Keywords: refactor, improve, cleanup, optimize code structure

Responsibilities:

• Code structure improvement
• Pattern implementation
• Technical debt reduction
• Code cleanup
• Maintainability enhancement

When to Use:

• Refactoring legacy code
• Improving code structure
• Applying design patterns
• Reducing technical debt

7. Security Analyst Agent

File: .claude/agents/security-analyst.md

Purpose: Security analysis and vulnerability assessment

Keywords: security, vulnerability, threat, audit, security analysis

Responsibilities:

• Vulnerability scanning
• Security best practices
• Threat modeling
• Compliance checking
• Security recommendations

When to Use:

• Security audits
• Vulnerability assessment
• Compliance reviews
• Threat analysis

8. Test Engineer Agent

File: .claude/agents/test-engineer.md

Purpose: Testing strategy and implementation

Keywords: test, testing, unit test, integration test, test coverage

Responsibilities:

• Test strategy
• Test implementation
• Coverage analysis
• Test automation
• Quality assurance

When to Use:

• Writing tests
• Test planning
• Coverage improvement
• Test automation

Agent Usage Examples

# Automatic invocation (based on description matching)
> "I need to design a microservices architecture for our API"
# → Architect agent automatically invoked

# Manual invocation
> "Use the security-analyst agent to review this code for vulnerabilities"
# → Security analyst explicitly invoked

# Parallel agents (use Task tool with multiple calls)
> "I need code review and security analysis"
# → Both code-reviewer and security-analyst invoked in parallel

---

Slash Commands

Overview

9 slash commands provide explicit workflows for common tasks.

How Commands Work

Invocation: User types /command-name [arguments]

Arguments:

• $ARGUMENTS - All arguments as single string
• $1, $2, $3 - Individual arguments
• $@ - All arguments as array

File References: Use @path/to/file to include file content

Bash Execution: Prefix with ! for inline bash commands

Available Commands

1. /adr [list|view|create|update] [adr-number-or-name]

File: .claude/commands/adr.md

Purpose: Manage Architectural Decision Records (ADRs)

Arguments:

• [action] - list, view, create, or update
• [adr-number-or-name] - ADR identifier (optional for list/create)

Features:

• List all architectural decisions
• View specific ADR with full context
• Create new ADRs (invokes architect agent)
• Update/supersede/deprecate existing ADRs
• Track decision lifecycle and relationships
• Store ADRs in Serena persistent memory

Usage:

> /adr list                                    # List all ADRs
> /adr view adr-001                           # View specific ADR
> /adr view adr-003-authentication-strategy   # View by name
> /adr create                                  # Create new ADR
> /adr update adr-002                         # Update/supersede ADR

Allowed Tools: Read(), mcp__serena__list_memories(), mcp__serena__read_memory(), mcp__serena__write_memory(), Task(*)

Storage: ADRs are stored in Serena memory (.serena/memories/) and persist across sessions

Integration: Works with architect agent for ADR creation and formatting

2. /analyze [path]

File: .claude/commands/analyze.md

Purpose: Comprehensive code analysis

Arguments: [path] - File or directory to analyze

Features:

• Code complexity analysis
• Dependency mapping
• Quality metrics
• Architecture review
• Performance profiling

Usage:

> /analyze src/components/
> /analyze src/utils/api.ts

Allowed Tools: Read(), Grep(), Glob(), Bash()

3. /explain [file-or-selection]

File: .claude/commands/explain.md

Purpose: Detailed code explanation

Arguments: [file-or-selection] - What to explain

Features:

• Step-by-step breakdown
• Pattern identification
• Design rationale
• Best practices
• Learning insights

Usage:

> /explain src/auth/middleware.ts
> /explain @src/utils/parser.js

4. /implement [feature-description]

File: .claude/commands/implement.md

Purpose: Feature implementation

Arguments: [feature-description] - What to implement

Features:

• Feature planning
• Code generation
• Pattern following
• Testing included
• Documentation

Usage:

> /implement user authentication with JWT
> /implement payment integration with Stripe

5. /optimize [file-or-function]

File: .claude/commands/optimize.md

Purpose: Performance optimization

Arguments: [file-or-function] - What to optimize

Features:

• Bottleneck identification
• Algorithm optimization
• Memory profiling
• Performance testing
• Recommendations

Usage:

> /optimize src/utils/dataProcessor.ts
> /optimize database queries

6. /review [file-or-path]

File: .claude/commands/review.md

Purpose: Comprehensive code review

Arguments: [file-or-path] - What to review

Features:

• Quality assessment
• Best practices check
• Security review
• Performance analysis
• Improvement suggestions

Usage:

> /review src/api/routes/
> /review @src/components/UserProfile.tsx

7. /scaffold [type] [name]

File: .claude/commands/scaffold.md

Purpose: Generate boilerplate code

Arguments: [type] - What to scaffold, [name] - Name

Features:

• Component generation
• Service scaffolding
• API endpoint creation
• Test file generation
• Configuration setup

Usage:

> /scaffold component UserDashboard
> /scaffold service PaymentService
> /scaffold api /users/:id

8. /setup-info

File: .claude/commands/setup-info.md

Purpose: Display complete setup information

Features:

• Configuration overview
• Agent list
• Command list
• MCP server status
• Hook configuration

Usage:

> /setup-info

9. /test [file-path]

File: .claude/commands/test.md

Purpose: Test execution and management

Arguments: [file-path] - Test file or path

Features:

• Test running
• Coverage analysis
• Test generation
• Failure analysis
• Test strategy

Usage:

> /test
> /test src/utils/__tests__/api.test.ts
> /test --coverage

Creating Custom Commands

Use the template at .claude/commands/.COMMANDS_TEMPLATE.md

Example:

# 1. Copy template
cp .claude/commands/.COMMANDS_TEMPLATE.md .claude/commands/deploy.md

# 2. Edit frontmatter
---
description: Deploy application to production
argument-hint: [environment]
allowed-tools: Bash(git *:*), Bash(npm *:*), Read(*)
model: claude-3-5-sonnet-20241022
---

# 3. Write instructions
Deploy the application to $1 environment...

# 4. Use it
> /deploy production

---

Output Styles

Overview

6 custom output styles modify Claude's behavior and communication style.

How Output Styles Work

Activation: /output-style [style-name]

Effect: Completely replaces system prompt, changing how Claude responds

Scope: Active for entire conversation until changed

Tool Access: Inherits from conversation settings (not restricted by style)

Available Styles

1. Default Style

Built-in: Yes

Purpose: Standard software engineering assistant

Characteristics:

• Efficient and task-focused
• Technical accuracy
• Concise explanations
• Code-first approach

When to Use: Normal development work

2. Concise Style

File: .claude/output-styles/concise.md

Purpose: Brief, to-the-point responses

Characteristics:

• Minimal explanation
• Direct answers
• Code without commentary
• Short summaries

When to Use: Quick fixes, simple tasks, time pressure

Activation:

> /output-style concise

3. Professional Style

File: .claude/output-styles/professional.md

Purpose: Formal, business-appropriate tone

Characteristics:

• Formal language
• Structured responses
• Detailed documentation
• Business-friendly

When to Use: Client interactions, stakeholder communication, reports

Activation:

> /output-style professional

4. Verbose Style

File: .claude/output-styles/verbose.md

Purpose: Detailed, comprehensive explanations

Characteristics:

• Extensive detail
• Multiple examples
• Thorough rationale
• Educational depth

When to Use: Learning, onboarding, complex topics

Activation:

> /output-style verbose

5. Explanatory Style

File: .claude/output-styles/explanatory.md

Purpose: Educational insights and learning

Characteristics:

• Explains "why" decisions
• Pattern identification
• Learning opportunities
• Best practices focus

When to Use: Understanding codebases, learning patterns, educational context

Activation:

> /output-style explanatory

6. Learning Style

File: .claude/output-styles/learning.md

Purpose: Interactive learning mode

Characteristics:

• Claude asks YOU to code
• Provides guidance, not solutions
• Marks sections with TODO(human)
• Socratic method

When to Use: Skill development, hands-on learning, teaching

Activation:

> /output-style learning

7. Security Reviewer Style

File: .claude/output-styles/security-reviewer.md

Purpose: Security-focused analysis

Characteristics:

• Security-first mindset
• Vulnerability scanning
• Threat modeling
• Compliance checking

When to Use: Security audits, vulnerability assessment, compliance reviews

Activation:

> /output-style security-reviewer

Creating Custom Output Styles

Use the template at .claude/output-styles/.OUTPUT_STYLES_TEMPLATE.md

Example:

---
name: debugging-mode
description: Systematic debugging approach with detailed logging
---

# Debugging Mode Output Style

You are Claude in debugging mode...

## Characteristics
- Step-by-step analysis
- Hypothesis generation and testing
- Detailed logging
- Root cause identification

## Response Format
1. **Problem Analysis**: [Describe the issue]
2. **Hypotheses**: [List possible causes]
3. **Testing**: [Test each hypothesis]
4. **Solution**: [Recommended fix]

---

Hooks System

Overview

5 event hooks enable automatic execution of scripts at specific points in Claude Code's lifecycle.

How Hooks Work

Event Triggers: Hooks fire automatically when specific events occur

Script Execution: Shell scripts (.sh) or PowerShell (.ps1) execute with current environment

Security: Hooks run with your credentials - review before using

Configuration: Defined in .claude/settings.json under hooks key

Available Hooks

1. session-start Hook

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

Trigger: When Claude Code session begins or resumes

Purpose: Initialize session, setup logging, create directories

Current Implementation:

# Create logs directory if it doesn't exist
mkdir -p .claude/logs

# Log session start
echo "[$(date)] Session started in $(pwd) by $USER" >> .claude/logs/session.log

Use Cases:

• Initialize logging
• Setup environment variables
• Create required directories
• Display welcome messages

2. session-end Hook

File: .claude/hooks/session-end.sh

Trigger: When Claude Code session terminates

Purpose: Cleanup, final logging, backups

Use Cases:

• Final log entries
• Cleanup temporary files
• Create session backups
• Generate reports

3. pre-bash Hook

File: .claude/hooks/pre-bash.sh

Trigger: Before Bash tool executes commands

Purpose: Command validation, logging, permission checks

Use Cases:

• Log commands before execution
• Validate command safety
• Check permissions
• Block dangerous commands

4. post-write Hook

File: .claude/hooks/post-write.sh

Trigger: After Write or Edit tool modifies files

Purpose: Post-processing, formatting, logging

Current Implementation:

# Log file writes
echo "[$(date)] File written: $FILEPATH" >> .claude/logs/writes.log

# Auto-format certain files (commented out by default)
# if [[ $FILEPATH =~ \.(js|ts|tsx)$ ]]; then
#   npx prettier --write "$FILEPATH"
# fi

Use Cases:

• Auto-formatting (Prettier, Black, etc.)
• Linting
• Git add
• File logging
• Backup creation

5. user-prompt-submit Hook

File: .claude/hooks/user-prompt-submit.sh

Trigger: After user submits a prompt, before processing

Purpose: Prompt logging, validation, preprocessing

Use Cases:

• Log all user prompts
• Count prompt usage
• Validate input
• Track costs

Hook Configuration

Location: .claude/settings.json

Format:

{
  "hooks": {
    "PreToolUse": {
      "*": "bash .claude/hooks/pre-bash.sh"
    },
    "PostToolUse": {
      "Write": "bash .claude/hooks/post-write.sh",
      "Edit": "bash .claude/hooks/post-write.sh"
    },
    "SessionStart": "bash .claude/hooks/session-start.sh",
    "SessionEnd": "bash .claude/hooks/session-end.sh",
    "UserPromptSubmit": "bash .claude/hooks/user-prompt-submit.sh"
  }
}

Creating Custom Hooks

Example: Auto-commit Hook

# .claude/hooks/post-write.sh
#!/bin/bash

# Auto-commit changed files
if [[ -n "$FILEPATH" ]]; then
  git add "$FILEPATH"
  git commit -m "Auto-commit: Updated $FILEPATH via Claude Code"
fi

Example: Cost Tracking Hook

# .claude/hooks/user-prompt-submit.sh
#!/bin/bash

# Track prompt count
COUNT_FILE=".claude/logs/prompt_count.txt"
COUNT=$(cat "$COUNT_FILE" 2>/dev/null || echo "0")
echo $((COUNT + 1)) > "$COUNT_FILE"

---

Templates

Overview

4 comprehensive templates for extending Claude Code functionality.

Available Templates

1. SKILL_TEMPLATE.md

Location: .claude/skills/.SKILL_TEMPLATE.md

Purpose: Create model-invoked capabilities

Features:

• YAML frontmatter with allowed-tools
• Progressive disclosure pattern
• Multi-file organization
• Testing checklist
• Version history

When to Use: Auto-activated capabilities based on context

Example Use Cases:

• PDF processing skill
• Excel analysis skill
• Documentation generation skill

2. COMMANDS_TEMPLATE.md

Location: .claude/commands/.COMMANDS_TEMPLATE.md

Purpose: Create user-invoked slash commands

Features:

• Argument handling ($ARGUMENTS, $1, $2)
• Bash execution (! prefix)
• File references (@ prefix)
• Model selection
• Tool restrictions

When to Use: Explicit workflows and routines

Example Use Cases:

• /commit - Create git commits
• /deploy - Deployment workflow
• /generate-tests - Test generation

3. AGENT_TEMPLATE.md

Location: .claude/agents/.AGENT_TEMPLATE.md

Purpose: Create specialized subagents

Features:

• YAML frontmatter configuration
• Tool restrictions
• Model selection
• Workflow definitions
• Context management

When to Use: Domain-specific expertise needed

Example Use Cases:

• Research agent
• Implementation agent
• Review agent

4. OUTPUT_STYLES_TEMPLATE.md

Location: .claude/output-styles/.OUTPUT_STYLES_TEMPLATE.md

Purpose: Create custom response behaviors

Features:

• Behavior definition
• Response structure
• Use case guidance
• Testing checklist

When to Use: Need different communication style

Example Use Cases:

• Debugging mode
• Documentation mode
• Teaching mode

Template Usage Guide

See .claude/TEMPLATES_README.md for comprehensive guide including:

• Template comparison matrix
• Quick start guides
• Decision trees
• Best practices
• Troubleshooting

---

Configuration

Settings Files Hierarchy

Claude Code uses a 5-level hierarchy (highest to lowest priority):

1. Enterprise Policies - IT-deployed, cannot be overridden
2. Command Line Arguments - Session-specific (--model, --max-tokens, etc.)
3. Local Project Settings - .claude/settings.local.json (personal, not in git)
4. Shared Project Settings - .claude/settings.json (team-shared, in git)
5. User Settings - ~/.claude/settings.json (global personal)

Main Settings File

Location: .claude/settings.json

Key Sections:

Permissions

{
  "permissions": {
    "allowed": [
      "Read(*)",
      "Write(*)",
      "Edit(*)",
      "Glob(*)",
      "Grep(*)",
      "Bash(git status:*)",
      "Bash(git diff:*)",
      "Bash(npm test:*)",
      "mcp__serena__*",
      "mcp__memory__*",
      "mcp__context7__*",
      "WebSearch",
      "WebFetch"
    ],
    "ask": [
      "Bash(npm install:*)",
      "Bash(npm uninstall:*)"
    ],
    "denied": [
      "Bash(rm -rf /:*)",
      "Bash(mkfs:*)",
      "Bash(dd if=:*)"
    ]
  }
}

MCP Server Configuration

{
  "mcpServers": {
    "serena": {
      "enabled": true
    },
    "memory": {
      "enabled": true
    },
    "context7": {
      "enabled": true
    }
  }
}

Hooks Configuration

{
  "hooks": {
    "SessionStart": "bash .claude/hooks/session-start.sh",
    "SessionEnd": "bash .claude/hooks/session-end.sh",
    "PreToolUse": {
      "*": "bash .claude/hooks/pre-bash.sh"
    },
    "PostToolUse": {
      "Write": "bash .claude/hooks/post-write.sh",
      "Edit": "bash .claude/hooks/post-write.sh"
    },
    "UserPromptSubmit": "bash .claude/hooks/user-prompt-submit.sh"
  }
}

Status Line

{
  "statusLine": {
    "enabled": true,
    "command": "bash .claude/statusline.sh"
  }
}

Plugin Marketplace

{
  "extraKnownMarketplaces": [
    {
      "name": "anthropic-official",
      "url": "https://raw.githubusercontent.com/anthropics/skills/main/marketplace.json",
      "description": "Official Anthropic Skills Marketplace"
    }
  ]
}

MCP Configuration

Location: .mcp.json (project root)

Format:

{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--context", "ide-assistant", "--project", "Claude Code Setup"]
    },
    "memory": {
      "command": "powershell",
      "args": ["-ExecutionPolicy", "Bypass", "-File", ".\.claude\tools\start-memory.ps1"]
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"],
      "env": {
        "CONTEXT7_API_KEY": "your-api-key-here"
      }
    }
  }
}

Environment Variables

Key environment variables (set in settings.json or shell):

Authentication:

• ANTHROPIC_API_KEY - API key for Claude
• ANTHROPIC_AUTH_TOKEN - OAuth token

Model Configuration:

• DEFAULT_MODEL - Default Claude model
• MAX_TOKENS - Response token limit
• THINKING_TOKEN_LIMIT - Extended thinking budget

Features:

• DISABLE_TELEMETRY - Disable usage tracking
• DISABLE_AUTOUPDATER - Disable auto-updates

Network:

• HTTPS_PROXY - Proxy server
• SSL_CERT_FILE - Custom CA certificate

---

Memory & Context

Memory System Overview

Claude Code has hierarchical memory across 4 locations:

1. Enterprise Policy - Organization-wide instructions
2. Project Memory - ./CLAUDE.md or ./.claude/CLAUDE.md (team-shared)
3. User Memory - ~/.claude/CLAUDE.md (personal, all projects)
4. Project Memory (Local) - Deprecated

Project Instructions (CLAUDE.md)

Location: CLAUDE.md

Purpose: Provide project context, conventions, and guidelines to Claude

Sections:

• Project overview
• Technology stack
• Code style guidelines
• Testing requirements
• Commit message format
• Development workflow
• Security considerations
• Performance optimization

Best Practices:

• Keep current and updated
• Be specific and concrete
• Use examples liberally
• Structure with clear headings
• Link to external docs
• Review periodically

Import Files: Use @path/to/file syntax (max depth: 5)

Persistent Memory (Serena)

Storage: .serena/memories/

Persistence: Survives across sessions

Management:

# Write memory
mcp__serena__write_memory("adr-001-architecture", content)

# Read memory
mcp__serena__read_memory("adr-001-architecture")

# List all
mcp__serena__list_memories()

# Delete
mcp__serena__delete_memory("adr-001-architecture")

Current Memory: serena-persistence-test

Naming Conventions:

• ADRs: adr-001-database-choice-postgresql
• Reviews: code-review-2024-10-payment-service
• Lessons: lesson-async-error-handling
• Patterns: pattern-repository-implementation
• Debt: debt-legacy-api-authentication
• Security: security-audit-2024-10-full
• Performance: performance-optimization-query-caching

Temporary Memory (Knowledge Graph)

Storage: In-memory, cleared on session end

Management:

# Create entities
mcp__memory__create_entities([{name, entityType, observations}])

# Create relations
mcp__memory__create_relations([{from, to, relationType}])

# Search
mcp__memory__search_nodes("query")

# Read graph
mcp__memory__read_graph()

Best For: Current session context, temporary analysis

Context Management

File References:

• Include files in prompts with @path/to/file
• Glob patterns supported: @src/**/*.ts

Directory Context:

• Use /add-dir to add entire directories
• Claude maintains awareness of directory structure

Conversation History:

• Full history maintained in session
• Use /compact to condense long conversations
• Use /clear to start fresh

---

Advanced Features

1. Extended Thinking

What: Gives Claude more computation time for complex problems

Activation:

• Use keywords: think, think hard, think harder, ultrathink
• Each level increases computational budget
• Shown as thinking process in UI

When to Use:

• Architecture decisions
• Complex debugging
• Security analysis
• Algorithm optimization
• Design pattern selection

Example:

> "Think hard about the best architecture for this microservices system"

Token Limits: Configure with THINKING_TOKEN_LIMIT environment variable

2. Plan Mode

What: Read-only exploration before making changes

Activation: Toggle with Tab key

Benefits:

• Safe exploration
• No file modifications
• Understanding phase
• Review before action

Workflow:

1. Enter plan mode (Tab)
2. Explore and understand
3. Get approval for plan
4. Exit plan mode (Tab)
5. Execute changes

When to Use:

• Complex multi-file changes
• Unfamiliar codebases
• Major refactoring
• Architecture changes

3. Checkpointing

What: Rewind conversation and/or code to previous states

Activation: Press ESC ESC or /rewind

Options:

1. Code Only - Revert files, keep conversation
2. Conversation Only - Revert conversation, keep files
3. Both - Complete rollback

Retention: 30 days

When to Use:

• Experimental changes
• Wrong direction
• Need to try alternatives
• Accidental modifications

4. Git Integration

Pre-approved commands:

• git status
• git diff
• git log
• git show

Commit Creation: See Git Workflow in CLAUDE.md

Branch Management: Supported with appropriate permissions

5. Parallel Execution

Independent Commands: Run multiple bash commands in parallel

# Claude executes these simultaneously
git status && npm test && docker ps

Multiple Agents: Invoke multiple agents in parallel with Task tool

File Operations: Multiple Reads in parallel for efficiency

6. Session Resume

Resume Previous: claude --continue or claude --resume

Named Sessions: claude --session [name]

List Sessions: View available sessions to resume

7. Cost Tracking

View Costs: /cost command

Token Usage: Tracked per session

Breakdown:

• Input tokens
• Output tokens
• Thinking tokens (if used)
• Tool calls

Export: Available in settings for monitoring

8. Plugin Marketplace

Access: /plugin command

Sources:

• Official Anthropic marketplace
• Custom marketplaces (configured in settings)

Installation: Browse and install skills/commands/agents

Management: /plugin list, /plugin install [name]

---

Best Practices

General Guidelines

1. Start Broad, Then Narrow

   • Ask high-level questions first
   • Progressively dive into specifics
   • Use agents for focused deep-dives

2. Use Appropriate Tools

   • Agents for domains
   • Commands for workflows
   • Skills for auto-capabilities
   • Output styles for communication

3. Leverage Memory

   • Store ADRs in Serena memory
   • Use knowledge graph for session context
   • Keep CLAUDE.md updated

4. Optimize Performance

   • Use concise style for quick tasks
   • Leverage extended thinking for complex problems
   • Parallel execution when possible

5. Maintain Security

   • Review hooks before using
   • Restrict sensitive tool access
   • Use security-analyst agent for audits
   • Never commit secrets

Development Workflows

New Feature Development

# 1. Architecture planning
> "Use the architect agent to design user authentication feature"

# 2. Implementation
> /implement user authentication with JWT

# 3. Testing
> /test src/auth/

# 4. Review
> /review src/auth/

# 5. Documentation
> "Use documentation-writer agent to document authentication"

# 6. Commit
> "Create a git commit for this feature"

Debugging

# 1. Use debugger agent
> "Use the debugger agent to investigate this error: [paste error]"

# 2. Extended thinking for complex issues
> "Think hard about why this race condition occurs"

# 3. Review fix
> /review [fixed file]

# 4. Test
> /test

Code Review

# 1. Review changes
> /review src/

# 2. Security check
> "Use security-analyst agent to check for vulnerabilities"

# 3. Generate suggestions
> "Use refactoring-specialist agent to suggest improvements"

MCP Usage Patterns

Code Navigation

# Find symbol
find_symbol("UserService")

# Find references
find_referencing_symbols("UserService", "src/services/user.ts")

# Get overview
get_symbols_overview("src/services/user.ts")

Persistent Knowledge

# Store ADR
write_memory("adr-001-auth-jwt", "Decision: Use JWT for auth...")

# Recall later
read_memory("adr-001-auth-jwt")

Documentation Lookup

# Resolve library
resolve-library-id("react")

# Get docs
get-library-docs("/facebook/react")

Optimization Tips

1. Model Selection

   • Haiku for simple tasks (fast, cheap)
   • Sonnet for general development (balanced)
   • Opus for complex reasoning (powerful)

2. Token Efficiency

   • Use concise style when appropriate
   • Leverage Glob/Grep instead of reading all files
   • Use Serena symbol tools instead of full file reads

3. Parallel Work

   • Multiple file reads in one message
   • Parallel agent invocation
   • Independent bash commands together

4. Context Management

   • Regular /compact for long sessions
   • Use knowledge graph for session state
   • Clear when switching major tasks

---

Troubleshooting

Common Issues

Agents Not Activating

Problem: Agent doesn't activate automatically

Solutions:

1. Check description has relevant keywords
2. Try manual invocation
3. Verify agent file is in .claude/agents/
4. Restart Claude to reload agents
5. Check YAML frontmatter is valid

Commands Not Found

Problem: /command not recognized

Solutions:

1. Verify file is .claude/commands/[name].md
2. Filename must match command name
3. Restart Claude to reload commands
4. Check /help to see available commands
5. Validate frontmatter syntax

MCP Server Failures

Problem: MCP server not connecting

Solutions:

1. Check .mcp.json configuration
2. Verify command path is correct
3. Test command manually in terminal
4. Check logs for error messages
5. Ensure dependencies installed (npx, uvx, etc.)

Hook Not Executing

Problem: Hook script doesn't run

Solutions:

1. Check hook is configured in settings.json
2. Verify script path is correct
3. Ensure script has execute permissions
4. Check script syntax (bash/PowerShell)
5. Look for errors in logs

Permission Denied

Problem: Tool execution blocked

Solutions:

1. Check permissions in settings.json
2. Add tool to allowed array
3. Use wildcards for patterns
4. Restart Claude after changes
5. Check for enterprise policies overriding

Debugging Steps

1. Check Logs

   • Session log: .claude/logs/session.log
   • Bash log: .claude/logs/bash.log
   • Write log: .claude/logs/writes.log

2. Verify Configuration

   # Check settings
   cat .claude/settings.json | jq '.permissions'
   
   # Check MCP config
   cat .mcp.json | jq '.mcpServers'
   

3. Test Components

   # Test MCP server manually
   npx -y @modelcontextprotocol/server-sequential-thinking
   
   # Test hook script
   bash .claude/hooks/session-start.sh
   

4. Use Diagnostic Commands

   > /setup-info          # Display configuration
   > /doctor              # Diagnose installation
   > /mcp                 # Check MCP status
   

Getting Help

1. Built-in Help: /help command
2. Setup Info: /setup-info command
3. Official Docs: https://docs.claude.com/en/docs/claude-code/
4. GitHub Issues: https://github.com/anthropics/claude-code/issues
5. This Documentation: Review relevant sections above

---

Appendix

Quick Reference

Key Files

• .claude/settings.json - Main configuration
• .mcp.json - MCP servers
• CLAUDE.md - Project instructions
• .claude/agents/ - Specialized agents
• .claude/commands/ - Slash commands
• .claude/output-styles/ - Response styles
• .claude/hooks/ - Event automation

Key Commands

• /help - Get help
• /setup-info - Display setup
• /plugin - Plugin marketplace
• /output-style [style] - Change style
• /cost - View costs
• /rewind - Checkpointing
• /memory - Edit memory
• /compact - Condense conversation
• /clear - Clear history

Key Shortcuts

• Tab - Toggle plan mode
• ESC ESC - Access checkpoints
• Ctrl+C - Interrupt Claude
• @file - Reference file
• # - Quick memory capture

File Naming Conventions

Agents: kebab-case.md in .claude/agents/ Commands: kebab-case.md in .claude/commands/ Skills: Directory with SKILL.md in .claude/skills/[name]/ Output Styles: kebab-case.md in .claude/output-styles/ Hooks: event-name.sh or event-name.ps1 in .claude/hooks/

Version History

• v3.0.0 (2025-10-20): Complete documentation overhaul, added missing capabilities
• v2.0.0 (2025-10-17): Added output styles, plugins, status line
• v1.0.0 (Initial): Basic setup with agents, commands, MCP

Credits

Based on:

• Official Anthropic Claude Code documentation
• Claude Agent SDK best practices
• Community contributions
• Real-world production experience

---

Documentation Version: 3.0.0 Last Updated: 2025-10-20 Maintained by: Claude Code Setup Project License: Use and modify freely

For the most current information, always refer to official documentation at: https://docs.claude.com/en/docs/claude-code/

---

This setup represents ~95% of available Claude Code capabilities. The remaining 5% includes enterprise features (SSO, analytics), headless mode (CI/CD), and specialized network configurations (proxies, certificates) which are optional and environment-specific.