pipecat/.claude/QUICKSTART.md

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):

   # Follow instructions at https://claude.ai/claude-code
   

2. Install project dependencies:

   uv sync --group dev --all-extras --no-extra gstreamer --no-extra krisp --no-extra local
   

3. Install pre-commit hooks:

   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:

• Project commands (test, lint, format, etc.)
• Coding standards
• File patterns
• Important files and directories

For detailed architecture info, see .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! 🎙️🤖