{"id":30717810,"url":"https://github.com/cheolwanpark/claude-agent-toolkit","last_synced_at":"2025-09-06T19:04:56.744Z","repository":{"id":312531610,"uuid":"1047811609","full_name":"cheolwanpark/claude-agent-toolkit","owner":"cheolwanpark","description":"Python framework for building agents using claude-code-sdk with programmable tools","archived":false,"fork":false,"pushed_at":"2025-09-01T14:00:36.000Z","size":210,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-01T15:08:58.661Z","etag":null,"topics":["agent","agentic-ai","agentic-ai-development","agentic-workflow","agents","ai","ai-agents","claude","claude-ai","claude-code","claude-code-sdk","fastmcp","mcp","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cheolwanpark.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-31T09:36:59.000Z","updated_at":"2025-09-01T14:00:39.000Z","dependencies_parsed_at":"2025-09-01T15:09:17.555Z","dependency_job_id":null,"html_url":"https://github.com/cheolwanpark/claude-agent-toolkit","commit_stats":null,"previous_names":["cheolwanpark/claude-adk","cheolwanpark/claude-agent-toolkit"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/cheolwanpark/claude-agent-toolkit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cheolwanpark%2Fclaude-agent-toolkit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cheolwanpark%2Fclaude-agent-toolkit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cheolwanpark%2Fclaude-agent-toolkit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cheolwanpark%2Fclaude-agent-toolkit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cheolwanpark","download_url":"https://codeload.github.com/cheolwanpark/claude-agent-toolkit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cheolwanpark%2Fclaude-agent-toolkit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273417342,"owners_count":25101817,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-03T02:00:09.631Z","response_time":76,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","agentic-ai","agentic-ai-development","agentic-workflow","agents","ai","ai-agents","claude","claude-ai","claude-code","claude-code-sdk","fastmcp","mcp","python"],"created_at":"2025-09-03T09:02:07.317Z","updated_at":"2025-09-04T15:04:58.970Z","avatar_url":"https://github.com/cheolwanpark.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Claude Code Agent Toolkit (claude-agent-toolkit)\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_agent_toolkit/agent/`) - Docker-isolated Agent class that runs Claude Code with MCP tool support\n- **MCP Tool Framework** (`src/claude_agent_toolkit/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-agent-toolkit\n\n# Using uv\nuv add claude-agent-toolkit\n\n# Using poetry\npoetry add claude-agent-toolkit\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-agent-toolkit.git\ncd claude-agent-toolkit\n\n# Start Docker Desktop first, then run the verification demo\n# Run calculator example:\ncd src/examples/calculator \u0026\u0026 python main.py\n# Run weather example:\ncd src/examples/weather \u0026\u0026 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_agent_toolkit 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) -\u003e 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) -\u003e 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_agent_toolkit import Agent, ConnectionError, ExecutionError\n\ntry:\n    # Create and start tool\n    my_tool = MyTool().run(workers=2)\n\n    # New pattern (recommended) - cleaner initialization\n    agent = 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)\n    result = await agent.run(\n        \"Please increment the counter twice and tell me the result\",\n        verbose=True  # Shows detailed Claude Code interaction logs\n    )\n    print(f\"Success: {result['success']}\")\n    print(f\"Response: {result['response']}\")\n\n    # Verify tool was actually called\n    print(f\"Tool state: {my_tool.state}\")\n    \nexcept ConnectionError as e:\n    print(f\"Connection issue: {e}\")\n    # Handle Docker, network, or port binding problems\n    \nexcept ExecutionError as e:\n    print(f\"Execution failed: {e}\")\n    # Handle agent execution or tool failures\n```\n\n## Model Selection\n\nChoose the right Claude model for your agent's needs:\n\n### Available Models\n- **\"haiku\"** - Fast and efficient for simple tasks\n- **\"sonnet\"** - Balanced performance (good default choice)\n- **\"opus\"** - Most capable for complex reasoning\n\n### Usage Examples\n\n```python\nfrom claude_agent_toolkit import Agent\n\n# Use fast Haiku model for simple tasks\nweather_agent = Agent(\n    system_prompt=\"You are a weather assistant\",\n    tools=[weather_tool],\n    model=\"haiku\"  # Fast, efficient for simple weather queries\n)\n\n# Use Sonnet for general-purpose tasks\ngeneral_agent = Agent(\n    system_prompt=\"You are a helpful assistant\", \n    tools=[calculator_tool, weather_tool],\n    model=\"sonnet\"  # Balanced performance\n)\n\n# Use Opus for complex analysis\nanalysis_agent = Agent(\n    system_prompt=\"You are a data analyst\",\n    tools=[analysis_tool],\n    model=\"opus\"  # Maximum reasoning capability\n)\n\n# Override model for specific queries\nresult = await weather_agent.run(\n    \"Complex weather pattern analysis for next month\",\n    model=\"opus\"  # Use more capable model for this specific task\n)\n\n# Full model IDs also work\nagent = Agent(model=\"claude-3-5-haiku-20241022\")\n```\n\n### When to Use Each Model\n- **Haiku**: Simple queries, basic operations, fast responses needed\n- **Sonnet**: General purpose tasks, good balance of speed and capability\n- **Opus**: Complex reasoning, detailed analysis, maximum quality needed\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        model: Optional[Union[Literal[\"opus\", \"sonnet\", \"haiku\"], str]] = None  # Model selection\n    )\n    def connect(self, tool: BaseTool) -\u003e '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        model: Optional[Union[Literal[\"opus\", \"sonnet\", \"haiku\"], str]] = None  # Override model\n    ) -\u003e 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) -\u003e 'BaseTool'\n    @property def connection_url(self) -\u003e str\n    @property def state(self) -\u003e 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### Exception Classes\n\nClaude Agent Toolkit provides specific exception types for clear error handling:\n\n```python\n# Import exception classes\nfrom claude_agent_toolkit import (\n    ClaudeAgentError,     # Base exception for all library errors\n    ConfigurationError,   # Missing OAuth tokens, invalid configuration\n    ConnectionError,      # Docker, network, port binding failures  \n    ExecutionError,       # Agent execution, tool failures, timeouts\n    StateError           # Tool lifecycle, state management issues\n)\n\n# Exception hierarchy\nClaudeAgentError\n├── ConfigurationError    # Configuration issues\n├── ConnectionError       # Network/service connectivity\n├── ExecutionError       # Runtime execution failures\n└── StateError          # State management problems\n```\n\n**When to catch each exception:**\n\n- **ConfigurationError**: Handle setup issues, missing tokens, invalid configs\n- **ConnectionError**: Handle Docker, network, and port binding failures\n- **ExecutionError**: Handle runtime failures, timeouts, tool execution issues  \n- **StateError**: Handle tool lifecycle violations, state conflicts\n- **ClaudeAgentError**: Catch all library errors with a single handler\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\u003e=7.1.0` - Docker container management\n- `fastmcp\u003e=2.11.3` - MCP server framework\n- `httpx\u003e=0.28.1` - HTTP client for health checks\n- `jsonpatch\u003e=1.33` - State management with JSON patches  \n- `uvicorn\u003e=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## Error Handling\n\nClaude Agent Toolkit uses specific exception types to help you handle errors gracefully:\n\n```python\nfrom claude_agent_toolkit import (\n    Agent, BaseTool, tool,\n    ClaudeAgentError, ConfigurationError, ConnectionError,\n    ExecutionError, StateError\n)\n\n# Handle specific error types\ntry:\n    agent = Agent(\n        oauth_token=\"your-token\",\n        tools=[MyTool().run()]\n    )\n    result = await agent.run(\"Process my request\")\n    \nexcept ConfigurationError as e:\n    print(f\"Configuration issue: {e}\")\n    # Handle missing OAuth token, invalid tool config\n    \nexcept ConnectionError as e:\n    print(f\"Connection failed: {e}\")\n    # Handle Docker, network, port binding issues\n    \nexcept ExecutionError as e:\n    print(f\"Execution failed: {e}\")\n    # Handle agent execution, tool failures, timeouts\n    \nexcept StateError as e:\n    print(f\"State management issue: {e}\")\n    # Handle tool lifecycle, state conflicts\n    \nexcept ClaudeAgentError as e:\n    print(f\"Library error: {e}\")\n    # Catch all library errors\n```\n\n## Troubleshooting\n\n### Common Issues\n\n**ConfigurationError: \"OAuth token required\"**\n```python\n# Set environment variable\nexport CLAUDE_CODE_OAUTH_TOKEN='your-token-here'\n\n# Or pass directly to Agent\nagent = Agent(oauth_token='your-token-here')\n```\n\n**ConnectionError: \"Cannot connect to Docker\"**\n- Ensure Docker Desktop is running\n- Check Docker daemon is accessible\n- Linux: `sudo systemctl start docker`\n\n**ConnectionError: \"Port binding failed\"**\n```python\n# Let tools auto-select available ports\ntool = MyTool().run()  # Auto-selects port\n\n# Or specify different port\ntool = MyTool().run(port=9000)\n```\n\n**StateError: \"Tool is not running\"**\n```python\n# Start tool before accessing properties\ntool = MyTool()\ntool.run()  # Start the tool\nurl = tool.connection_url  # Now accessible\n```\n\n**ExecutionError: \"Operation timed out\"**\n```python\n# Increase timeout for CPU-bound operations\n@tool(cpu_bound=True, timeout_s=300)  # 5 minute timeout\nasync def heavy_computation(self):\n    pass\n```\n\n### Debug Mode\n```python\nfrom claude_agent_toolkit import set_logging, LogLevel\n\n# Enable detailed logging\nset_logging(LogLevel.DEBUG, show_time=True, show_level=True)\n\n# Run with verbose output\nresult = await agent.run(\"your prompt\", verbose=True)\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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcheolwanpark%2Fclaude-agent-toolkit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcheolwanpark%2Fclaude-agent-toolkit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcheolwanpark%2Fclaude-agent-toolkit/lists"}