201 lines
5.4 KiB
Markdown
201 lines
5.4 KiB
Markdown
# Claude Code Quick Start for Pipecat
|
|
|
|
This guide helps you get started using Claude Code with the Pipecat project.
|
|
|
|
## Initial Setup
|
|
|
|
1. **Install Claude Code** (if not already installed):
|
|
```bash
|
|
# Follow instructions at https://claude.ai/claude-code
|
|
```
|
|
|
|
2. **Install project dependencies**:
|
|
```bash
|
|
uv sync --group dev --all-extras --no-extra gstreamer --no-extra krisp --no-extra local
|
|
```
|
|
|
|
3. **Install pre-commit hooks**:
|
|
```bash
|
|
uv run pre-commit install
|
|
```
|
|
|
|
## Common Commands
|
|
|
|
### Testing
|
|
- "Run all tests"
|
|
- "Run tests for [specific file]"
|
|
- "Run tests and show coverage"
|
|
|
|
### Code Quality
|
|
- "Format the code"
|
|
- "Fix linting issues"
|
|
- "Run type checking"
|
|
- "Run pre-commit hooks"
|
|
|
|
### Development
|
|
- "Add a new TTS service for [provider]"
|
|
- "Create a new processor that [does something]"
|
|
- "Add a new frame type for [purpose]"
|
|
- "Document the [ClassName] class" (uses `/docstring` skill)
|
|
|
|
### Documentation
|
|
- "Document this module using Google style"
|
|
- "Add docstrings to [file/class]"
|
|
- Use `/docstring ClassName` for comprehensive class documentation
|
|
|
|
### Git Operations
|
|
- "Create a commit for these changes"
|
|
- "Create a pull request"
|
|
- Use `/pr-description` skill for detailed PR descriptions
|
|
- Use `/changelog` skill for changelog entries
|
|
|
|
## Custom Skills
|
|
|
|
### `/docstring [ClassName]`
|
|
Automatically documents a Python class and its methods following Google-style conventions.
|
|
|
|
**Example:**
|
|
```
|
|
/docstring AudioProcessor
|
|
```
|
|
|
|
This will:
|
|
- Find the class in the codebase
|
|
- Add module docstring if missing
|
|
- Add class docstring with purpose and event handlers
|
|
- Document all public methods
|
|
- Document constructor parameters
|
|
- Skip private methods and already-documented code
|
|
|
|
### `/changelog`
|
|
Generates changelog entries using towncrier.
|
|
|
|
### `/pr-description`
|
|
Creates comprehensive pull request descriptions based on your changes.
|
|
|
|
## Project-Specific Tips
|
|
|
|
### Understanding Pipecat Architecture
|
|
|
|
When asking Claude Code to help with development:
|
|
|
|
1. **Frame-Based System**: All data flows through frames
|
|
- Ask: "Explain how frames work in this pipeline"
|
|
- Reference: `src/pipecat/frames/frames.py`
|
|
|
|
2. **Processor Pattern**: Everything is a processor
|
|
- Ask: "Show me how to create a custom processor"
|
|
- Reference: `src/pipecat/processors/frame_processor.py`
|
|
|
|
3. **Service Integrations**: Many AI service integrations
|
|
- Ask: "How do I add a new TTS service?"
|
|
- Reference: `src/pipecat/services/tts/`
|
|
|
|
### Working with Examples
|
|
|
|
- "Show me examples of [feature]"
|
|
- "Create a simple example that [does something]"
|
|
- Examples are in `examples/foundational/` (building blocks) and `examples/` (complete apps)
|
|
|
|
### Debugging
|
|
|
|
- "Help me debug this pipeline"
|
|
- "Why isn't my processor receiving frames?"
|
|
- "Trace the flow of this frame type through the pipeline"
|
|
|
|
## Best Practices
|
|
|
|
1. **Be Specific**: Instead of "fix this", say "fix the audio dropouts in the TTS processor"
|
|
|
|
2. **Context**: Provide context about what you're building
|
|
- "I'm building a voice assistant that needs to interrupt TTS"
|
|
- "I want to add vision capabilities to this chatbot"
|
|
|
|
3. **Reference Examples**: Point to existing patterns
|
|
- "Similar to how DeepgramTTS works"
|
|
- "Following the pattern in OpenAILLMService"
|
|
|
|
4. **Test-Driven**: Ask for tests
|
|
- "Create tests for this processor"
|
|
- "Add test coverage for the error handling"
|
|
|
|
5. **Documentation**: Keep docs updated
|
|
- "Update the docstrings for these changes"
|
|
- "Add a usage example to the class docstring"
|
|
|
|
## Example Conversations
|
|
|
|
### Adding a New Feature
|
|
```
|
|
You: "I need to add a processor that detects when the user says 'hello' and triggers an event"
|
|
|
|
Claude Code will:
|
|
1. Create the processor class
|
|
2. Implement frame processing logic
|
|
3. Add event emission
|
|
4. Create tests
|
|
5. Add documentation
|
|
```
|
|
|
|
### Debugging an Issue
|
|
```
|
|
You: "The audio is cutting out in my pipeline. Here's the code: [paste code]"
|
|
|
|
Claude Code will:
|
|
1. Analyze the pipeline structure
|
|
2. Check for common issues (buffer sizes, async handling, etc.)
|
|
3. Suggest fixes
|
|
4. Explain the root cause
|
|
```
|
|
|
|
### Refactoring
|
|
```
|
|
You: "Refactor the XYZ service to use the new WebSocket pattern from ABC service"
|
|
|
|
Claude Code will:
|
|
1. Analyze both services
|
|
2. Identify the pattern differences
|
|
3. Apply the refactoring
|
|
4. Update tests
|
|
5. Maintain backward compatibility if needed
|
|
```
|
|
|
|
## Useful Prompts
|
|
|
|
- "Explain how [feature] works in this codebase"
|
|
- "Add error handling for [scenario]"
|
|
- "Create an example that demonstrates [feature]"
|
|
- "Optimize this processor for [use case]"
|
|
- "Add logging to help debug [issue]"
|
|
- "Make this code more maintainable"
|
|
- "Add type hints to this file"
|
|
- "Create a comprehensive test suite for [component]"
|
|
|
|
## Configuration Reference
|
|
|
|
All Claude Code settings are in [.claude/settings.json](.claude/settings.json):
|
|
- Project commands (test, lint, format, etc.)
|
|
- Coding standards
|
|
- File patterns
|
|
- Important files and directories
|
|
|
|
For detailed architecture info, see [.claude/README.md](.claude/README.md).
|
|
|
|
## Getting Help
|
|
|
|
- **Project docs**: https://docs.pipecat.ai
|
|
- **Discord**: https://discord.gg/pipecat
|
|
- **GitHub Issues**: https://github.com/pipecat-ai/pipecat/issues
|
|
- **Examples**: https://github.com/pipecat-ai/pipecat-examples
|
|
|
|
## Tips for Success
|
|
|
|
1. Start with small, specific tasks
|
|
2. Use the custom skills (`/docstring`, `/pr-description`, etc.)
|
|
3. Reference existing code patterns
|
|
4. Ask for explanations when confused
|
|
5. Request tests and documentation
|
|
6. Run pre-commit hooks before committing
|
|
|
|
Happy coding with Claude! 🎙️🤖
|