Claude Code Generator#

The Claude Code Generator provides advanced code generation by leveraging Claude Code, Anthropic’s enterprise-level agentic code generator. Through the Claude Code SDK, this generator enables multi-turn agentic reasoning, codebase learning, and configurable quality profiles.

Overview#

What This Generator Provides

This Osprey generator leverages the Claude Code SDK to provide capabilities beyond traditional single-pass LLM generators:

Read your codebase to learn from successful examples
Execute multi-phase workflows (scan → plan → implement)
Iterate intelligently with multi-turn reasoning
Design custom workflows through pure configuration - no code changes needed
Balance quality and speed through configurable profiles tailored to your use cases

Two Pre-configured Approaches:

⚡ Fast Profile (Single-Phase)

~20 seconds

User Request
     ↓
Claude Code (optional lookup)
     ↓
Python Code

Single-phase generation with optional codebase learning. Claude autonomously decides whether to reference examples based on the task.

🔬 Robust Profile (Multi-Phase)

~60 seconds

User Request
     ↓
Phase 1: SCAN
→ Find examples & patterns
     ↓
Phase 2: PLAN
→ Create implementation plan
     ↓
Phase 3: IMPLEMENT
→ Write Python code
     ↓
Python Code

Structured 3-phase workflow with comprehensive analysis. Conversation history is maintained across all phases, allowing Claude to build on insights from previous steps.

Quick Start#

Minimal Configuration#

Step 1: Generate the Claude Code configuration file

osprey generate claude-config

This creates claude_generator_config.yml with sensible defaults based on your project’s LLM provider.

Step 2: Enable in your main config

# config.yml
execution:
  code_generator: "claude_code"
  generators:
    claude_code:
      profile: "fast"  # fast (DEFAULT) | robust | your custom profiles
      claude_config_path: "claude_generator_config.yml"

That’s it! This uses the fast profile with sensible defaults. For advanced configuration, see Configuration Reference below.

Codebase Reading#

This generator enables Claude to read your codebase and learn from successful examples. You configure libraries of example scripts, and Claude finds similar implementations, identifies patterns and conventions, uses the same libraries and approaches, and matches your code style. The result is generated code that fits naturally into your codebase, not generic solutions.

Example Workflow#

User: "Retrieve EPICS PV data and create time series plot"

SCAN:  Finds read_beam_data.py → Uses pyepics, handles timeouts
        Finds time_series.py → Uses matplotlib, saves with dpi=300

PLAN:  Use pyepics like examples, handle timeouts, create plot

IMPLEMENT: Generated code follows discovered patterns!

How It Works#

Define example libraries with directories and guidance in claude_generator_config.yml. The guidance field tells Claude what scenarios each directory covers (when to look there). The actual best practices are in the example code itself. All libraries are provided to Claude - it determines what’s relevant for each task.

Create a directory structure for your examples:

mkdir -p _agent_data/example_scripts/{epics,plotting,analysis}

Add well-documented example scripts:

# _agent_data/example_scripts/epics/read_pv_example.py
"""
Example: Reading EPICS PV values with error handling.
Standard pattern for EPICS operations.
"""
from epics import caget

def read_pv_with_timeout(pv_name, timeout=5.0):
    """Read PV value with timeout handling."""
    try:
        value = caget(pv_name, timeout=timeout)
        if value is None:
            raise ValueError(f"Failed to read PV: {pv_name}")
        return value
    except Exception as e:
        print(f"Error reading {pv_name}: {e}")
        return None

beam_current = read_pv_with_timeout('BEAM:CURRENT')
results = {'beam_current': beam_current}

Claude will find and learn from examples like this when generating code. Adding a README file in each directory (e.g., _agent_data/example_scripts/epics/README.md) is also helpful - Claude naturally discovers these files and can learn generic patterns and conventions from them.

# _agent_data/example_scripts/epics/README.md

This directory contains examples for EPICS channel access operations. All examples use
pyepics and follow standard timeout/error handling patterns. PV names follow the convention
`SYSTEM:SUBSYSTEM:PARAMETER`.

Security#

Codebase reading is read-only with multiple protection layers:

Layer 0: Directory isolation - Claude runs in /tmp/osprey_claude_code_restricted/ with only copied examples
Layer 1: SDK allowed_tools only includes Read/Grep/Glob
Layer 2: SDK disallowed_tools blocks Write/Edit/Delete/Bash/Python
Layer 3: PreToolUse safety hook actively blocks dangerous operations

See the Advanced Reference section below for complete safety model details.

Usage Examples#

Basic Usage

from osprey.services.python_executor.generation import ClaudeCodeGenerator
from osprey.services.python_executor.models import PythonExecutionRequest

generator = ClaudeCodeGenerator()

