# Claude Code Agent Development Kit (claude-adk)
A Python framework for building Claude Code agents with custom tools, designed to leverage Claude Code's advanced reasoning capabilities with your subscription token. The framework provides Docker-isolated environments where Claude Code can orchestrate custom MCP tools for production workflows.
## Key Features
- **Claude Code Integration** - Leverage Claude Code's advanced reasoning with your existing subscription token
- **Docker Isolation** - Complete isolation of agent execution environment with Claude Code CLI
- **Advanced State Management** - JSON patch-based state management with conflict resolution and automatic retries
- **CPU-bound Operations** - Support for CPU-intensive operations with process pools and parallel execution
- **Multi-tool Coordination** - Claude Code orchestrates multiple tools in complex workflows
- **Production Ready** - Build scalable agents using Claude Code's capabilities with custom tool integration
## Architecture
### Core Components
- **Agent Framework** (`src/claude_adk/agent/`) - Docker-isolated Agent class that runs Claude Code with MCP tool support
- **MCP Tool Framework** (`src/claude_adk/tool/`) - BaseTool class for creating custom MCP tools with state management
- **Example Tools** (`src/examples/`) - Demonstration tools showing practical agent development patterns
- **Docker Environment** (`src/docker/`) - Isolated environment with Claude Code CLI and dependencies
## Quick Start
### Prerequisites
- **Python 3.12+** with `uv` package manager
- **Docker Desktop** (must be running)
- **Claude Code OAuth Token** - Get from [Claude Code](https://claude.ai/code)
### Installation
```bash
# Using pip
pip install claude-adk
# Using uv
uv add claude-adk
# Using poetry
poetry add claude-adk
# Set your OAuth token
export CLAUDE_CODE_OAUTH_TOKEN='your-token-here'
```
### Run the Demo
```bash
# Clone the repository for examples
git clone https://github.com/cheolwanpark/claude-adk.git
cd claude-adk
# Start Docker Desktop first, then run the verification demo
# Run calculator example:
cd src/examples/calculator && python main.py
# Run weather example:
cd src/examples/weather && python main.py
```
This will run demonstration examples:
1. **Calculator Demo** - Shows stateful mathematical operations and problem solving
2. **Weather Demo** - Demonstrates external API integration with real-time data
## Tool Development
### Creating Custom Tools
Create tools by inheriting from `BaseTool` and using the `@tool()` decorator:
```python
from claude_adk import BaseTool, tool
class MyTool(BaseTool):
def __init__(self):
super().__init__()
self.state = {"counter": 0}
@tool(description="Increment counter and return new value")
async def increment(self) -> dict:
self.state["counter"] += 1
return {"value": self.state["counter"]}
@tool(description="Heavy computation", cpu_bound=True)
def compute_heavy(self, data: str) -> dict:
# CPU-intensive operation runs in process pool
import time
time.sleep(2) # Simulate heavy computation
return {"processed": f"Heavy result for {data}"}
```
### Using Tools with Agents
```python
from claude_adk import Agent
# Create and start tool
my_tool = MyTool().run(workers=2)
# New pattern (recommended) - cleaner initialization
agent = Agent(
system_prompt="You are a helpful assistant specialized in calculations",
tools=[my_tool]
)
# Traditional pattern - still supported
# agent = Agent()
# agent.connect(my_tool)
# Run agent with prompt (verbose=True shows detailed message processing)
result = await agent.run(
"Please increment the counter twice and tell me the result",
verbose=True # Shows detailed Claude Code interaction logs
)
print(f"Success: {result['success']}")
print(f"Response: {result['response']}")
# Verify tool was actually called
print(f"Tool state: {my_tool.state}")
```
## Why Claude Code Agents?
Unlike generic agent frameworks, this toolkit specifically leverages Claude Code's unique capabilities:
1. **Advanced Reasoning** - Use Claude Code's sophisticated decision-making in your agents
2. **Existing Subscription** - Build production agents with your current Claude Code subscription
3. **Stateful Workflows** - Claude Code builds context across multiple tool interactions
4. **Intelligent Orchestration** - Claude Code decides which tools to use and when
5. **Production Infrastructure** - Leverage Claude's robust infrastructure for your agents
### Example: Intelligent Workflow
```python
# Claude Code analyzes data with one tool, then decides to process it with another
# The agent maintains context and makes intelligent decisions about tool usage
# Your tools provide capabilities, Claude Code provides the intelligence
```
## API Reference
### Agent Class
```python
class Agent:
def __init__( # Initialize agent
self,
oauth_token: Optional[str] = None, # Your Claude Code token
system_prompt: Optional[str] = None, # Custom agent behavior
tools: Optional[List[BaseTool]] = None # Tools to connect automatically
)
def connect(self, tool: BaseTool) -> 'Agent' # Connect custom tools
async def run( # Run Claude Code with tools
self,
prompt: str, # Instruction for Claude
verbose: bool = False # Show detailed processing logs
) -> Dict[str, Any]
```
### BaseTool Class
```python
class BaseTool:
def __init__(self)
def run(self, host="127.0.0.1", port=None, *, workers=None) -> 'BaseTool'
@property def connection_url(self) -> str
@property def state(self) -> Any # Mutable state dictionary
```
### @tool() Decorator
```python
@tool(
name: Optional[str] = None, # Tool method name
description: str = "", # Method description
cpu_bound: bool = False, # Use process pool
timeout_s: int = 60, # Timeout for CPU-bound operations
conflict_policy: str = "retry", # How to handle state conflicts
max_retries: int = 16 # Max retry attempts
)
```
## Development Workflow
### 1. Start Docker Desktop
Required for agent execution - must be running before creating Claude Code agents.
### 2. Set OAuth Token
```bash
export CLAUDE_CODE_OAUTH_TOKEN='your-token-here'
```
### 3. Create Custom Tools
Inherit from `BaseTool` and implement `@tool` methods that extend Claude Code's capabilities.
### 4. Build Your Agent
Use the examples in `src/examples/` to see demonstrations or create custom agent scripts.
### 5. Deploy to Production
Use your Claude Code subscription to run agents at scale with custom tool integration.
## Dependencies
### Runtime Dependencies
- `docker>=7.1.0` - Docker container management
- `fastmcp>=2.11.3` - MCP server framework
- `httpx>=0.28.1` - HTTP client for health checks
- `jsonpatch>=1.33` - State management with JSON patches
- `uvicorn>=0.35.0` - ASGI server for MCP HTTP endpoints
### Docker Environment
- Python 3.11 with Claude Code SDK
- Node.js 20 with Claude Code CLI
- Non-root user execution for security
## Troubleshooting
### Common Issues
**"Cannot connect to Docker"**
- Ensure Docker Desktop is running
- Check Docker daemon is accessible
**"OAuth token required"**
- Set `CLAUDE_CODE_OAUTH_TOKEN` environment variable
- Get token from [Claude Code](https://claude.ai/code)
**Tool connection failures**
- Check tool health endpoints are accessible
- Verify port conflicts (tools auto-assign ports)
- Review Docker network connectivity
### Debug Mode
```bash
# Enable detailed logging
export CLAUDE_DEBUG=1
python main.py
```
## Contributing
1. Create custom tools for different Claude Code agent use cases
2. Add new agent development patterns and templates
3. Improve Docker image efficiency and security
4. Enhance state management and conflict resolution
5. Add support for additional MCP server types
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Related Projects
- [Claude Code](https://claude.ai/code) - Official Claude Code interface (required for this framework)
- [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) - Protocol for AI-tool integration
- [FastMCP](https://github.com/jlowin/fastmcp) - Fast MCP server implementation
Raw data
{
"_id": null,
"home_page": null,
"name": "claude-adk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": "Cheolwan Park <cheolwan.park552@gmail.com>",
"keywords": "agent-framework, ai-agents, claude-adk, claude-agents, claude-code, docker, mcp-tools, model-context-protocol",
"author": null,
"author_email": "Cheolwan Park <cheolwan.park552@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/bb/d9/1ed5eb1386c83cb619598e908347cae39d4fd641890fb604817af1d5937f/claude_adk-0.1.2.tar.gz",
"platform": null,
"description": "# Claude Code Agent Development Kit (claude-adk)\n\nA Python framework for building Claude Code agents with custom tools, designed to leverage Claude Code's advanced reasoning capabilities with your subscription token. The framework provides Docker-isolated environments where Claude Code can orchestrate custom MCP tools for production workflows.\n\n## Key Features\n\n- **Claude Code Integration** - Leverage Claude Code's advanced reasoning with your existing subscription token\n- **Docker Isolation** - Complete isolation of agent execution environment with Claude Code CLI\n- **Advanced State Management** - JSON patch-based state management with conflict resolution and automatic retries \n- **CPU-bound Operations** - Support for CPU-intensive operations with process pools and parallel execution\n- **Multi-tool Coordination** - Claude Code orchestrates multiple tools in complex workflows\n- **Production Ready** - Build scalable agents using Claude Code's capabilities with custom tool integration\n\n## Architecture\n\n### Core Components\n\n- **Agent Framework** (`src/claude_adk/agent/`) - Docker-isolated Agent class that runs Claude Code with MCP tool support\n- **MCP Tool Framework** (`src/claude_adk/tool/`) - BaseTool class for creating custom MCP tools with state management\n- **Example Tools** (`src/examples/`) - Demonstration tools showing practical agent development patterns\n- **Docker Environment** (`src/docker/`) - Isolated environment with Claude Code CLI and dependencies\n\n## Quick Start\n\n### Prerequisites\n\n- **Python 3.12+** with `uv` package manager\n- **Docker Desktop** (must be running)\n- **Claude Code OAuth Token** - Get from [Claude Code](https://claude.ai/code)\n\n### Installation\n\n```bash\n# Using pip\npip install claude-adk\n\n# Using uv\nuv add claude-adk\n\n# Using poetry\npoetry add claude-adk\n\n# Set your OAuth token\nexport CLAUDE_CODE_OAUTH_TOKEN='your-token-here'\n```\n\n### Run the Demo\n\n```bash\n# Clone the repository for examples\ngit clone https://github.com/cheolwanpark/claude-adk.git\ncd claude-adk\n\n# Start Docker Desktop first, then run the verification demo\n# Run calculator example:\ncd src/examples/calculator && python main.py\n# Run weather example:\ncd src/examples/weather && python main.py\n```\n\nThis will run demonstration examples:\n1. **Calculator Demo** - Shows stateful mathematical operations and problem solving\n2. **Weather Demo** - Demonstrates external API integration with real-time data\n\n## Tool Development\n\n### Creating Custom Tools\n\nCreate tools by inheriting from `BaseTool` and using the `@tool()` decorator:\n\n```python\nfrom claude_adk import BaseTool, tool\n\nclass MyTool(BaseTool):\n def __init__(self):\n super().__init__()\n self.state = {\"counter\": 0}\n \n @tool(description=\"Increment counter and return new value\")\n async def increment(self) -> dict:\n self.state[\"counter\"] += 1\n return {\"value\": self.state[\"counter\"]}\n \n @tool(description=\"Heavy computation\", cpu_bound=True) \n def compute_heavy(self, data: str) -> dict:\n # CPU-intensive operation runs in process pool\n import time\n time.sleep(2) # Simulate heavy computation\n return {\"processed\": f\"Heavy result for {data}\"}\n```\n\n### Using Tools with Agents\n\n```python\nfrom claude_adk import Agent\n\n# Create and start tool\nmy_tool = MyTool().run(workers=2)\n\n# New pattern (recommended) - cleaner initialization\nagent = Agent(\n system_prompt=\"You are a helpful assistant specialized in calculations\",\n tools=[my_tool]\n)\n\n# Traditional pattern - still supported\n# agent = Agent()\n# agent.connect(my_tool)\n\n# Run agent with prompt (verbose=True shows detailed message processing)\nresult = await agent.run(\n \"Please increment the counter twice and tell me the result\",\n verbose=True # Shows detailed Claude Code interaction logs\n)\nprint(f\"Success: {result['success']}\")\nprint(f\"Response: {result['response']}\")\n\n# Verify tool was actually called\nprint(f\"Tool state: {my_tool.state}\")\n```\n\n## Why Claude Code Agents?\n\nUnlike generic agent frameworks, this toolkit specifically leverages Claude Code's unique capabilities:\n\n1. **Advanced Reasoning** - Use Claude Code's sophisticated decision-making in your agents\n2. **Existing Subscription** - Build production agents with your current Claude Code subscription\n3. **Stateful Workflows** - Claude Code builds context across multiple tool interactions\n4. **Intelligent Orchestration** - Claude Code decides which tools to use and when\n5. **Production Infrastructure** - Leverage Claude's robust infrastructure for your agents\n\n### Example: Intelligent Workflow\n\n```python\n# Claude Code analyzes data with one tool, then decides to process it with another\n# The agent maintains context and makes intelligent decisions about tool usage\n# Your tools provide capabilities, Claude Code provides the intelligence\n```\n\n## API Reference\n\n### Agent Class\n\n```python\nclass Agent:\n def __init__( # Initialize agent\n self,\n oauth_token: Optional[str] = None, # Your Claude Code token\n system_prompt: Optional[str] = None, # Custom agent behavior\n tools: Optional[List[BaseTool]] = None # Tools to connect automatically\n )\n def connect(self, tool: BaseTool) -> 'Agent' # Connect custom tools \n async def run( # Run Claude Code with tools\n self,\n prompt: str, # Instruction for Claude\n verbose: bool = False # Show detailed processing logs\n ) -> Dict[str, Any]\n```\n\n### BaseTool Class \n\n```python\nclass BaseTool:\n def __init__(self)\n def run(self, host=\"127.0.0.1\", port=None, *, workers=None) -> 'BaseTool'\n @property def connection_url(self) -> str\n @property def state(self) -> Any # Mutable state dictionary\n```\n\n### @tool() Decorator\n\n```python\n@tool(\n name: Optional[str] = None, # Tool method name\n description: str = \"\", # Method description \n cpu_bound: bool = False, # Use process pool\n timeout_s: int = 60, # Timeout for CPU-bound operations\n conflict_policy: str = \"retry\", # How to handle state conflicts\n max_retries: int = 16 # Max retry attempts\n)\n```\n\n## Development Workflow\n\n### 1. Start Docker Desktop\nRequired for agent execution - must be running before creating Claude Code agents.\n\n### 2. Set OAuth Token \n```bash\nexport CLAUDE_CODE_OAUTH_TOKEN='your-token-here'\n```\n\n### 3. Create Custom Tools\nInherit from `BaseTool` and implement `@tool` methods that extend Claude Code's capabilities.\n\n### 4. Build Your Agent \nUse the examples in `src/examples/` to see demonstrations or create custom agent scripts.\n\n### 5. Deploy to Production\nUse your Claude Code subscription to run agents at scale with custom tool integration.\n\n## Dependencies\n\n### Runtime Dependencies\n- `docker>=7.1.0` - Docker container management\n- `fastmcp>=2.11.3` - MCP server framework\n- `httpx>=0.28.1` - HTTP client for health checks\n- `jsonpatch>=1.33` - State management with JSON patches \n- `uvicorn>=0.35.0` - ASGI server for MCP HTTP endpoints\n\n### Docker Environment \n- Python 3.11 with Claude Code SDK\n- Node.js 20 with Claude Code CLI\n- Non-root user execution for security\n\n## Troubleshooting\n\n### Common Issues\n\n**\"Cannot connect to Docker\"**\n- Ensure Docker Desktop is running\n- Check Docker daemon is accessible\n\n**\"OAuth token required\"** \n- Set `CLAUDE_CODE_OAUTH_TOKEN` environment variable\n- Get token from [Claude Code](https://claude.ai/code)\n\n**Tool connection failures**\n- Check tool health endpoints are accessible\n- Verify port conflicts (tools auto-assign ports)\n- Review Docker network connectivity\n\n### Debug Mode\n```bash\n# Enable detailed logging\nexport CLAUDE_DEBUG=1\npython main.py\n```\n\n## Contributing\n\n1. Create custom tools for different Claude Code agent use cases\n2. Add new agent development patterns and templates\n3. Improve Docker image efficiency and security\n4. Enhance state management and conflict resolution\n5. Add support for additional MCP server types\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Related Projects\n\n- [Claude Code](https://claude.ai/code) - Official Claude Code interface (required for this framework)\n- [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) - Protocol for AI-tool integration\n- [FastMCP](https://github.com/jlowin/fastmcp) - Fast MCP server implementation",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python framework for building Claude Code agents with custom tools",
"version": "0.1.2",
"project_urls": {
"Changelog": "https://github.com/cheolwanpark/claude-adk/blob/main/CHANGELOG.md",
"Claude Code": "https://claude.ai/code",
"Documentation": "https://github.com/cheolwanpark/claude-adk#readme",
"Homepage": "https://github.com/cheolwanpark/claude-adk",
"Issues": "https://github.com/cheolwanpark/claude-adk/issues",
"Repository": "https://github.com/cheolwanpark/claude-adk.git"
},
"split_keywords": [
"agent-framework",
" ai-agents",
" claude-adk",
" claude-agents",
" claude-code",
" docker",
" mcp-tools",
" model-context-protocol"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "da9bb3cbf9f1cea38d4236f34f05648b93dfc2d08e63ba9c6144d0e7b6d9c238",
"md5": "749b962a683032dc048b902d7d0d02a8",
"sha256": "cca064d3c7ac69a22e3c9bc89b506d8668bc152017ccd2947021d9ef1d3136f7"
},
"downloads": -1,
"filename": "claude_adk-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "749b962a683032dc048b902d7d0d02a8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 18845,
"upload_time": "2025-08-31T12:19:33",
"upload_time_iso_8601": "2025-08-31T12:19:33.518823Z",
"url": "https://files.pythonhosted.org/packages/da/9b/b3cbf9f1cea38d4236f34f05648b93dfc2d08e63ba9c6144d0e7b6d9c238/claude_adk-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "bbd91ed5eb1386c83cb619598e908347cae39d4fd641890fb604817af1d5937f",
"md5": "ba9fda69905b371452f2e4da09d157d3",
"sha256": "ae837420ec8c2e84807678b9fa757e541963563ae9dde8f5f08bbe2375559a11"
},
"downloads": -1,
"filename": "claude_adk-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "ba9fda69905b371452f2e4da09d157d3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 30227,
"upload_time": "2025-08-31T12:19:35",
"upload_time_iso_8601": "2025-08-31T12:19:35.960703Z",
"url": "https://files.pythonhosted.org/packages/bb/d9/1ed5eb1386c83cb619598e908347cae39d4fd641890fb604817af1d5937f/claude_adk-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-31 12:19:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cheolwanpark",
"github_project": "claude-adk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "claude-adk"
}
JSON
