# Claude Code Supervisor
[](https://badge.fury.io/py/claude-code-supervisor)
[](https://pypi.org/project/claude-code-supervisor/)
[](https://opensource.org/licenses/MIT)
An intelligent wrapper around Claude Code SDK that provides automated problem-solving capabilities with session management, progress monitoring, and intelligent feedback loops.
## 🚀 Features
- **Automated Problem Solving**: Describes problems to Claude Code and gets complete solutions
- **Session Management**: Maintains context across multiple iterations
- **Progress Monitoring**: Tracks Claude's progress via todo list updates and output analysis
- **Intelligent Feedback**: Provides guidance when Claude encounters issues
- **Data I/O Support**: Handles various data formats (lists, dicts, CSV, DataFrames, etc.)
- **Custom Prompts**: Guide implementation toward specific patterns or requirements
- **Test Automation**: Automatically generates and runs tests for solutions
- **Multiple Providers**: Support for Anthropic, AWS Bedrock, and Google Vertex AI
## 📦 Installation
### From PyPI (recommended)
```bash
pip install claude-code-supervisor
```
### From Source
```bash
git clone https://github.com/vinyluis/claude-code-supervisor.git
cd claude-code-supervisor
pip install -e .
```
## 🛠️ Prerequisites
1. **Claude Code CLI**:
```bash
npm install -g @anthropic-ai/claude-code
```
2. **API Key** (choose one):
```bash
# Anthropic (default)
export ANTHROPIC_API_KEY=<YOUR_ANTHROPIC_API_KEY>
# AWS Bedrock
export AWS_ACCESS_KEY_ID=<YOUR_AWS_ACCESS_KEY_ID>
export AWS_SECRET_ACCESS_KEY=<YOUR_AWS_SECRET_ACCESS_KEY>
export AWS_REGION=<AWS_REGION>
```
3. **LLM API Key** (for guidance, choose one):
```bash
# OpenAI (default)
export OPENAI_API_KEY="your-openai-api-key"
# Configure supervisor_config.json with "provider": "openai"
# AWS Bedrock (for guidance LLM)
# Will use the access keys above
# Configure supervisor_config.json with "provider": "bedrock"
```
## 🚀 Quick Start
### Basic Usage
```python
from claude_code_supervisor import SupervisorAgent
# Initialize the agent
agent = SupervisorAgent()
# Solve a problem
result = agent.process(
"Create a function to calculate fibonacci numbers",
example_output="fib(8) should return 21"
)
if result.is_solved:
print(f"Solution: {result.solution_path}")
print(f"Tests: {result.test_path}")
```
### With Input/Output Data
```python
# Process data with input/output examples
result = agent.process(
"Sort this list in ascending order",
input_data=[64, 34, 25, 12, 22, 11, 90, 5],
expected_output=[5, 11, 12, 22, 25, 34, 64, 90],
data_format="list"
)
```
### With Custom Prompts
```python
# Guide implementation style
agent = SupervisorAgent(
custom_prompt="Use object-oriented programming with SOLID principles"
)
result = agent.process("Create a calculator with basic operations")
```
### Bring Your Own Model (BYOM)
```python
# Use your own LangChain LLM for guidance
from langchain_openai import ChatOpenAI
custom_llm = ChatOpenAI(model='gpt-4o-mini', temperature=0.2)
agent = SupervisorAgent(llm=custom_llm)
result = agent.process("Create a data processing function")
```
### With Custom Configuration
```python
# Pass configuration as type-safe dataclass
from claude_code_supervisor import SupervisorAgent
from claude_code_supervisor.config import openai_config
config = openai_config(model='gpt-4o-mini', temperature=0.1)
config.agent.max_iterations = 3
config.agent.solution_filename = 'my_solution.py'
config.claude_code.max_turns = 25
agent = SupervisorAgent(config=config)
result = agent.process("Create a web scraper function")
```
### Advanced Configuration Examples
```python
# Use structured, type-safe configuration with dataclasses
from claude_code_supervisor import SupervisorAgent
from claude_code_supervisor.config import (
SupervisorConfig, ModelConfig, AgentConfig,
development_config, openai_config, bedrock_config
)
# Method 1: Use convenience functions
config = development_config() # Pre-configured for development
agent = SupervisorAgent(config=config)
# Method 2: Use builder functions with customization
config = openai_config(model='gpt-4o-mini', temperature=0.2)
config.agent.max_iterations = 5
config.agent.solution_filename = 'custom_solution.py'
agent = SupervisorAgent(config=config)
# Method 3: Build from scratch with type safety
config = SupervisorConfig(
model=ModelConfig(name='gpt-4o', temperature=0.1, provider='openai'),
agent=AgentConfig(max_iterations=3, test_timeout=60)
)
agent = SupervisorAgent(config=config)
result = agent.process("Create a validation function")
```
### Combining Configuration with Custom LLM
```python
# Use dataclass config + custom LLM together
from langchain_aws import ChatBedrockConverse
from claude_code_supervisor import SupervisorAgent
from claude_code_supervisor.config import SupervisorConfig, AgentConfig
# Custom LLM for guidance
guidance_llm = ChatBedrockConverse(
model='anthropic.claude-3-haiku-20240307-v1:0',
temperature=0.1,
)
# Type-safe configuration (no model config needed since we provide LLM)
config = SupervisorConfig(
agent=AgentConfig(max_iterations=2, solution_filename='solution.py')
)
agent = SupervisorAgent(config=config, llm=guidance_llm)
result = agent.process("Create a file parser")
```
### Command Line Interface
```bash
# Basic usage
claude-supervisor "Create a hello world function"
# With custom prompt
claude-supervisor "Create a web scraper" --prompt="Use requests and BeautifulSoup"
```
## 📊 Data Format Support
The supervisor supports various data formats:
- **Lists**: `[1, 2, 3, 4]`
- **Dictionaries**: `{"name": "Alice", "age": 30}`
- **Pandas DataFrames**: For data analysis tasks
- **NumPy Arrays**: For numerical computations
- **Strings**: Text processing tasks
- **CSV Data**: Business logic and data processing
## 🎯 Examples
Check out the [examples directory](examples/) for detailed usage examples:
- **Basic Usage**: Simple problem solving without I/O
- **Data Processing**: Working with lists, dictionaries, and complex data
- **Custom Prompts**: Guiding implementation toward specific patterns
- **Advanced Scenarios**: Real-world data processing examples
## 🔧 Configuration
SupervisorAgent uses type-safe dataclass configuration for better IDE support and validation:
### Quick Setup with Convenience Functions
```python
from claude_code_supervisor import SupervisorAgent
from claude_code_supervisor.config import openai_config, bedrock_config
# OpenAI configuration
config = openai_config(model='gpt-4o-mini', temperature=0.2)
agent = SupervisorAgent(config=config)
# AWS Bedrock configuration
config = bedrock_config(
model='anthropic.claude-3-haiku-20240307-v1:0',
)
agent = SupervisorAgent(config=config)
```
### Custom Configuration from Scratch
```python
from claude_code_supervisor import SupervisorAgent
from claude_code_supervisor.config import SupervisorConfig, ModelConfig, AgentConfig
# Build custom configuration
config = SupervisorConfig(
model=ModelConfig(
name='gpt-4o',
temperature=0.1,
provider='openai'
),
agent=AgentConfig(
max_iterations=5,
solution_filename='solution.py',
test_filename='test_solution.py'
)
)
agent = SupervisorAgent(config=config)
```
### Environment-Specific Configurations
```python
from claude_code_supervisor import SupervisorAgent
from claude_code_supervisor.config import development_config, production_config
# Development environment
dev_config = development_config()
dev_agent = SupervisorAgent(config=dev_config)
# Production environment
prod_config = production_config()
prod_agent = SupervisorAgent(config=prod_config)
```
## 🧪 Testing
Run the test suite:
```bash
# Run all tests
pytest
# Run with coverage
pytest --cov=claude_code_supervisor
# Run specific test categories
pytest -m "unit"
pytest -m "integration"
```
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## 📝 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- [Claude Code SDK](https://github.com/anthropics/claude-code-sdk) for the core Claude Code integration
- [LangGraph](https://github.com/langchain-ai/langgraph) for workflow orchestration
- [LangChain](https://github.com/langchain-ai/langchain) for LLM integrations
## 📚 Documentation
For detailed documentation, visit our [docs](docs/) directory or check out the [API Reference](docs/api.md).
## 🐛 Issues
Found a bug? Have a feature request? Please [open an issue](https://github.com/vinyluis/claude-code-supervisor/issues).
---
**Made with ❤️ by [Vinícius Trevisan](mailto:vinicius@viniciustrevisan.com)**
Raw data
{
"_id": null,
"home_page": null,
"name": "claude-code-supervisor",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Vin\u00edcius Trevisan <vinicius@viniciustrevisan.com>",
"keywords": "claude, code-generation, ai, automation, testing, development",
"author": null,
"author_email": "Vin\u00edcius Trevisan <vinicius@viniciustrevisan.com>",
"download_url": "https://files.pythonhosted.org/packages/60/c7/baf91388fdbc0b85564a7cadf248c4008e2307c667dc062573a9ab6170ee/claude_code_supervisor-0.1.3.tar.gz",
"platform": null,
"description": "# Claude Code Supervisor\n\n[](https://badge.fury.io/py/claude-code-supervisor)\n[](https://pypi.org/project/claude-code-supervisor/)\n[](https://opensource.org/licenses/MIT)\n\nAn intelligent wrapper around Claude Code SDK that provides automated problem-solving capabilities with session management, progress monitoring, and intelligent feedback loops.\n\n## \ud83d\ude80 Features\n\n- **Automated Problem Solving**: Describes problems to Claude Code and gets complete solutions\n- **Session Management**: Maintains context across multiple iterations\n- **Progress Monitoring**: Tracks Claude's progress via todo list updates and output analysis\n- **Intelligent Feedback**: Provides guidance when Claude encounters issues\n- **Data I/O Support**: Handles various data formats (lists, dicts, CSV, DataFrames, etc.)\n- **Custom Prompts**: Guide implementation toward specific patterns or requirements\n- **Test Automation**: Automatically generates and runs tests for solutions\n- **Multiple Providers**: Support for Anthropic, AWS Bedrock, and Google Vertex AI\n\n## \ud83d\udce6 Installation\n\n### From PyPI (recommended)\n\n```bash\npip install claude-code-supervisor\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/vinyluis/claude-code-supervisor.git\ncd claude-code-supervisor\npip install -e .\n```\n\n## \ud83d\udee0\ufe0f Prerequisites\n\n1. **Claude Code CLI**:\n ```bash\n npm install -g @anthropic-ai/claude-code\n ```\n\n2. **API Key** (choose one):\n ```bash\n # Anthropic (default)\n export ANTHROPIC_API_KEY=<YOUR_ANTHROPIC_API_KEY>\n \n # AWS Bedrock\n export AWS_ACCESS_KEY_ID=<YOUR_AWS_ACCESS_KEY_ID>\n export AWS_SECRET_ACCESS_KEY=<YOUR_AWS_SECRET_ACCESS_KEY>\n export AWS_REGION=<AWS_REGION>\n\n ```\n\n3. **LLM API Key** (for guidance, choose one):\n ```bash\n # OpenAI (default)\n export OPENAI_API_KEY=\"your-openai-api-key\"\n # Configure supervisor_config.json with \"provider\": \"openai\"\n \n # AWS Bedrock (for guidance LLM)\n # Will use the access keys above\n # Configure supervisor_config.json with \"provider\": \"bedrock\"\n ```\n\n## \ud83d\ude80 Quick Start\n\n### Basic Usage\n\n```python\nfrom claude_code_supervisor import SupervisorAgent\n\n# Initialize the agent\nagent = SupervisorAgent()\n\n# Solve a problem\nresult = agent.process(\n \"Create a function to calculate fibonacci numbers\",\n example_output=\"fib(8) should return 21\"\n)\n\nif result.is_solved:\n print(f\"Solution: {result.solution_path}\")\n print(f\"Tests: {result.test_path}\")\n```\n\n### With Input/Output Data\n\n```python\n# Process data with input/output examples\nresult = agent.process(\n \"Sort this list in ascending order\",\n input_data=[64, 34, 25, 12, 22, 11, 90, 5],\n expected_output=[5, 11, 12, 22, 25, 34, 64, 90],\n data_format=\"list\"\n)\n```\n\n### With Custom Prompts\n\n```python\n# Guide implementation style\nagent = SupervisorAgent(\n custom_prompt=\"Use object-oriented programming with SOLID principles\"\n)\n\nresult = agent.process(\"Create a calculator with basic operations\")\n```\n\n### Bring Your Own Model (BYOM)\n\n```python\n# Use your own LangChain LLM for guidance\nfrom langchain_openai import ChatOpenAI\n\ncustom_llm = ChatOpenAI(model='gpt-4o-mini', temperature=0.2)\nagent = SupervisorAgent(llm=custom_llm)\nresult = agent.process(\"Create a data processing function\")\n```\n\n### With Custom Configuration\n\n```python\n# Pass configuration as type-safe dataclass\nfrom claude_code_supervisor import SupervisorAgent\nfrom claude_code_supervisor.config import openai_config\n\nconfig = openai_config(model='gpt-4o-mini', temperature=0.1)\nconfig.agent.max_iterations = 3\nconfig.agent.solution_filename = 'my_solution.py'\nconfig.claude_code.max_turns = 25\n\nagent = SupervisorAgent(config=config)\nresult = agent.process(\"Create a web scraper function\")\n```\n\n### Advanced Configuration Examples\n\n```python\n# Use structured, type-safe configuration with dataclasses\nfrom claude_code_supervisor import SupervisorAgent\nfrom claude_code_supervisor.config import (\n SupervisorConfig, ModelConfig, AgentConfig,\n development_config, openai_config, bedrock_config\n)\n\n# Method 1: Use convenience functions\nconfig = development_config() # Pre-configured for development\nagent = SupervisorAgent(config=config)\n\n# Method 2: Use builder functions with customization\nconfig = openai_config(model='gpt-4o-mini', temperature=0.2)\nconfig.agent.max_iterations = 5\nconfig.agent.solution_filename = 'custom_solution.py'\nagent = SupervisorAgent(config=config)\n\n# Method 3: Build from scratch with type safety\nconfig = SupervisorConfig(\n model=ModelConfig(name='gpt-4o', temperature=0.1, provider='openai'),\n agent=AgentConfig(max_iterations=3, test_timeout=60)\n)\nagent = SupervisorAgent(config=config)\nresult = agent.process(\"Create a validation function\")\n```\n\n### Combining Configuration with Custom LLM\n\n```python\n# Use dataclass config + custom LLM together\nfrom langchain_aws import ChatBedrockConverse\nfrom claude_code_supervisor import SupervisorAgent\nfrom claude_code_supervisor.config import SupervisorConfig, AgentConfig\n\n# Custom LLM for guidance\nguidance_llm = ChatBedrockConverse(\n model='anthropic.claude-3-haiku-20240307-v1:0',\n temperature=0.1,\n)\n\n# Type-safe configuration (no model config needed since we provide LLM)\nconfig = SupervisorConfig(\n agent=AgentConfig(max_iterations=2, solution_filename='solution.py')\n)\n\nagent = SupervisorAgent(config=config, llm=guidance_llm)\nresult = agent.process(\"Create a file parser\")\n```\n\n### Command Line Interface\n\n```bash\n# Basic usage\nclaude-supervisor \"Create a hello world function\"\n\n# With custom prompt\nclaude-supervisor \"Create a web scraper\" --prompt=\"Use requests and BeautifulSoup\"\n```\n\n## \ud83d\udcca Data Format Support\n\nThe supervisor supports various data formats:\n\n- **Lists**: `[1, 2, 3, 4]`\n- **Dictionaries**: `{\"name\": \"Alice\", \"age\": 30}`\n- **Pandas DataFrames**: For data analysis tasks\n- **NumPy Arrays**: For numerical computations\n- **Strings**: Text processing tasks\n- **CSV Data**: Business logic and data processing\n\n## \ud83c\udfaf Examples\n\nCheck out the [examples directory](examples/) for detailed usage examples:\n\n- **Basic Usage**: Simple problem solving without I/O\n- **Data Processing**: Working with lists, dictionaries, and complex data\n- **Custom Prompts**: Guiding implementation toward specific patterns\n- **Advanced Scenarios**: Real-world data processing examples\n\n## \ud83d\udd27 Configuration\n\nSupervisorAgent uses type-safe dataclass configuration for better IDE support and validation:\n\n### Quick Setup with Convenience Functions\n\n```python\nfrom claude_code_supervisor import SupervisorAgent\nfrom claude_code_supervisor.config import openai_config, bedrock_config\n\n# OpenAI configuration\nconfig = openai_config(model='gpt-4o-mini', temperature=0.2)\nagent = SupervisorAgent(config=config)\n\n# AWS Bedrock configuration\nconfig = bedrock_config(\n model='anthropic.claude-3-haiku-20240307-v1:0',\n)\nagent = SupervisorAgent(config=config)\n```\n\n### Custom Configuration from Scratch\n\n```python\nfrom claude_code_supervisor import SupervisorAgent\nfrom claude_code_supervisor.config import SupervisorConfig, ModelConfig, AgentConfig\n\n# Build custom configuration\nconfig = SupervisorConfig(\n model=ModelConfig(\n name='gpt-4o',\n temperature=0.1,\n provider='openai'\n ),\n agent=AgentConfig(\n max_iterations=5,\n solution_filename='solution.py',\n test_filename='test_solution.py'\n )\n)\n\nagent = SupervisorAgent(config=config)\n```\n\n### Environment-Specific Configurations\n\n```python\nfrom claude_code_supervisor import SupervisorAgent\nfrom claude_code_supervisor.config import development_config, production_config\n\n# Development environment\ndev_config = development_config()\ndev_agent = SupervisorAgent(config=dev_config)\n\n# Production environment \nprod_config = production_config()\nprod_agent = SupervisorAgent(config=prod_config)\n```\n\n## \ud83e\uddea Testing\n\nRun the test suite:\n\n```bash\n# Run all tests\npytest\n\n# Run with coverage\npytest --cov=claude_code_supervisor\n\n# Run specific test categories\npytest -m \"unit\"\npytest -m \"integration\"\n```\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## \ud83d\udcdd License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\ude4f Acknowledgments\n\n- [Claude Code SDK](https://github.com/anthropics/claude-code-sdk) for the core Claude Code integration\n- [LangGraph](https://github.com/langchain-ai/langgraph) for workflow orchestration\n- [LangChain](https://github.com/langchain-ai/langchain) for LLM integrations\n\n## \ud83d\udcda Documentation\n\nFor detailed documentation, visit our [docs](docs/) directory or check out the [API Reference](docs/api.md).\n\n## \ud83d\udc1b Issues\n\nFound a bug? Have a feature request? Please [open an issue](https://github.com/vinyluis/claude-code-supervisor/issues).\n\n---\n\n**Made with \u2764\ufe0f by [Vin\u00edcius Trevisan](mailto:vinicius@viniciustrevisan.com)**\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "An intelligent wrapper around Claude Code SDK for automated problem-solving",
"version": "0.1.3",
"project_urls": {
"Changelog": "https://github.com/vinyluis/claude-code-supervisor/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/vinyluis/claude-code-supervisor#readme",
"Homepage": "https://github.com/vinyluis/claude-code-supervisor",
"Issues": "https://github.com/vinyluis/claude-code-supervisor/issues",
"Repository": "https://github.com/vinyluis/claude-code-supervisor.git"
},
"split_keywords": [
"claude",
" code-generation",
" ai",
" automation",
" testing",
" development"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "16f4ca377b5a9a109f2af99b9a935780ff25a9c2cc113a868ab571b59d06f7e0",
"md5": "6490a708e6f0136083f5cd0680f61764",
"sha256": "234031d5408d30ad581a587a0e04f9403bbe7bef54f0c13e3a41f781b99c0a05"
},
"downloads": -1,
"filename": "claude_code_supervisor-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6490a708e6f0136083f5cd0680f61764",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 26986,
"upload_time": "2025-07-08T22:37:55",
"upload_time_iso_8601": "2025-07-08T22:37:55.557309Z",
"url": "https://files.pythonhosted.org/packages/16/f4/ca377b5a9a109f2af99b9a935780ff25a9c2cc113a868ab571b59d06f7e0/claude_code_supervisor-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "60c7baf91388fdbc0b85564a7cadf248c4008e2307c667dc062573a9ab6170ee",
"md5": "593cba3498bed4aa326fff22be49bd0a",
"sha256": "2ac033cff4df1273bc113ecdfc813042fd7e79e40a191d6c8a464886f98a52f8"
},
"downloads": -1,
"filename": "claude_code_supervisor-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "593cba3498bed4aa326fff22be49bd0a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 41175,
"upload_time": "2025-07-08T22:37:57",
"upload_time_iso_8601": "2025-07-08T22:37:57.241345Z",
"url": "https://files.pythonhosted.org/packages/60/c7/baf91388fdbc0b85564a7cadf248c4008e2307c667dc062573a9ab6170ee/claude_code_supervisor-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-08 22:37:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "vinyluis",
"github_project": "claude-code-supervisor",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "numpy",
"specs": [
[
"==",
"2.3.1"
]
]
},
{
"name": "pandas",
"specs": [
[
"==",
"2.3.0"
]
]
},
{
"name": "scikit-learn",
"specs": [
[
"==",
"1.7.0"
]
]
},
{
"name": "langchain",
"specs": [
[
"==",
"0.3.26"
]
]
},
{
"name": "langchain-aws",
"specs": [
[
"==",
"0.2.27"
]
]
},
{
"name": "langchain-openai",
"specs": [
[
"==",
"0.3.26"
]
]
},
{
"name": "langgraph",
"specs": [
[
"==",
"0.4.10"
]
]
},
{
"name": "claude-code-sdk",
"specs": [
[
"==",
"0.0.14"
]
]
},
{
"name": "pytest",
"specs": [
[
">=",
"6.0.0"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
">=",
"0.19.0"
]
]
}
],
"lcname": "claude-code-supervisor"
}
JSON
