Initial commit: Fresh start with current state
This commit is contained in:
Claude Code
590
README.md
Normal file
590
README.md
Normal file
@@ -0,0 +1,590 @@
|
||||
# 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)**
|
||||
Reference in New Issue
Block a user