claude-code-recipes

Tested, production-ready patterns for building with Claude Code SDK.

Claude Code SDK is the right foundation for AI agents — but the common patterns (rate limit handling, conversation memory, MCP integration, parallelism) require boilerplate that isn't obvious from the docs. These recipes distill what works.

Architecture

graph LR
    subgraph recipes["claude-code-recipes"]
        RL[rate-limit-fallback]
        CM[conversation-memory]
        MCP[mcp-servers]
        PT[parallel-tasks]
        SM[session-management]
        SA[scheduled-agents]
        ES[encrypted-stores]
    end

    subgraph sdk["Claude Code SDK"]
        Q[query]
        OPT[ClaudeCodeOptions]
    end

    subgraph storage["Local Storage"]
        DB[(SQLite)]
        FS[filesystem]
    end

    RL --> Q
    CM --> Q
    MCP --> Q
    PT --> Q
    SM --> Q
    SA --> Q
    ES --> DB

    Q --> OPT --> API[Anthropic API]
    CM --> DB
    SM --> FS

Loading

Recipes

Core Patterns

Recipe	Pattern	Use When
rate-limit-fallback	Retry with backoff, model fallback chain	Production agents that can't afford downtime
conversation-memory	SQLite-backed message history injection	Stateful assistants, support bots, chat apps
mcp-servers	HTTP and stdio MCP server configuration	Agents that need external tools (GitHub, browser)
parallel-tasks	Concurrent tasks with rate limit guard	Batch processing, repo analysis pipelines

Advanced Patterns

Recipe	Pattern	Use When
session-management	Save/resume agent sessions across restarts	Long-running tasks, multi-step workflows
scheduled-agents	Cron-scheduled agent tasks via asyncio	Morning briefings, hourly health checks, periodic reports
signal-integration	Signal bot with Claude backend	Private, encrypted AI assistant on your phone
encrypted-stores	Fernet field-level encryption for SQLite	Agent data with sensitive content, API keys, personal info

Case Study: Batch Repository Health Checks (48 Repos)

Problem. A security audit required scanning 48 internal repositories for hardcoded secrets, deprecated dependency patterns, and missing LICENSE files. Running Claude serially took 22 minutes, and a single rate-limit error mid-run meant starting the whole batch over.

Constraints. Tier 3 API limits, claude-sonnet-4-5 preferred for quality, cost cap of ~$2 per run, no persistence between script invocations.

Architecture. Three recipes composed together:

1. parallel-tasks — 6 concurrent workers processing repos from a queue
2. rate-limit-fallback — sonnet → haiku fallback chain with exponential backoff; haiku used only for summary tasks, not for pattern-matching steps
3. session-management — SQLite checkpoint after every 10 repos; re-running the script skips already-processed entries and resumes from the last checkpoint

Trade-offs. Six workers hit the sweet spot — eight caused consistent rate limiting without meaningful speed improvement. Haiku fallback was acceptable for "does this file contain X?" classification but filtered out for "explain the security implication of this pattern" steps where quality mattered.

Results.

Metric	Before	After
Wall time (48 repos)	22 min	6 min
Full restarts on rate-limit	3 of 5 runs	0 of 10 runs
Haiku fallbacks	—	11 of 48 repos (23%)
Cost per run	—	$1.74 avg

All data is synthetic.

Prerequisites

pip install claude-code-sdk anthropic cryptography

You need a valid Claude API key in your environment:

export ANTHROPIC_API_KEY=your-key-here

Most recipes work with claude-sonnet-4-5. Adjust DEFAULT_MODEL at the top of each recipe.py to match your API tier. Scheduled and Signal recipes use claude-haiku-4-5 by default for cost efficiency.

Quick Start

Each recipe is a standalone Python file. Clone the repo and run:

git clone https://github.com/RedBeret/claude-code-recipes.git
cd claude-code-recipes
pip install -e ".[dev]"

# Run any recipe
python recipes/rate-limit-fallback/recipe.py
python recipes/conversation-memory/recipe.py
python recipes/session-management/recipe.py
python recipes/encrypted-stores/recipe.py  # no API key needed

Windows (run.bat):

run.bat rate-limit-fallback
run.bat encrypted-stores

Air-Gapped / Offline Install

Download wheels on a machine with internet access, then transfer and install:

# On internet-connected machine — download all wheels
pip download claude-code-sdk anthropic cryptography pytest pytest-asyncio \
    -d ./wheels --python-version 3.12

# Transfer ./wheels/ to the air-gapped host, then install
pip install --no-index --find-links ./wheels claude-code-sdk anthropic cryptography
pip install --no-index --find-links ./wheels -e ".[dev]"

The encrypted-stores recipe works fully offline (no API calls). All other recipes require an outbound HTTPS connection to api.anthropic.com.

Structure

claude-code-recipes/
├── run.bat                      # Windows one-command runner
├── recipes/
│   ├── rate-limit-fallback/     # Core: retry + model fallback
│   │   ├── recipe.py
│   │   └── README.md
│   ├── conversation-memory/     # Core: SQLite conversation history
│   │   ├── recipe.py
│   │   └── README.md
│   ├── mcp-servers/             # Core: MCP server configuration
│   │   ├── recipe.py
│   │   └── README.md
│   ├── parallel-tasks/          # Core: concurrent execution
│   │   ├── recipe.py
│   │   └── README.md
│   ├── session-management/      # Advanced: save/resume sessions
│   │   ├── recipe.py
│   │   └── README.md
│   ├── scheduled-agents/        # Advanced: cron scheduling
│   │   ├── recipe.py
│   │   └── README.md
│   ├── signal-integration/      # Advanced: Signal bot
│   │   ├── recipe.py
│   │   └── README.md
│   └── encrypted-stores/        # Advanced: field-level encryption
│       ├── recipe.py
│       └── README.md
└── tests/
    └── test_imports.py          # verifies all recipes import cleanly

Philosophy

• Standalone. Each recipe runs with python recipe.py. No shared library code between recipes.
• Real. These patterns come from a production agent system. Not toy examples.
• Minimal deps. claude-code-sdk, anthropic, cryptography (encrypted-stores only). stdlib for everything else.
• Copy-paste ready. Grab a recipe, drop it in your project, adapt as needed.

Running Tests

pip install -e ".[dev]"
pytest tests/ -v

All tests run without making API calls. They verify imports, data structures, and logic that doesn't require a live Claude connection.

Contributing

See CONTRIBUTING.md.

License

MIT