Claude Code Plugin for Hamilton

The Hamilton Claude Code plugin provides AI-powered assistance for developing Hamilton DAGs using Claude Code, Anthropic's official CLI tool.

What is Claude Code?

Claude Code is an AI-powered CLI tool that helps you build software faster by providing intelligent code assistance, debugging help, and code generation capabilities. The Hamilton plugin extends Claude Code with deep knowledge of Hamilton patterns and best practices.

Features

The Hamilton Claude Code plugin provides expert assistance for:

  • 🏗️ Creating new Hamilton modules with proper patterns and decorators
  • 🔍 Understanding existing DAGs by explaining dataflow and dependencies
  • 🎨 Applying function modifiers correctly (@parameterize, @config.when, @check_output, etc.)
  • 🐛 Debugging issues in DAG definitions and execution
  • 🔄 Converting Python scripts to Hamilton modules
  • ⚡ Optimizing pipelines with caching, parallelization, and best practices
  • ✅ Writing tests for Hamilton functions
  • 📊 Generating visualizations of your DAGs

Installation

Prerequisites

First, install Claude Code:

# Install Claude Code CLI
curl -fsSL https://cli.claude.ai/install.sh | sh

For more installation options, see the Claude Code documentation.

Install the Hamilton Plugin

Once Claude Code is installed, you can add the Hamilton plugin:

# Add the Hamilton plugin marketplace
/plugin marketplace add apache/hamilton

# Install the plugin (available across all projects)
/plugin install hamilton --scope user

Or combine into a single command:

claude plugin install hamilton@apache/hamilton --scope user

Installation scopes:

  • --scope user - Available in all your projects (recommended)
  • --scope project - Only in the current project
  • --scope local - Testing/development only

For Contributors

If you've cloned the Hamilton repository, the skill is already available in .claude/plugins/hamilton/skills/hamilton/ and will be automatically discovered by Claude Code when you work in the repo. No installation needed!

Usage

Automatic Assistance

Claude Code will automatically use the Hamilton plugin when it detects you're working with Hamilton code. Just ask questions or give instructions naturally:

claude "Help me create a Hamilton module for processing customer data"
claude "Explain what this DAG does"
claude "Convert this pandas script to Hamilton"
claude "Add caching to my expensive computation function"
claude "Why am I getting a circular dependency error?"

Manual Invocation

You can explicitly invoke the skill using the /hamilton command:

claude /hamilton create a feature engineering module with rolling averages
claude /hamilton explain the dataflow in my_functions.py
claude /hamilton optimize this DAG for parallel execution

Interactive Mode

For ongoing assistance, start an interactive session:

# Start Claude Code in your Hamilton project
cd /path/to/your/hamilton/project
claude

Then interact naturally:

You: I need to create a DAG that processes customer transactions
Claude: I'll help you create a Hamilton module for processing customer transactions...

You: Add validation to ensure all amounts are positive
Claude: I'll add a @check_output decorator with validation...

Examples

Creating a New Hamilton Module

Prompt:

Create a Hamilton module that loads sales data from a CSV, removes nulls,
calculates a 7-day rolling average, and outputs the top 10 days by sales.

Claude generates:

"""Sales analysis DAG."""
import pandas as pd

def raw_sales(csv_path: str) -> pd.DataFrame:
    """Load sales data from CSV.

    :param csv_path: Path to sales CSV file
    :return: Raw sales DataFrame
    """
    return pd.read_csv(csv_path)

def cleaned_sales(raw_sales: pd.DataFrame) -> pd.DataFrame:
    """Remove null values from sales data.

    :param raw_sales: Raw sales data
    :return: Cleaned sales DataFrame
    """
    return raw_sales.dropna()

def rolling_avg_7d(cleaned_sales: pd.DataFrame) -> pd.Series:
    """Calculate 7-day rolling average of sales.

    :param cleaned_sales: Cleaned sales data
    :return: 7-day rolling average
    """
    return cleaned_sales['sales'].rolling(window=7, min_periods=1).mean()

def top_10_sales_days(
    cleaned_sales: pd.DataFrame,
    rolling_avg_7d: pd.Series
) -> pd.DataFrame:
    """Get top 10 days by rolling average.

    :param cleaned_sales: Cleaned sales data
    :param rolling_avg_7d: 7-day rolling average
    :return: Top 10 sales days
    """
    result = cleaned_sales.copy()
    result['rolling_avg'] = rolling_avg_7d
    return result.nlargest(10, 'rolling_avg')

# Usage:
# from hamilton import driver
# dr = driver.Driver({}, __name__)
# results = dr.execute(['top_10_sales_days'], inputs={'csv_path': 'sales.csv'})

Converting Existing Code

Prompt:

Convert this script to Hamilton:

import pandas as pd
df = pd.read_csv('data.csv')
df['feature'] = df['col_a'] * 2 + df['col_b']
result = df.groupby('category')['feature'].mean()

Claude refactors to:

"""Data processing DAG."""
import pandas as pd

def raw_data(data_path: str) -> pd.DataFrame:
    """Load raw data from CSV."""
    return pd.read_csv(data_path)

