Development Background

Claude Agent Toolkit provides superior developer experience and execution capabilities. Key advantages include class-based tool organization with automatic MCP server management, Docker-isolated execution preventing system tool access, and parallel processing for CPU-intensive operations that won't block the main execution thread.

Why it is better than using claude-code-sdk directly?

See the Difference

Before (Direct claude-code-sdk):

# Manual tool naming and complex schema definition required
@tool("greet", "Greet a user", {"name": str})
async def greet_user(args):
    return {
        "content": [
            {"type": "text", "text": f"Hello, {args['name']}!"}
        ]
    }

# Tool functions and MCP server are decoupled - difficult to maintain at scale
server = create_sdk_mcp_server(
    name="my-tools",
    version="1.0.0",
    tools=[greet_user]
)

# At Runtime:
# ❌ Subprocess can access system tools (Read, LS, Grep)
# ❌ Manual environment configuration required
# ❌ No control over Claude Code's tool access
# ❌ Risk of unintended system interactions

After (Claude Agent Toolkit):

# Intuitive class-based tool definition with integrated MCP server
class CalculatorTool(BaseTool):
    @tool(description="Adds two numbers together")
    async def add(self, a: float, b: float) -> dict:
        return {"result": a + b}

# Single line agent creation with controlled tool access
agent = Agent(tools=[CalculatorTool()])

# At Runtime:
# ✅ Docker container runs only your defined tools
# ✅ No access to system tools (Read, LS, Grep)
# ✅ Clean, isolated, predictable execution environment
# ✅ Complete control over Claude Code's capabilities

Key Differences

Custom tool creation is fundamentally different between approaches. The SDK requires manual schema definitions with no built-in parallel execution support, while Claude Agent Toolkit offers intuitive class-based definitions using the @tool decorator with built-in parallel execution via parallel=True .

Runtime isolation represents a major architectural difference. The SDK provides no built-in isolation - you must design your own - whereas Claude Agent Toolkit uses Docker by default and allows only tools you explicitly add.

Environment consistency shows the practical impact. The SDK requires manual environment setup and explicit tool/option configuration, while Claude Agent Toolkit needs zero setup and works out of the box.

Setup complexity varies significantly: approximately 20 lines just for ClaudeCodeOptions configuration with the SDK versus 25 lines for a complete agent with calculator functionality using Claude Agent Toolkit, plus Agent.run(verbose=True) shows all responses.

Built-in tools highlight the development experience difference. The SDK requires building everything from scratch, while Claude Agent Toolkit provides FileSystemTool with permission control and DataTransferTool for formatted output handling.

Best use cases depend on your needs: the SDK excels for using Claude Code as-is with minimal dependencies, while Claude Agent Toolkit shines for fast development and using Claude Code as a reasoning engine similar to LangGraph agents.

Core Features

Decorator-Based Tool Creation

Claude Agent Toolkit provides superior developer experience through class-based tool organization. Unlike SDK's function-based approach, tools are encapsulated within classes with automatic MCP server management and state persistence.

The key advantage is parallel execution for CPU-intensive operations. While claude-code-sdk runs tools in the main process (causing blocking), Claude Agent Toolkit supports parallel=True to execute compute-heavy operations in separate process pools:

from claude_agent_toolkit import BaseTool, tool

class CalculatorTool(BaseTool):
    def __init__(self):
        super().__init__()
        self.history = []
        self.last_result = None

    @tool(description="Adds two numbers together")
    async def add(self, a: float, b: float) -> dict:
        result = a + b
        self.last_result = result
        self.history.append(f"{a} + {b} = {result}")

        return {
            "operation": f"{a} + {b}",
            "result": result,
            "message": f"The result of adding {a} and {b} is {result}"
        }

    @tool(description="CPU-intensive factorial calculation", parallel=True, timeout_s=120)
    def factorial(self, n: int) -> dict:
        # Runs in separate process - won't block agent execution
        import math
        result = math.factorial(n)
        return {"result": result, "parallel_execution": True}

Tools integrate seamlessly with Agent objects:

from claude_agent_toolkit import Agent

calculator_tool = CalculatorTool()

agent = Agent(
    system_prompt="I am a friendly assistant that helps with mathematical calculations.",
    tools=[calculator_tool]
)

result = await agent.run("What is 10 plus 5?")

Docker-Based Isolated Execution

To provide an isolated execution environment unaffected by the local environment, Docker containers are used as the default executor. This ensures identical execution results regardless of the environment.

For cases where Docker usage is difficult, subprocess execution is also supported.

from claude_agent_toolkit import Agent, ExecutorType

# Default: Uses Docker executor
agent = Agent(tools=[calculator_tool])

# Switch to subprocess executor
agent = Agent(tools=[calculator_tool], executor=ExecutorType.SUBPROCESS)

Built-in Tools

Built-in tools are provided for frequently used functionalities. FileSystemTool supports secure file system access with pattern-based permission control, while DataTransferTool enables structured data transfer based on Pydantic models. Since tools run on the host, they can be used for communication between host processes and agents running in Docker containers.

from claude_agent_toolkit.tools import FileSystemTool, DataTransferTool
from pydantic import BaseModel

# File system access tool
permissions = [
    ("*.txt", "read"),           # Read permission for all text files
    ("data/**", "write"),        # Write permission for data directory
    ("logs/*.log", "read"),      # Read permission for log files
]
fs_tool = FileSystemTool(permissions=permissions, root_dir="/workspace")

# Structured data transfer tool
class UserProfile(BaseModel):
    name: str
    age: int
    email: str

user_tool = DataTransferTool.create(UserProfile, "UserProfileTool")

Key Advantages

Simple Tool Integration

Class declaration and the @tool decorator alone convert regular methods into tools that Claude Code-based agents can use. They are immediately available without complex MCP server configuration or deployment processes.

Secure Isolated Execution

Execution occurs within Docker containers, allowing only connected tools. This ensures consistent results without being affected by local environment configurations.

Getting Started

Installation is straightforward using pip.

pip install claude-agent-toolkit

After setting up the Claude Code OAuth token and running Docker Desktop, you can begin using the toolkit.

export CLAUDE_CODE_OAUTH_TOKEN='your-token-here'

Let us begin with a simple example.

import asyncio
from claude_agent_toolkit import Agent, BaseTool, tool

class HelloTool(BaseTool):
    @tool(description="Say hello")
    async def say_hello(self, name: str) -> dict:
        return f"Hello! {name}!!"

async def main():
    agent = Agent(
        tools=[HelloTool()],
        system_prompt="You are a helpful assistant."
    )

    result = await agent.run("Hello there!")
    print(result)

asyncio.run(main())

More detailed examples and documentation are available on GitHub.