request = PythonExecutionRequest(
    user_query="Calculate mean and standard deviation",
    task_objective="Compute basic statistics",
    execution_folder_name="stats",
    expected_results={"mean": "float", "std": "float"}
)

code = await generator.generate_code(request, [])

With Custom Profile

# Fast profile for development
generator = ClaudeCodeGenerator({"profile": "fast"})

# Robust profile for critical tasks
generator = ClaudeCodeGenerator({"profile": "robust"})

With Context and Guidance

request = PythonExecutionRequest(
    user_query="Process EPICS PV data and create time series plot",
    task_objective="Visualize accelerator data",
    execution_folder_name="epics_viz",

    capability_context_data={
        "pv_names": ["BEAM:CURRENT", "BEAM:ENERGY"],
        "time_range": "last 1 hour"
    },

    capability_prompts=[
        "Use pyepics for channel access",
        "Handle connection timeouts gracefully",
        "Create matplotlib plot with labels",
        "Save plot to execution folder"
    ],

    expected_results={
        "plot_path": "str",
        "statistics": "dict",
        "pv_values": "list"
    }
)

code = await generator.generate_code(request, [])

With Error Feedback

# First attempt
code_v1 = await generator.generate_code(request, [])

# Retry with error feedback
error_chain = ["NameError: name 'pd' is not defined"]
code_v2 = await generator.generate_code(request, error_chain)
# Should now include 'import pandas as pd'

Advanced Reference & Customization

API Configuration

The Claude Code Generator supports multiple API providers through explicit configuration.

Direct Anthropic API (Default)

Obtain an API key from https://console.anthropic.com/

Set environment variable:

export ANTHROPIC_API_KEY='your-api-key-here'

Configure in claude_generator_config.yml:
```
api_config:
  provider: "anthropic"
```

Model Names:

claude-haiku-4-5-20251001 for Claude Haiku 4.5
claude-sonnet-4-5-20250929 for Claude Sonnet 4.5

CBORG (Lawrence Berkeley Lab)

Obtain a CBORG API key from Science IT

Set environment variable:

export CBORG_API_KEY='your-cborg-key-here'

Configure in claude_generator_config.yml:

api_config:
  provider: "cborg"
  base_url: "https://api.cborg.lbl.gov"
  disable_non_essential_model_calls: true
  disable_telemetry: true
  max_output_tokens: 8192  # Reduces throttling

Model Names:

anthropic/claude-haiku for Claude Haiku
anthropic/claude-sonnet for Claude Sonnet
anthropic/claude-opus for Claude Opus

Provider Comparison:

Aspect	Direct Anthropic	CBORG
API Key	`ANTHROPIC_API_KEY`	`CBORG_API_KEY`
Base URL	Default (api.anthropic.com)	https://api.cborg.lbl.gov
Model Names	Full model IDs (e.g., claude-haiku-4-5-20251001)	anthropic/* prefix format (e.g., anthropic/claude-haiku)
Billing	Direct Anthropic billing	LBL project recharge

Codebase Guidance

Configure example libraries that Claude can read to learn patterns:

codebase_guidance:
  epics:
    directories:
      - "_agent_data/example_scripts/epics/"
    guidance: |
      Use for EPICS channel access tasks: reading PVs, monitoring values,
      control operations. Examples show pyepics usage patterns.

  plotting:
    directories:
      - "_agent_data/example_scripts/plotting/"
    guidance: |
      Use for plotting and visualization: time series plots, multi-parameter
      comparisons, correlation matrices, publication-quality figures.

  data_analysis:
    directories:
      - "_agent_data/example_scripts/analysis/"
    guidance: |
      Use for data analysis tasks: statistical calculations, data manipulation,
      pandas and numpy operations.

How it works:

Directories → Claude can search these paths (via Read/Grep/Glob tools)
Guidance → Tells Claude WHEN to use these examples (what scenarios/tasks they cover)
Always active → ALL libraries are included, Claude picks what’s relevant

Troubleshooting

Installation

# ImportError
pip install osprey-framework[claude-agent]

# API key not found
export ANTHROPIC_API_KEY='your-key'

Configuration

Profile not found: Check profile name matches exactly in claude_generator_config.yml
Multi-phase workflow not working: Ensure profile specifies phases correctly: phases: [scan, plan, implement]

Generation Issues

Timeout: Increase timeout, use fast profile, limit codebase directories
High API usage: Use fast profile, reduce max_turns, set stricter budgets
Code doesn’t follow examples: Verify directories exist, check that codebase_guidance is configured

Quality Issues

Low quality: Use robust profile (multi-phase), add better examples, provide more context
Missing imports: Add examples with imports, include guidance in capability_prompts

Performance Issues

Too slow: Use fast profile (single-phase), reduce max_turns, limit example directories
Too many API calls: Reduce max_turns, use fast profile, set stricter budgets