591 lines
14 KiB
Markdown
591 lines
14 KiB
Markdown
# Claude Code Setup - Complete Claude Code Configuration
|
|
|
|
> **Production-ready Claude Code setup with comprehensive documentation**
|
|
> **Version**: 3.0.0 | **Last Updated**: 2025-10-20
|
|
|
|
---
|
|
|
|
## 🚀 Quick Start
|
|
|
|
**New to this project?** Start here: **[QUICKSTART.md](QUICKSTART.md)** (5-minute read)
|
|
|
|
**Need complete details?** See: **[CLAUDE_CODE_SETUP_COMPLETE.md](CLAUDE_CODE_SETUP_COMPLETE.md)** (comprehensive)
|
|
|
|
---
|
|
|
|
## 📋 What's Included
|
|
|
|
This project demonstrates a **fully configured Claude Code setup** with:
|
|
|
|
### Core Features (100% Configured)
|
|
|
|
✅ **8 MCP Servers**
|
|
- Serena (code navigation + persistent memory)
|
|
- Sequential Thinking (complex reasoning)
|
|
- Context7 (real-time library docs)
|
|
- Memory (knowledge graph)
|
|
- Playwright (browser automation)
|
|
- Windows MCP (desktop automation)
|
|
- Fetch (web scraping)
|
|
- Database Server
|
|
|
|
✅ **8 Specialized Agents**
|
|
- Architect, Code Reviewer, Debugger
|
|
- Documentation Writer, Project Manager
|
|
- Refactoring Specialist, Security Analyst, Test Engineer
|
|
|
|
✅ **9 Slash Commands**
|
|
- `/analyze`, `/review`, `/implement`, `/test`
|
|
- `/optimize`, `/explain`, `/scaffold`, `/setup-info`, `/adr`
|
|
|
|
✅ **6 Output Styles**
|
|
- Concise, Professional, Verbose
|
|
- Explanatory, Learning, Security Reviewer
|
|
|
|
✅ **6 Event Hooks**
|
|
- Session lifecycle (start/end)
|
|
- Bash command interception
|
|
- File write logging
|
|
- User prompt tracking
|
|
- Stop tracking for summaries
|
|
|
|
✅ **Complete Templates**
|
|
- Agent Template, Command Template
|
|
- Skill Template, Output Style Template
|
|
- CLAUDE.md Project Template
|
|
|
|
✅ **Automatic Status Summaries**
|
|
- Every task completion includes detailed summary
|
|
- Shows agents, commands, MCP servers used
|
|
- Lists all files modified
|
|
- Promotes transparency and learning
|
|
|
|
---
|
|
|
|
## 📚 Documentation
|
|
|
|
### For Users
|
|
|
|
| Document | Purpose | Read Time |
|
|
|----------|---------|-----------|
|
|
| **[QUICKSTART.md](QUICKSTART.md)** | Get started quickly | 5 min |
|
|
| **[CLAUDE_CODE_SETUP_COMPLETE.md](CLAUDE_CODE_SETUP_COMPLETE.md)** | Complete documentation | 30 min |
|
|
| **[MCP_SERVERS_GUIDE.md](MCP_SERVERS_GUIDE.md)** | Complete MCP server documentation | 20 min |
|
|
| **[CLAUDE.md](CLAUDE.md)** | Project instructions for Claude | Reference |
|
|
|
|
### For Developers
|
|
|
|
| Document | Purpose |
|
|
|----------|---------|
|
|
| **[CLAUDE_TEMPLATE.md](CLAUDE_TEMPLATE.md)** | Template for new projects |
|
|
| **[.claude/TEMPLATES_README.md](.claude/TEMPLATES_README.md)** | Master template guide |
|
|
| **[.claude/agents/MCP_USAGE_TEMPLATES.md](.claude/agents/MCP_USAGE_TEMPLATES.md)** | MCP usage templates for agents |
|
|
| **[.claude/TEMPLATE_CAPABILITIES_ANALYSIS.md](.claude/TEMPLATE_CAPABILITIES_ANALYSIS.md)** | Template review & missing features |
|
|
|
|
### Specialized Guides
|
|
|
|
| Document | Purpose |
|
|
|----------|---------|
|
|
| **[MCP_SERVERS_GUIDE.md](MCP_SERVERS_GUIDE.md)** | Complete MCP server documentation |
|
|
| **[.claude/CHECKPOINTING_GUIDE.md](.claude/CHECKPOINTING_GUIDE.md)** | Session checkpointing |
|
|
| **[.claude/PLUGIN_SETUP.md](.claude/PLUGIN_SETUP.md)** | Plugin marketplace |
|
|
| **[.claude/STATUS_LINE_SETUP.md](.claude/STATUS_LINE_SETUP.md)** | Status line customization |
|
|
|
|
---
|
|
|
|
## 🎯 Key Capabilities
|
|
|
|
### Intelligent Code Navigation (Serena MCP)
|
|
|
|
```bash
|
|
# Find symbols
|
|
find_symbol("UserService")
|
|
|
|
# Find references
|
|
find_referencing_symbols("authenticate", "src/auth/")
|
|
|
|
# Store persistent knowledge
|
|
write_memory("adr-001-architecture", "Decision: Microservices...")
|
|
```
|
|
|
|
### Specialized Agents (8 Available)
|
|
|
|
```bash
|
|
# Automatic invocation
|
|
> "I need to design a microservices architecture"
|
|
# → Architect agent activated
|
|
|
|
# Manual invocation
|
|
> "Use the security-analyst agent to review this code"
|
|
```
|
|
|
|
### Development Workflows (8 Commands)
|
|
|
|
```bash
|
|
/analyze src/ # Code analysis
|
|
/review src/ # Code review
|
|
/implement feature # Build features
|
|
/test # Run tests
|
|
/optimize file.ts # Performance tuning
|
|
```
|
|
|
|
### Extended Thinking
|
|
|
|
```bash
|
|
> "Think hard about the best database architecture"
|
|
> "Ultrathink: How to optimize this algorithm?"
|
|
```
|
|
|
|
### Custom Output Modes (6 Styles)
|
|
|
|
```bash
|
|
/output-style learning # Interactive learning
|
|
/output-style security-reviewer # Security focus
|
|
/output-style explanatory # Educational insights
|
|
```
|
|
|
|
---
|
|
|
|
## 📁 Project Structure
|
|
|
|
```
|
|
Claude Code Setup/
|
|
├── README.md # This file
|
|
├── QUICKSTART.md # Quick start guide (5 min)
|
|
├── CLAUDE_CODE_SETUP_COMPLETE.md # Complete documentation (30 min)
|
|
├── CLAUDE.md # Project instructions
|
|
├── CLAUDE_TEMPLATE.md # Project template
|
|
│
|
|
├── .mcp.json # MCP servers configuration
|
|
│
|
|
└── .claude/ # Main configuration directory
|
|
├── settings.json # Shared configuration
|
|
├── settings.local.json # Personal configuration
|
|
│
|
|
├── agents/ # 8 specialized agents
|
|
│ ├── architect.md
|
|
│ ├── code-reviewer.md
|
|
│ ├── debugger.md
|
|
│ ├── documentation-writer.md
|
|
│ ├── project-manager.md
|
|
│ ├── refactoring-specialist.md
|
|
│ ├── security-analyst.md
|
|
│ ├── test-engineer.md
|
|
│ └── .AGENT_TEMPLATE.md
|
|
│
|
|
├── commands/ # 9 slash commands
|
|
│ ├── adr.md
|
|
│ ├── analyze.md
|
|
│ ├── explain.md
|
|
│ ├── implement.md
|
|
│ ├── optimize.md
|
|
│ ├── review.md
|
|
│ ├── scaffold.md
|
|
│ ├── setup-info.md
|
|
│ ├── test.md
|
|
│ └── .COMMANDS_TEMPLATE.md
|
|
│
|
|
├── output-styles/ # 6 custom styles
|
|
│ ├── concise.md
|
|
│ ├── professional.md
|
|
│ ├── verbose.md
|
|
│ ├── explanatory.md
|
|
│ ├── learning.md
|
|
│ ├── security-reviewer.md
|
|
│ └── .OUTPUT_STYLES_TEMPLATE.md
|
|
│
|
|
├── skills/ # Skills directory
|
|
│ └── .SKILL_TEMPLATE.md
|
|
│
|
|
├── hooks/ # 5 event hooks
|
|
│ ├── session-start.sh
|
|
│ ├── session-end.sh
|
|
│ ├── pre-bash.sh
|
|
│ ├── post-write.sh
|
|
│ └── user-prompt-submit.sh
|
|
│
|
|
├── tools/ # Utility scripts
|
|
│ ├── start-memory.ps1
|
|
│ └── statusline.sh
|
|
│
|
|
├── logs/ # Session logs
|
|
│
|
|
└── [Documentation Files]
|
|
├── TEMPLATES_README.md
|
|
├── MCP_CORRECT_USAGE_GUIDE.md
|
|
├── TEMPLATE_CAPABILITIES_ANALYSIS.md
|
|
├── CHECKPOINTING_GUIDE.md
|
|
├── PLUGIN_SETUP.md
|
|
└── STATUS_LINE_SETUP.md
|
|
```
|
|
|
|
---
|
|
|
|
## 🚦 Getting Started
|
|
|
|
### 1. First Time Setup (1 minute)
|
|
|
|
```bash
|
|
# Clone or open this project
|
|
cd "Claude Code Setup"
|
|
|
|
# Start Claude Code
|
|
claude
|
|
|
|
# Verify setup
|
|
> /setup-info
|
|
```
|
|
|
|
### 2. Try Basic Commands (2 minutes)
|
|
|
|
```bash
|
|
# Get help
|
|
> /help
|
|
|
|
# See what's configured
|
|
> /setup-info
|
|
|
|
# Try a command
|
|
> /analyze src/
|
|
|
|
# Try an agent
|
|
> "Use the architect agent to explain the project structure"
|
|
```
|
|
|
|
### 3. Learn Core Features (5 minutes)
|
|
|
|
Read **[QUICKSTART.md](QUICKSTART.md)** for:
|
|
- Essential commands
|
|
- MCP server usage
|
|
- Agent invocation
|
|
- Output styles
|
|
- Memory system
|
|
|
|
### 4. Deep Dive (30 minutes)
|
|
|
|
Read **[CLAUDE_CODE_SETUP_COMPLETE.md](CLAUDE_CODE_SETUP_COMPLETE.md)** for complete details on:
|
|
- All MCP servers and capabilities
|
|
- Agent configuration and usage
|
|
- Slash command reference
|
|
- Hooks system
|
|
- Templates
|
|
- Advanced features
|
|
- Best practices
|
|
|
|
---
|
|
|
|
## 💡 Common Use Cases
|
|
|
|
### Feature Development
|
|
|
|
```bash
|
|
# 1. Architecture
|
|
> "Use architect agent to design payment integration"
|
|
|
|
# 2. Implement
|
|
> /implement Stripe payment integration
|
|
|
|
# 3. Test
|
|
> /test src/payments/
|
|
|
|
# 4. Review
|
|
> /review src/payments/
|
|
|
|
# 5. Document
|
|
> "Use documentation-writer agent to document payment flow"
|
|
```
|
|
|
|
### Bug Fixing
|
|
|
|
```bash
|
|
# 1. Debug
|
|
> "Use debugger agent: [paste error]"
|
|
|
|
# 2. Extended thinking (for complex bugs)
|
|
> "Think hard about this race condition"
|
|
|
|
# 3. Review fix
|
|
> /review [fixed file]
|
|
```
|
|
|
|
### Code Review
|
|
|
|
```bash
|
|
# 1. Standard review
|
|
> /review src/
|
|
|
|
# 2. Security check
|
|
> "Use security-analyst agent to check vulnerabilities"
|
|
|
|
# 3. Refactoring suggestions
|
|
> "Use refactoring-specialist agent for improvements"
|
|
```
|
|
|
|
### Learning Codebase
|
|
|
|
```bash
|
|
# 1. Use explanatory style
|
|
> /output-style explanatory
|
|
|
|
# 2. High-level questions
|
|
> "Explain the architecture of this project"
|
|
|
|
# 3. Deep dive with Serena
|
|
> get_symbols_overview("src/core/engine.ts")
|
|
|
|
# 4. Store learnings
|
|
> write_memory("architecture-overview", "The system uses...")
|
|
```
|
|
|
|
---
|
|
|
|
## 🎓 Learning Path
|
|
|
|
### Beginner (Day 1)
|
|
|
|
1. Read [QUICKSTART.md](QUICKSTART.md)
|
|
2. Try basic commands (`/help`, `/setup-info`)
|
|
3. Experiment with one agent
|
|
4. Try one output style
|
|
|
|
### Intermediate (Week 1)
|
|
|
|
1. Use all slash commands
|
|
2. Work with multiple agents
|
|
3. Try extended thinking
|
|
4. Use Serena MCP for code navigation
|
|
|
|
### Advanced (Month 1)
|
|
|
|
1. Create custom commands
|
|
2. Build custom agents
|
|
3. Configure hooks for your workflow
|
|
4. Leverage all MCP servers
|
|
|
|
---
|
|
|
|
## 🔧 Customization
|
|
|
|
### Add a Custom Command
|
|
|
|
```bash
|
|
# Copy template
|
|
cp .claude/commands/.COMMANDS_TEMPLATE.md .claude/commands/my-command.md
|
|
|
|
# Edit and configure
|
|
# Use it
|
|
> /my-command
|
|
```
|
|
|
|
### Add a Custom Agent
|
|
|
|
```bash
|
|
# Copy template
|
|
cp .claude/agents/.AGENT_TEMPLATE.md .claude/agents/my-agent.md
|
|
|
|
# Configure and use
|
|
> "Use the my-agent agent to..."
|
|
```
|
|
|
|
### Add a Custom Output Style
|
|
|
|
```bash
|
|
# Copy template
|
|
cp .claude/output-styles/.OUTPUT_STYLES_TEMPLATE.md .claude/output-styles/my-style.md
|
|
|
|
# Activate
|
|
> /output-style my-style
|
|
```
|
|
|
|
See [.claude/TEMPLATES_README.md](.claude/TEMPLATES_README.md) for detailed guides.
|
|
|
|
---
|
|
|
|
## 🤝 Team Setup
|
|
|
|
### Sharing This Setup
|
|
|
|
```bash
|
|
# Everything is in git, just commit and push
|
|
git add .claude/ .mcp.json CLAUDE.md
|
|
git commit -m "Add Claude Code configuration"
|
|
git push
|
|
|
|
# Team members pull and get full setup
|
|
git pull
|
|
```
|
|
|
|
### Team Customization
|
|
|
|
**Shared (in git)**:
|
|
- `.claude/settings.json`
|
|
- `.claude/agents/`
|
|
- `.claude/commands/`
|
|
- `.mcp.json`
|
|
- `CLAUDE.md`
|
|
|
|
**Personal (not in git)**:
|
|
- `.claude/settings.local.json`
|
|
- `~/.claude/` (user-wide)
|
|
|
|
---
|
|
|
|
## 📊 Setup Completeness
|
|
|
|
**Current**: ~95% of Claude Code capabilities implemented
|
|
|
|
**Implemented**:
|
|
- ✅ MCP servers
|
|
- ✅ Agents/Subagents
|
|
- ✅ Slash commands
|
|
- ✅ Output styles
|
|
- ✅ Hooks
|
|
- ✅ Templates
|
|
- ✅ Memory system
|
|
- ✅ Extended thinking
|
|
- ✅ Plan mode
|
|
- ✅ Checkpointing
|
|
- ✅ Plugin marketplace
|
|
|
|
**Optional (not implemented)**:
|
|
- ⚠️ Enterprise SSO/Analytics
|
|
- ⚠️ Headless mode (CI/CD)
|
|
- ⚠️ Network proxies/certificates
|
|
|
|
---
|
|
|
|
## 🖥️ Platform Notes
|
|
|
|
### Windows-Only Components
|
|
|
|
The following components are **Windows-specific** and will not work on Mac/Linux:
|
|
|
|
- **Windows MCP** ([.windows-mcp/](.windows-mcp/)) - Desktop automation using Python/uv
|
|
- Provides Windows UI automation, PowerShell execution, clipboard operations
|
|
- **Impact on other platforms**: Will show error on startup but won't affect other MCP servers
|
|
- **Solution for Mac/Linux**: Ignore Windows MCP errors or disable in `.mcp.json`
|
|
|
|
- **PowerShell Scripts**:
|
|
- [.claude/tools/start-memory.ps1](.claude/tools/start-memory.ps1) - Memory MCP launcher
|
|
- Various hook scripts using PowerShell commands
|
|
- **Alternative**: Create bash equivalents for cross-platform support
|
|
|
|
### Cross-Platform Components
|
|
|
|
All other MCP servers work on all platforms:
|
|
- ✅ Serena (Python/uvx)
|
|
- ✅ Sequential Thinking (Node.js/npx)
|
|
- ✅ Database Server (Node.js/npx)
|
|
- ✅ Context7 (Node.js/npx)
|
|
- ✅ Memory (works via Node.js on all platforms - PowerShell launcher is Windows-only convenience)
|
|
- ✅ Fetch (Python/uvx)
|
|
- ✅ Playwright (Node.js/npx)
|
|
|
|
### Disabling Windows MCP on Mac/Linux
|
|
|
|
If you're on Mac/Linux and want to disable Windows MCP to avoid startup errors:
|
|
|
|
**Option 1: Comment out in .mcp.json**
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
// "windows-mcp": {
|
|
// "command": "uv",
|
|
// "args": ["--directory", "./.windows-mcp", "run", "main.py"]
|
|
// },
|
|
// ... other servers
|
|
}
|
|
}
|
|
```
|
|
|
|
**Option 2: Disable in settings**
|
|
```json
|
|
// In .claude/settings.json or .claude/settings.local.json
|
|
{
|
|
"mcpServers": {
|
|
"windows-mcp": {
|
|
"enabled": false
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 🐛 Troubleshooting
|
|
|
|
Quick fixes:
|
|
|
|
```bash
|
|
# Agent not working?
|
|
> "Use the [agent-name] agent to..." # Manual invocation
|
|
|
|
# Command not found?
|
|
> /help # List available commands
|
|
|
|
# MCP server failed?
|
|
cat .mcp.json | jq '.mcpServers' # Check configuration
|
|
|
|
# Permission denied?
|
|
cat .claude/settings.json | jq '.permissions' # Check permissions
|
|
|
|
# Windows MCP error on Mac/Linux?
|
|
# This is normal - see Platform Notes above
|
|
```
|
|
|
|
See [CLAUDE_CODE_SETUP_COMPLETE.md](CLAUDE_CODE_SETUP_COMPLETE.md#troubleshooting) for detailed troubleshooting.
|
|
|
|
---
|
|
|
|
## 📖 Resources
|
|
|
|
### Official Documentation
|
|
|
|
- **Claude Code Docs**: https://docs.claude.com/en/docs/claude-code/
|
|
- **GitHub Issues**: https://github.com/anthropics/claude-code/issues
|
|
|
|
### This Project
|
|
|
|
- **Quick Start**: [QUICKSTART.md](QUICKSTART.md)
|
|
- **Complete Guide**: [CLAUDE_CODE_SETUP_COMPLETE.md](CLAUDE_CODE_SETUP_COMPLETE.md)
|
|
- **MCP Servers**: [MCP_SERVERS_GUIDE.md](MCP_SERVERS_GUIDE.md)
|
|
- **Templates**: [.claude/TEMPLATES_README.md](.claude/TEMPLATES_README.md)
|
|
- **MCP Templates**: [.claude/agents/MCP_USAGE_TEMPLATES.md](.claude/agents/MCP_USAGE_TEMPLATES.md)
|
|
|
|
---
|
|
|
|
## 🎉 Success Checklist
|
|
|
|
After setup, you should be able to:
|
|
|
|
- [x] Run `/setup-info` and see full configuration
|
|
- [x] Use slash commands like `/analyze`, `/review`, `/test`
|
|
- [x] Invoke agents automatically or manually
|
|
- [x] Change output styles with `/output-style`
|
|
- [x] Use Serena MCP for code navigation
|
|
- [x] Store persistent memories
|
|
- [x] Use extended thinking for complex problems
|
|
- [x] Access checkpoints with ESC ESC
|
|
|
|
**Ready?** Start with [QUICKSTART.md](QUICKSTART.md)!
|
|
|
|
---
|
|
|
|
## 📝 Version History
|
|
|
|
- **v3.0.0** (2025-10-20): Complete documentation overhaul, consolidated docs, added /adr command
|
|
- **v2.0.0** (2025-10-17): Added output styles, plugins, status line
|
|
- **v1.0.0**: Initial comprehensive setup
|
|
|
|
---
|
|
|
|
## 📄 License
|
|
|
|
This configuration setup is provided as-is for educational and development purposes. Feel free to use, modify, and share.
|
|
|
|
---
|
|
|
|
**Questions?** Check the documentation files or see [troubleshooting](#troubleshooting)
|
|
|
|
**Ready to start?** → **[QUICKSTART.md](QUICKSTART.md)**
|