Migrate from Claude Agent SDK
Port a Claude Agent SDK integration to Autohand by mapping Claude's Python or TypeScript APIs to Autohand's CLI-backed SDK. The shape is familiar: create an agent session, send work, stream events, handle approvals, and read a final result.
What you are migrating
Claude Agent SDK exposes Claude Code as a library in Python and TypeScript. Autohand supports those same two migration paths, then extends the model to Go, Java, Swift, Rust, C++, C#, and Ruby for teams that do not want to wrap a Python or Node process just to embed a code agent.
| Existing Claude app | Use this Autohand path | Why |
|---|---|---|
TypeScript or JavaScript app using query() | @autohandai/agent-sdk with Agent and Run | Closest match for Node, Bun, CLIs, dashboards, and web backends. |
Python app using query() or ClaudeSDKClient | autohand-sdk with AutohandSDK | Closest match for async Python services, notebooks, internal tools, and automation scripts. |
| App that only used Claude SDK because there was no native SDK for your host language | Autohand Go, Java, Swift, Rust, C++, C#, or Ruby SDK | You can keep the agent in the same runtime as your product. |
Install the target SDK
Autohand SDKs call the local Autohand Code CLI over JSON-RPC. Install the SDK in your app, then make sure the CLI is installed and authenticated for the user or deployment image that will run the agent.
TypeScript
Python
API mapping
Start with the API surface your app uses today. Replace the Claude entry point first, then move options, event handling, permission behavior, and session behavior one by one.
| Claude Agent SDK | Autohand TypeScript | Autohand Python | How to port it |
|---|---|---|---|
query({ prompt, options }) | agent.run(prompt) or agent.send(prompt) | sdk.stream_prompt(prompt) | Use one-shot APIs for simple tasks and streaming APIs when your UI needs progress. |
ClaudeSDKClient | Long-lived Agent | async with AutohandSDK(...) | Keep the session object alive while the user is in the same workflow. |
ClaudeAgentOptions.cwd | Agent.create({ cwd }) | AutohandSDK(cwd="...") | Point Autohand at the same repository root. |
allowedTools / allowed_tools | permissionMode, permissions, canUseTool | permission_mode, permissions | Start with interactive permissions, observe real tool requests, then tighten the policy. |
permissionMode / permission_mode | permissionMode: "interactive" | permission_mode="interactive" | Autohand emits permission events your app can allow, deny, or scope. |
mcpServers / mcp_servers | mcpServers | MCP server config through SDK config | Keep command and args, then verify environment variables and cwd. |
AssistantMessage text blocks | message_update events and result.text | message_update events | Stream deltas for UI; use final result for logs, storage, or tests. |
Fresh query() session per call | agent.run() on a live Agent | One AutohandSDK context | Reuse the session object when follow-up prompts need prior context. |
TypeScript port
Replace Claude's async iterator with an Autohand run. The run object gives you both a stream and a final result, so your application can show progress and still assert on the completed output.
Before: Claude Agent SDK
After: Autohand Code Agent SDK
Python port
Claude's Python SDK uses `query()` for one-off runs and `ClaudeSDKClient` for explicit session control. Autohand's Python SDK uses one async client that can stream prompts, answer permission requests, and stay open for follow-up work.
Before: Claude Agent SDK
After: Autohand Code Agent SDK
Permissions and tools
Do not blindly copy a Claude `allowedTools` list as a permanent policy. First run Autohand in interactive mode and log `tool_start`, `tool_end`, and `permission_request`. Once you know the real tool names and command shapes, move to explicit allow/deny settings for production.
- Map Claude read/search tools to Autohand file and search events.
- Map Claude edit tools to Autohand file mutation events and permission requests.
- Map Claude Bash usage to Autohand command permissions and command allow patterns.
- Map Claude MCP servers to Autohand MCP server config, preserving command, args, cwd, and env.
Structured output
If your Claude integration parses a result message into JSON, make the output contract explicit during the migration. TypeScript can use `runJson()` directly; Python can stream the text and validate it with Pydantic.
TypeScript
Python
Native language upgrade
Claude's official Agent SDK path is Python and TypeScript. Autohand supports those, but the same agent model is also available in native packages for Go, Java, Swift, Rust, C++, C#, and Ruby. That matters when the code agent is part of an existing backend, desktop app, mobile-adjacent toolchain, Rails app, JVM service, or systems workflow.
Cutover checklist
- Pick the Autohand language package that matches the host app, not just the old Claude SDK language.
- Replace `query()` with `Agent`/`Run` in TypeScript or `AutohandSDK.stream_prompt()` in Python.
- Move `cwd`, instructions, MCP servers, and provider assumptions into Autohand configuration.
- Start with interactive permissions and record the actual tool sequence.
- Add tests for streaming text, permission pauses, denied actions, JSON parsing, aborts, and follow-up prompts.
Source context: Claude Agent SDK overview, Claude Python reference, and the Autohand TypeScript API reference.