dotfiles

22.3 KB•MD
README.md
22.3 KB • 575 lines • markdown
1# ðï¸ Claude Code Studio
2
3> **Finally, conversations with Claude Code that don't hit context limits**
4
5[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6[![Claude Code Compatible](https://img.shields.io/badge/Claude%20Code-Compatible-blue.svg)](https://claude.ai/code)
7[![Agents](https://img.shields.io/badge/Agents-40+-green.svg)](#agent-system)
8[![MCP Servers](https://img.shields.io/badge/MCP%20Servers-12-orange.svg)](#mcp-integration)
9
10## ð The #1 Frustration with Claude Code - SOLVED
11
12**Problem**: Your conversations die at 50-100 messages. Context limits kill productivity. You lose all project knowledge every time you hit the wall.
13
14**Solution**: **Agent delegation keeps conversations clean and unlimited.**
15
16### â¡ Before vs After
17
18| **Without Claude Code Studio** | **With Claude Code Studio** |
19|--------------------------------|------------------------------|
20| â 50-100 messages max | â 300+ messages and counting |
21| â Context bloat from mixed topics | â Clean context via agent delegation |
22| â Lost project knowledge | â Persistent project memory |
23| â Restart every 2 hours | â All-day development sessions |
24| â Repeat explanations constantly | â Agents remember everything |
25
26### ð§  How Agent Delegation Enables Unlimited Conversations
27
28**The Secret**: Instead of cramming everything into one conversation, specialized agents spawn with **fresh, focused context** for each task:
29
30```mermaid
31graph LR
32    A[Main Conversation] --> B[file-creator agent]
33    A --> C[backend-architect agent]  
34    A --> D[test-runner agent]
35    A --> E[git-workflow agent]
36    
37    B --> F[Clean context + file creation expertise]
38    C --> G[Clean context + backend architecture expertise]
39    D --> H[Clean context + testing expertise]
40    E --> I[Clean context + git workflow expertise]
41```
42
43**Real Example**: Instead of this context-killing pattern:
44```
45You: Create a React component
46Claude: [300 lines of code + explanation]
47You: Now add tests
48Claude: [200 lines of tests + context about previous component]  
49You: Add styling
50Claude: [150 lines of CSS + rehashing component details]
51// Continue until context limit hit at ~50-100 messages
52```
53
54**You get this clean pattern**:
55```
56You: Create a React component
57â file-creator agent spawns with clean context â Creates component
58You: Now add tests  
59â test-writer-fixer agent spawns with clean context â Creates tests
60You: Add styling
61â frontend-developer agent spawns with clean context â Adds styles
62// Continue indefinitely - each agent gets fresh context
63```
64
65## ð Beyond Context Management
66
67**Claude Code Studio** transforms Claude Code into a complete AI-powered development studio with agent delegation as the core technology that enables unlimited conversations **PLUS**:
68
69- ð¯ **40+ Specialized Agents**: Domain experts with 500+ word system prompts
70- ð§ **12 Intelligent MCP Integrations**: Tools that work together seamlessly  
71- ð **Systematic Development**: Evidence-based principles and safety protocols
72- â¡ **Lightweight Context**: Only ~13k tokens (both conversation start and agent spawn)
73- ð **Production Ready**: Battle-tested configurations for real projects
74- ð **Extensible**: Easy to customize and extend for your specific needs
75
76## â¨ Key Features
77
78### ð¤ 40+ Specialized Agents
79- **Engineering**: Backend architects, frontend developers, mobile builders, AI engineers
80- **Design**: UI designers, UX researchers, brand guardians, visual storytellers
81- **Marketing**: Growth hackers, social media strategists, content creators
82- **Product**: Sprint prioritizers, feedback synthesizers, trend researchers
83- **Operations**: Analytics reporters, finance trackers, support responders
84
85### ð ï¸ 12 MCP Server Integrations
86- **Code Analysis**: Serena (semantic analysis), IDE integration, Sequential thinking
87- **Documentation**: Context7 (library docs), Readwise (knowledge management)
88- **Testing**: Playwright, Puppeteer (browser automation)
89- **Database**: Supabase integration with intelligent query optimization
90- **Deployment**: Vercel integration with automated workflows
91- **Monitoring**: Sentry error tracking with AI-powered analysis
92
93### ð¬ Conversation Longevity Benefits
94
95**Quantified Results from Real Usage:**
96- **Average conversation length**: 300+ messages (vs 50-100 without studio)
97- **Context efficiency**: 90% reduction in repeated explanations
98- **Development sessions**: Full day productivity without restarts
99- **Project continuity**: Persistent knowledge across all interactions
100
101**Why This Changes Everything:**
102- **No More Context Anxiety**: Develop features without watching message counts
103- **Persistent Project Memory**: Agents remember your patterns and preferences  
104- **Seamless Handoffs**: Switch between tasks without losing context
105- **All-Day Development**: Morning to evening sessions without interruption
106
107### ð¯ Core Principles
108- **Agent-First**: Specialized expertise over general-purpose approaches
109- **Evidence > Assumptions**: All decisions backed by data and testing
110- **Fresh Context**: Agent delegation prevents conversation bloat
111- **Efficiency > Verbosity**: Direct answers, minimal overhead
112
113## ð Quick Start
114
115**Get unlimited conversations in 3 steps:**
116
117Choose your installation method based on your current setup:
118
119### ð New Users (No existing ~/.claude setup)
120```bash
121# Simple installation
122git clone https://github.com/your-username/claude-code-studio.git ~/.claude
123cd ~/.claude
124
125# Customize your environment
126cp CONTEXT_TEMPLATE.md CONTEXT.md
127# Edit CONTEXT.md with your personal details
128```
129
130### ð Existing Users (Have ~/.claude setup)
131**Safe backup and replace method:**
132
133```bash
134# 1. Backup your current setup
135cp -r ~/.claude ~/.claude-backup
136
137# 2. Install studio (replaces existing)
138git clone https://github.com/your-username/claude-code-studio.git ~/.claude
139cd ~/.claude
140
141# 3. Restore your personal files
142cp ~/.claude-backup/CONTEXT.md ~/.claude/ 2>/dev/null || echo "No existing CONTEXT.md found"
143cp ~/.claude-backup/settings*.json ~/.claude/ 2>/dev/null || echo "No existing settings found"
144
145# 4. Merge MCP configurations (see step 2 below)
146```
147
148> ð¡ **Safety First**: Your backup at `~/.claude-backup` lets you revert anytime with `rm -rf ~/.claude && mv ~/.claude-backup ~/.claude`
149
150### 2. Configure MCP Servers
151Add these servers to your existing `.claude.json` or MCP configuration:
152
153**Critical servers (essential):**
154```json
155{
156  "mcpServers": {
157    "git": { "type": "stdio", "command": "uvx", "args": ["mcp-server-git"] },
158    "serena": { "type": "stdio", "command": "uvx", "args": ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--context", "ide-assistant"] },
159    "sequential-thinking": { "type": "stdio", "command": "npx", "args": ["@modelcontextprotocol/server-sequential-thinking"] }
160  }
161}
162```
163
164**High priority servers (stack-dependent):**
165```json
166{
167  "supabase": { "type": "stdio", "command": "npx", "args": ["@supabase/mcp-server-supabase@latest"], "env": { "SUPABASE_ACCESS_TOKEN": "[YOUR_TOKEN]" } },
168  "sentry": { "type": "http", "url": "https://mcp.sentry.dev/mcp" },
169  "context7": { "type": "stdio", "command": "npx", "args": ["@upstash/context7-mcp"] },
170  "playwright": { "type": "stdio", "command": "npx", "args": ["@playwright/mcp@latest"] }
171}
172```
173
174> ð¡ Most servers auto-install via `npx` on first use. See [MCP Integration](#-mcp-integration) section for complete setup.
175
176### 3. Basic Setup
177```bash
178# Verify installation
179ls -la ~/.claude
180
181# Customize your environment (optional)
182cp CONTEXT_TEMPLATE.md CONTEXT.md
183# Edit CONTEXT.md with your personal details
184```
185
186### 3. First Unlimited Conversation
187Try an agent-powered workflow that won't consume your context:
188```
189Create a new React component with TypeScript and tests for a user profile card
190```
191
192**Watch the magic happen:**
193- `file-creator` agent spawns with fresh context â Creates files
194- `frontend-developer` agent spawns with fresh context â Builds component  
195- `test-writer-fixer` agent spawns with fresh context â Generates tests
196- Your main conversation stays clean â Ready for the next 297 messages
197
198**Result**: You just completed a complex task using **0% of your conversation context**.
199
200## ð§ Detailed Setup
201
202### Core Configuration Files
203
204| File | Purpose | Customization |
205|------|---------|---------------|
206| `CLAUDE.md` | Main entry point, references all other configs | Usually no changes needed |
207| `CONTEXT.md` | Personal development environment details | **Customize for your setup** |
208| `AGENTS.md` | 40+ agent definitions and workflows | Extend with custom agents |
209| `MCP.md` | 12 MCP server configurations and coordination | Add your MCP servers |
210| `PRINCIPLES.md` | Core development philosophy | Adapt to your principles |
211| `RULES.md` | Operational safety and standards | Add team-specific rules |
212
213### Template Customization
214
2151. **Update CONTEXT_TEMPLATE.md â CONTEXT.md**:
216```bash
217cp CONTEXT_TEMPLATE.md CONTEXT.md
218# Edit CONTEXT.md with your personal details:
219# - Development environment (OS, tools, paths)
220# - Project locations and structures  
221# - Personal preferences and workflows
222```
223
2242. **Customize Agent Configurations**:
225```bash
226# Add custom agents to AGENTS.md
227# Modify existing agent prompts
228# Set up agent auto-activation rules
229```
230
2313. **Configure MCP Servers**:
232```bash
233# Update MCP.md with your server configurations
234# Add authentication credentials (use environment variables)
235# Set up server-specific optimization rules
236```
237
238## ð¤ Agent System
239
240### Agent-First Philosophy
241The studio operates on an **Agent-First** principle: specialized AI agents handle specific domains with **fresh, isolated context** rather than bloating your main conversation.
242
243**Context Management Benefits:**
244- **Zero Context Contamination**: Each agent starts with a clean slate
245- **Infinite Conversation Capacity**: Main conversation never gets bloated with task-specific details  
246- **Expert-Level Focus**: 500+ word specialized prompts for each domain
247- **Parallel Processing**: Multiple agents work simultaneously without context conflicts
248
249### Utility Agents (Mandatory Usage)
250- **file-creator**: ALL file/directory creation tasks
251- **git-workflow**: ALL git operations with safety protocols
252- **date-checker**: ALL date/time calculations and scheduling
253- **context-fetcher**: ALL documentation retrieval and research
254- **test-runner**: ALL test execution and analysis
255
256### Specialized Agent Categories
257
258#### ð§ Engineering Department (7 agents)
259```
260rapid-prototyper     â Build MVPs and prototypes
261backend-architect    â Design scalable APIs and systems
262frontend-developer   â Create blazing-fast UIs
263mobile-app-builder   â Native iOS/Android development
264ai-engineer          â Integrate AI/ML features
265devops-automator     â Deploy and scale systems
266test-writer-fixer    â Write tests that catch real bugs
267```
268
269#### ð¨ Design Department (5 agents)
270```
271ui-designer          â Design buildable interfaces
272ux-researcher        â Turn insights into improvements
273whimsy-injector      â Add delightful interactions
274brand-guardian       â Maintain visual consistency
275visual-storyteller   â Create compelling visuals
276```
277
278#### ð Marketing Department (7 agents)
279```
280growth-hacker        â Find viral growth loops
281tiktok-strategist    â Create shareable content
282app-store-optimizer  â Dominate search results
283content-creator      â Generate cross-platform content
284instagram-curator    â Master visual content
285reddit-community-builder â Engage authentically
286twitter-engager      â Ride trends to engagement
287```
288
289### Agent Coordination
290- **Single Domain**: Direct agent usage
291- **Multi-Domain**: `studio-coach` orchestrates multiple agents
292- **Complex Projects**: Parallel agent teams with clear handoffs
293
294## ð MCP Integration
295
296### Intelligent Tool Coordination
297The studio includes decision trees for optimal tool selection based on task complexity and context.
298
299### Core MCP Servers
300
301#### Code Analysis Stack
302- **Serena**: Semantic code analysis and project memory
303- **Sequential Thinking**: Structured problem-solving (3 complexity levels)
304- **IDE**: Development environment integration
305
306#### Documentation & Knowledge
307- **Context7**: Library documentation and API references
308- **Readwise**: Personal knowledge management and research
309
310#### Testing & Automation
311- **Playwright**: Modern browser automation
312- **Puppeteer**: Legacy browser support
313- **Integration**: Automated testing workflows
314
315#### Database & Backend
316- **Supabase**: Database operations with intelligent query optimization
317- **Performance monitoring and optimization
318
319#### Deployment & Monitoring
320- **Vercel**: Deployment automation and monitoring
321- **Sentry**: Error tracking with AI-powered analysis
322
323### Performance Optimization
324- **Parallel Execution**: Independent operations run simultaneously
325- **Context Reuse**: Smart caching of analysis results
326- **Complexity-Based Routing**: Match tool complexity to task complexity
327- **Stop Conditions**: Avoid over-engineering simple queries
328
329## ð Project Structure
330
331```
332claude-code-studio/
333âââ README.md                 # This documentation
334âââ LICENSE                   # MIT license
335âââ CLAUDE.md                 # Main configuration entry point
336âââ CONTEXT_TEMPLATE.md      # Template for personal customization
337âââ AGENTS.md                # Complete agent system documentation
338âââ MCP.md                   # 12 MCP server integration guide
339âââ PRINCIPLES.md            # Core development philosophy
340âââ RULES.md                 # Operational safety protocols
341âââ agents/                  # 40+ specialized agents
342â   âââ utilities/          # Mandatory utility agents (file-creator, git-workflow, etc.)
343â   âââ engineering/        # Backend, frontend, mobile, AI engineers
344â   âââ design/            # UI designers, UX researchers, brand guardians
345â   âââ marketing/         # Growth hackers, content creators, social strategists
346â   âââ product/           # Sprint prioritizers, feedback synthesizers
347â   âââ project-management/ # Experiment trackers, project shippers
348â   âââ studio-operations/ # Analytics, finance, infrastructure
349â   âââ testing/           # API testers, performance benchmarkers
350â   âââ bonus/             # Studio coach, special purpose agents
351âââ commands/              # Slash command definitions
352    âââ api.md            # API development commands
353    âââ deploy.md         # Deployment commands
354    âââ test.md           # Testing commands
355    âââ ui.md             # UI development commands
356    âââ ...               # Additional workflow commands
357```
358
359## ð§ Installation Troubleshooting
360
361### Reverting Installation (Existing Users)
362If you need to go back to your original setup:
363```bash
364# Remove studio and restore backup
365rm -rf ~/.claude
366mv ~/.claude-backup ~/.claude
367echo "Original configuration restored!"
368```
369
370### Merging MCP Configurations
371If you had MCP servers configured before installation:
372
3731. **Check your existing config**: `cat ~/.claude.json` (this file stays in place during installation)
3742. **Add studio servers**: Merge the MCP servers from step 2 into your existing `~/.claude.json`
3753. **Test setup**: Restart and verify all servers load correctly
376
377> ð¡ **Note**: The `.claude.json` MCP configuration file is at `~/.claude.json` (not inside the `~/.claude/` folder), so it's preserved during installation.
378
379### Partial Recovery
380Restore specific files from backup:
381```bash
382# Restore specific personal files
383cp ~/.claude-backup/hooks/* ~/.claude/hooks/ 2>/dev/null || true
384cp ~/.claude-backup/commands/* ~/.claude/commands/ 2>/dev/null || true
385# Add any other personal customizations
386```
387
388### Verification
389Confirm studio is working:
390```bash
391# Check structure
392ls -la ~/.claude/agents/
393
394# Verify agents are available - try this command:
395# "Use file-creator agent to create a new component"
396```
397
398## âï¸ Customization Guide
399
400### 1. Personal Environment Setup
401
402**Edit CONTEXT.md** with your specific details:
403```markdown
404# Development Environment
405- OS: Your operating system
406- Node.js: Version and package manager
407- Editor: VS Code, Cursor, etc.
408- Projects: Your project locations
409- Preferences: Coding style, frameworks
410```
411
412### 2. Agent Customization
413
414**Add Custom Agents** to AGENTS.md:
415```markdown
416#### your-custom-agent
417- **Specialization**: Your specific domain expertise
418- **Best for**: Specific use cases
419- **Auto-activates**: Trigger conditions
420- **Context overhead**: ~13k tokens (same as all studio agents)
421```
422
423### 3. MCP Server Configuration
424
425**Update MCP.md** with your servers:
426```yaml
427your_custom_server:
428  description: "Your server description"
429  capabilities: ["capability1", "capability2"]
430  usage_patterns: ["when to use", "best practices"]
431```
432
433### 4. Principle Alignment
434
435**Modify PRINCIPLES.md** to match your development philosophy:
436- Code quality standards
437- Testing approaches  
438- Documentation requirements
439- Team collaboration rules
440
441## ð¡ Usage Examples: Context-Efficient Development
442
443### Creating a New Feature (0 Context Used)
444```
445I need to build a user authentication system with React frontend and Node.js backend
446```
447
448**Studio Response - All with Fresh Context:**
4491. `backend-architect` spawns â designs the API structure â exits
4502. `frontend-developer` spawns â creates React components â exits  
4513. `file-creator` spawns â sets up the directory structure â exits
4524. `test-writer-fixer` spawns â generates comprehensive tests â exits
4535. `git-workflow` spawns â manages commits and branches â exits
454
455**Context Impact**: Your main conversation used **0 messages** for this complex feature. All 297+ messages still available.
456
457### Debugging Production Issues (0 Context Used)
458```
459Our app is experiencing high error rates in production
460```
461
462**Studio Response - Parallel Investigation:**
4631. `analytics-reporter` spawns â analyzes error metrics â exits
4642. `sentry` MCP â retrieves detailed error traces â exits
4653. `sequential-thinking` spawns â performs root cause analysis â exits
4664. `devops-automator` spawns â suggests deployment fixes â exits
4675. `support-responder` spawns â drafts user communications â exits
468
469**Context Impact**: Complex production debugging completed without consuming any conversation context.
470
471### All-Day Development Session Example
472```
473Morning: "Build user auth system"     â Agents handle, 0 context used
474Midday: "Add payment integration"     â Agents handle, 0 context used  
475Afternoon: "Debug performance issue" â Agents handle, 0 context used
476Evening: "Deploy to production"      â Agents handle, 0 context used
477```
478
479**Traditional Approach**: 4 separate conversations, constant re-explaining context
480**Studio Approach**: 1 continuous conversation, 300+ messages, full project memory
481
482## ð¤ Contributing
483
484We welcome contributions! Here's how to get involved:
485
486### 1. Agent Development
487- Create specialized agents for new domains
488- Enhance existing agent capabilities
489- Improve agent coordination workflows
490
491### 2. MCP Integration
492- Add support for new MCP servers
493- Optimize existing server configurations
494- Create intelligent decision trees
495
496### 3. Documentation
497- Improve setup guides and tutorials
498- Add usage examples and best practices
499- Translate documentation
500
501### 4. Templates
502- Create templates for new frameworks
503- Enhance existing component templates
504- Add industry-specific templates
505
506### Contribution Process
5071. Fork the repository
5082. Create a feature branch: `git checkout -b feature/amazing-agent`
5093. Make your changes and test thoroughly
5104. Submit a pull request with detailed description
511
512### Code Style
513- Follow existing patterns and conventions
514- Include comprehensive documentation
515- Add usage examples for new features
516- Test all configurations before submitting
517
518## ð License
519
520This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
521
522### What This Means
523- â **Use freely** in personal and commercial projects
524- â **Modify** and adapt to your needs
525- â **Distribute** and share with others
526- â **Include** in proprietary software
527- â¹ï¸ **Attribution** appreciated but not required
528
529## ð Acknowledgments
530
531### Core Contributors
532
533**[Contains Studio](https://github.com/contains-studio/agents)** ð¯  
534Provided the complete 40+ agent system that forms the heart of this studio. Their revolutionary vision of department-organized, specialized AI agents with 6-day sprint methodology enables the rapid development capabilities this project provides. The entire agent ecosystem - from engineering to marketing to testing - originates from their innovative work.
535
536**[Agent OS by Builder Methods](https://github.com/buildermethods/agent-os)** ð§  
537Contributed foundational concepts for utility agent patterns and systematic AI development workflows. Their approach to structured, spec-driven agentic development influenced the utility agent implementation and workflow optimization principles.
538
539### Special Thanks
540- **Anthropic** for creating the AI platform that enables this ecosystem
541- **Development Community** for inspiration and collaborative feedback
542- **MCP Server Developers** for building the tools that power the integrations
543- **Open Source Contributors** who make projects like this possible
544
545### Philosophy Credits
546- **6-Day Sprint Methodology**: Contains Studio's rapid development framework
547- **Agent-First Development**: Core principle from Contains Studio
548- **Structured AI Workflows**: Concepts from Agent OS systematic approach
549- **Domain Specialization**: Department-based organization by Contains Studio
550
551### Built With
552- AI-powered development environment with MCP integration
553- [Model Context Protocol](https://modelcontextprotocol.io/) - Standardized AI-tool integration
554- [Various MCP Servers](https://github.com/modelcontextprotocol/servers) - Specialized tool integrations
555
556### Inspiration
557This project was inspired by the frustrating reality of hitting context limits every 50-100 messages, and the vision of AI-augmented development where:
558- **Conversations never die from context limits**
559- **Humans focus on creativity and strategy**
560- **AI handles repetitive tasks with fresh, focused context**  
561- **Development sessions last all day, not all morning**
562
563---
564
565<div align="center">
566  
567**ð End Context Limit Frustration Forever! ð**
568
569**Finally develop features without watching your message count.**
570
571[Get Unlimited Conversations](#quick-start) â¢ [See Agent System](#agent-system) â¢ [Context Benefits](#-conversation-longevity-benefits)
572
573*Transform your 50-message conversations into 300+ message development marathons*
574
575</div>