def feature(raw_data: pd.DataFrame) -> pd.Series:
    """Calculate feature from columns."""
    return raw_data['col_a'] * 2 + raw_data['col_b']

def data_with_feature(raw_data: pd.DataFrame, feature: pd.Series) -> pd.DataFrame:
    """Add feature column to dataset."""
    result = raw_data.copy()
    result['feature'] = feature
    return result

def result(data_with_feature: pd.DataFrame) -> pd.Series:
    """Calculate mean feature by category."""
    return data_with_feature.groupby('category')['feature'].mean()

Applying Decorators

Prompt:

I need to create rolling averages for 7, 30, and 90 day windows.
How do I do this without repeating code?

Claude suggests:

from hamilton.function_modifiers import parameterize

@parameterize(
    rolling_7d={'window': 7},
    rolling_30d={'window': 30},
    rolling_90d={'window': 90},
)
def rolling_average(sales: pd.Series, window: int) -> pd.Series:
    """Calculate rolling average for different windows.

    Creates three nodes: rolling_7d, rolling_30d, rolling_90d
    """
    return sales.rolling(window=window, min_periods=1).mean()

Debugging

Prompt:

I'm getting: "Could not find parameter 'processed_data' in graph"

Claude analyzes:

This error occurs when a function parameter references a node that doesn't exist
in your DAG. Common causes:

1. Typo in parameter name (e.g., 'processed_data' vs 'process_data')
2. Missing function definition for 'processed_data'
3. Function excluded via @hamilton_exclude or @config.when

Check your module for a function named 'processed_data'. If it doesn't exist,
either:
- Add the function, or
- Fix the parameter name to match an existing function

What the Plugin Knows

The plugin has deep knowledge of Hamilton:

Core Concepts

  • Function-based DAG definitions
  • Driver configuration and execution
  • Node dependencies via parameters
  • Type hints and annotations

Function Modifiers

  • Configuration: @config.when, @hamilton_exclude
  • Parameterization: @parameterize, @parameterize_sources, @parameterize_values
  • Column extraction: @extract_columns, @extract_fields
  • Data quality: @check_output, @check_output_custom, @schema
  • I/O: @save_to, @load_from, @dataloader, @datasaver
  • Transformation: @pipe, @does, @mutate, @step
  • Advanced: @subdag, @resolve, @cache

Integration Patterns

  • Airflow orchestration
  • FastAPI microservices
  • Streamlit dashboards
  • Jupyter notebooks
  • Ray/Dask/Spark distributed execution

LLM Workflows

  • RAG pipeline patterns
  • Document chunking
  • Vector database operations
  • Embedding generation

Best Practices

  • Testing strategies
  • Code organization
  • Error handling
  • Performance optimization

Plugin Structure

The plugin is organized as follows:

.claude/plugins/hamilton/
├── .claude-plugin/
│   ├── plugin.json           # Plugin manifest
│   └── marketplace.json      # Marketplace configuration
├── skills/
│   └── hamilton/
│       ├── SKILL.md          # Main skill instructions
│       ├── examples.md       # Code examples and patterns
│       └── README.md         # Skill documentation
└── README.md                 # Plugin documentation

For contributors, the skill exists in .claude/plugins/hamilton/skills/hamilton/ for immediate use.

Contributing

Found a bug or want to improve the plugin? We'd love your help!

Report Issues

Please file an issue with:

  • Clear description of the problem
  • Steps to reproduce
  • Expected vs actual behavior
  • Hamilton and Claude Code versions

Submit Pull Requests

  1. Fork the repository: https://github.com/apache/hamilton
  2. Make changes in .claude/plugins/hamilton/skills/hamilton/
  3. Test thoroughly with various scenarios
  4. Submit a PR with a clear description

Contribution ideas:

  • 📚 Add new examples to examples.md
  • 📝 Improve instructions in SKILL.md
  • 🐛 Fix bugs or inaccuracies
  • ✨ Add support for new Hamilton features
  • 📖 Enhance documentation

See CONTRIBUTING.md for guidelines.

Requirements

  • Claude Code CLI - v0.1.0 or later
  • Hamilton - v1.0.0 or later (plugin works with any version)
  • Python - 3.9 or later

Troubleshooting

Plugin Not Loading

If the plugin isn't recognized:

# Check installed plugins
claude plugin list

# Reinstall if needed
claude plugin uninstall hamilton
claude plugin install hamilton@apache/hamilton --scope user

Skill Not Activating

If Claude doesn't seem to use Hamilton knowledge:

# Manually invoke the skill
claude /hamilton <your-question>

# Or mention Hamilton explicitly in your prompt
claude "Using Hamilton framework, create a DAG for..."

Permission Errors

The plugin requests permission to:

  • Read files (Read, Grep, Glob)
  • Run Python code (python, pytest)
  • Search files (find)

If prompted, approve these permissions for the best experience.

Learn More

License

This plugin is part of the Apache Hamilton project and is licensed under the Apache 2.0 License.

Enhance your Hamilton development with AI! 🚀