Add claude code files

.claude/.gitignore

@@ -0,0 +1,8 @@
+# Claude Code temporary files
+*.tmp
+*.log
+.claude-cache/
+
+# OS files
+.DS_Store
+Thumbs.db

.claude/QUICKSTART.md

@@ -0,0 +1,200 @@
+# 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! 🎙️🤖

.claude/README.md

@@ -0,0 +1,177 @@
+# Claude Code Setup for Pipecat
+
+This directory contains configuration and custom skills for working with the Pipecat project using Claude Code.
+
+## Project Overview
+
+Pipecat is an open-source Python framework for building real-time voice and multimodal conversational agents. It provides a composable, frame-based architecture for orchestrating audio, video, AI services, and conversation pipelines.
+
+## Architecture
+
+### Core Concepts
+
+1. **Frames** - The fundamental data units in Pipecat (audio, text, images, system messages, etc.)
+   - Located in: `src/pipecat/frames/frames.py`
+   - Different frame types for different data: `AudioRawFrame`, `TextFrame`, `ImageRawFrame`, etc.
+
+2. **Processors** - Processing units that receive, transform, and emit frames
+   - Base class: `src/pipecat/processors/frame_processor.py`
+   - Can be chained to form pipelines
+   - Examples: STT services, LLMs, TTS services, aggregators, etc.
+
+3. **Pipelines** - Chains of processors that define data flow
+   - Created using the `Pipeline` class
+   - Processors linked using `link()` method or `|` operator
+
+4. **Transports** - Handle input/output for audio/video streams
+   - WebRTC (Daily), WebSocket, Local audio, etc.
+   - Located in: `src/pipecat/transports/`
+
+### Key Directories
+
+- `src/pipecat/` - Main source code
+  - `frames/` - Frame definitions and utilities
+  - `processors/` - Base processors and common processors
+  - `services/` - AI service integrations (STT, TTS, LLM, etc.)
+  - `transports/` - Transport implementations
+  - `audio/` - Audio processing utilities
+- `examples/` - Example applications and foundational examples
+- `tests/` - Test suite
+- `docs/` - Documentation source
+
+## Development Workflow
+
+### Setup
+
+```bash
+# Install dependencies
+uv sync --group dev --all-extras --no-extra gstreamer --no-extra krisp --no-extra local
+
+# Install pre-commit hooks
+uv run pre-commit install
+```
+
+### Running Tests
+
+```bash
+# All tests
+uv run pytest
+
+# Specific test file
+uv run pytest tests/test_name.py
+
+# With coverage
+uv run coverage run --module pytest
+uv run coverage report
+```
+
+### Code Quality
+
+```bash
+# Format code
+uv run ruff format .
+
+# Lint code
+uv run ruff check .
+
+# Fix linting issues
+uv run ruff check --fix .
+
+# Type checking
+uv run pyright
+
+# Run all pre-commit hooks
+uv run pre-commit run --all-files
+```
+
+### Building
+
+```bash
+# Build package
+uv build
+```
+
+## Custom Skills
+
+This project includes custom Claude Code skills:
+
+### `/docstring`
+Document Python modules and classes using Google-style docstrings.
+
+Usage: `/docstring ClassName`
+
+### `/changelog`
+Generate changelog entries using towncrier.
+
+### `/pr-description`
+Generate comprehensive PR descriptions based on changes.
+
+## Coding Standards
+
+1. **Docstrings** - Use Google-style docstrings for all public APIs
+   - Module docstrings required
+   - Class docstrings with purpose and event handlers
+   - Method docstrings with Args/Returns/Raises
+   - Constructor (`__init__`) must document all parameters
+
+2. **Type Hints** - Required for all function signatures
+   - Use `from typing import ...` for complex types
+   - Dataclasses should have field type annotations
+
+3. **Async/Await** - Consistent use of async patterns
+   - Most processors use async methods
+   - Tests use pytest-asyncio
+
+4. **Code Style**
+   - Line length: 100 characters max
+   - Ruff for linting and formatting
+   - Follow existing patterns in the codebase
+
+5. **Testing**
+   - Write tests for new features
+   - Use pytest fixtures for common setups
+   - Mock external services when appropriate
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make changes following coding standards
+4. Add tests for new functionality
+5. Run pre-commit hooks: `uv run pre-commit run --all-files`
+6. Submit a pull request
+
+## Common Tasks
+
+### Adding a New Service Integration
+
+1. Create service file in `src/pipecat/services/<category>/`
+2. Inherit from appropriate base class (e.g., `TTSService`, `LLMService`)
+3. Implement required abstract methods
+4. Add service to `pyproject.toml` optional dependencies
+5. Add documentation
+6. Add tests in `tests/`
+
+### Adding a New Processor
+
+1. Create processor in `src/pipecat/processors/`
+2. Inherit from `FrameProcessor` or appropriate subclass
+3. Override `process_frame()` method
+4. Handle relevant frame types
+5. Emit frames using `await self.push_frame()`
+6. Add tests
+
+### Adding a New Frame Type
+
+1. Add frame definition to `src/pipecat/frames/frames.py`
+2. Inherit from appropriate base frame class
+3. Use `@dataclass` decorator for data frames
+4. Document the frame type and its fields
+5. Update processors that should handle this frame type
+
+## Resources
+
+- [Documentation](https://docs.pipecat.ai)
+- [GitHub Repository](https://github.com/pipecat-ai/pipecat)
+- [Examples](https://github.com/pipecat-ai/pipecat-examples)
+- [Discord Community](https://discord.gg/pipecat)

.claude/settings.json

@@ -0,0 +1,81 @@
+{
+  "description": "Pipecat - Open-source Python framework for real-time voice and multimodal AI agents",
+  "conventions": {
+    "language": "Python",
+    "version": ">=3.10",
+    "package_manager": "uv",
+    "code_style": "Google docstrings, Ruff formatting",
+    "test_framework": "pytest",
+    "async": true
+  },
+  "project_info": {
+    "type": "python_library",
+    "framework": "pipecat",
+    "main_source": "src/pipecat",
+    "examples": "examples/",
+    "tests": "tests/",
+    "docs": "docs/"
+  },
+  "commands": {
+    "install": "uv sync --group dev --all-extras --no-extra gstreamer --no-extra krisp --no-extra local",
+    "test": "uv run pytest",
+    "test_file": "uv run pytest {file}",
+    "lint": "uv run ruff check .",
+    "lint_fix": "uv run ruff check --fix .",
+    "format": "uv run ruff format .",
+    "format_check": "uv run ruff format --check .",
+    "type_check": "uv run pyright",
+    "pre_commit": "uv run pre-commit run --all-files",
+    "build": "uv build",
+    "changelog": "uv run towncrier build --version {version}"
+  },
+  "coding_standards": [
+    "Use Google-style docstrings for all public classes and methods",
+    "Follow Ruff linting rules (see pyproject.toml)",
+    "Maintain type hints for all function signatures",
+    "Use async/await patterns consistently",
+    "Keep line length at 100 characters maximum",
+    "Use dataclasses with type annotations for configuration classes",
+    "Prefer composition over inheritance where appropriate",
+    "Write comprehensive pytest tests with asyncio support",
+    "Document event handlers in class docstrings with Example:: sections"
+  ],
+  "file_patterns": {
+    "source_files": "src/pipecat/**/*.py",
+    "test_files": "tests/**/*.py",
+    "example_files": "examples/**/*.py",
+    "config_files": "pyproject.toml"
+  },
+  "important_files": [
+    "pyproject.toml - Project configuration and dependencies",
+    "CONTRIBUTING.md - Contributing guidelines",
+    "README.md - Project overview and quick start",
+    "src/pipecat/__init__.py - Main package exports",
+    "src/pipecat/frames/frames.py - Core frame definitions",
+    "src/pipecat/processors/frame_processor.py - Base processor class"
+  ],
+  "documentation": {
+    "style": "Google",
+    "build_command": "cd docs && make html",
+    "skip_private_methods": true,
+    "skip_simple_dunders": true,
+    "require_module_docstrings": true,
+    "require_class_docstrings": true,
+    "require_init_docstrings": true
+  },
+  "git": {
+    "main_branch": "main",
+    "commit_style": "Conventional Commits",
+    "pre_commit_hooks": true
+  },
+  "ai_assistance_notes": [
+    "This project is a real-time voice and multimodal AI framework",
+    "Core concepts: Frames (data units), Processors (processing units), Pipelines (chains of processors)",
+    "Heavy use of async/await for real-time processing",
+    "WebRTC and WebSocket transports for audio/video streaming",
+    "Integration with many AI services (OpenAI, Anthropic, Deepgram, ElevenLabs, etc.)",
+    "Frame-based architecture allows composable, modular pipeline construction",
+    "Tests use pytest-asyncio for async test support",
+    "Pre-commit hooks enforce code quality (run 'uv run pre-commit install')"
+  ]
+}

.gitignore

@@ -61,4 +61,9 @@ docs/api/api
 .python-version
 
 # Pipecat
-whisker_setup.py
+whisker_setup.py
+
+# Claude Code - exclude temporary files but keep configuration
+.claude/.claude-cache/
+.claude/**/*.tmp
+.claude/**/*.log