Migrate from claude-code-sdk to claude-agent-sdk

[michaelansel]

Overview

The claude-code-sdk package has been officially deprecated and replaced with claude-agent-sdk. This issue tracks the migration to the new SDK.

Status: claude-code-sdk v0.0.25 (Sept 2025) - Deprecated, no longer maintained
Target: claude-agent-sdk v0.1.6+ (Oct 2025) - Actively maintained

Priority: Medium - Schedule within 1-2 months
Effort: 1-2 hours
Risk: Low (straightforward refactoring with good test coverage)

---

Why Migrate?

Value Proposition

• ✅ Security & Stability: No future security patches or bug fixes for old SDK
• ✅ Future-proofing: Avoid breaking changes when old SDK eventually sunsets
• ✅ New Features: SDK MCP servers (in-process tools), hooks system, session forking
• ✅ Active Support: Ongoing development, documentation, and community support
• ✅ Low Effort: Only 4 files affected with comprehensive test coverage

When to Do This

Do sooner if:

• Actively developing new features anyway
• Want to use new MCP servers or hooks features
• Encounter any bugs/issues with old SDK

Do later if:

• Have critical bugs/features to address first
• Bot is stable and low-touch
• Time-constrained on higher priorities

---

Impact Analysis

Files Affected: 4 files

1. pyproject.toml - Dependency declaration
2. src/claude/sdk_integration.py - Main integration (2 imports, class usage)
3. tests/unit/test_claude/test_sdk_integration.py - Unit tests (4 imports)
4. docs/todo-5-claude-integration.md - Documentation

Breaking Changes:

Change	Old	New
Package name	claude-code-sdk	claude-agent-sdk
Import path	claude_code_sdk	claude_agent_sdk
Options class	ClaudeCodeOptions	ClaudeAgentOptions
System prompt	Auto-applied	Must specify explicitly
Settings sources	Auto-enabled	Disabled by default

---

Migration Steps

Phase 1: Dependency Update (10 min)

1.1 Update pyproject.toml

[tool.poetry.dependencies]
- claude-code-sdk = "^0.0.11"
+ claude-agent-sdk = "^0.1.0"

1.2 Install new SDK

poetry remove claude-code-sdk
poetry add claude-agent-sdk
poetry lock
poetry install

---

Phase 2: Code Updates (30 min)

2.1 Update src/claude/sdk_integration.py

Lines 18-19 and 27-34:

- from claude_code_sdk import (
-     ClaudeCodeOptions,
+ from claude_agent_sdk import (
+     ClaudeAgentOptions,
      ClaudeSDKError,
      CLIConnectionError,
      CLINotFoundError,
      Message,
      ProcessError,
      query,
  )
- from claude_code_sdk.types import (
+ from claude_agent_sdk.types import (
      AssistantMessage,
      ResultMessage,
      TextBlock,
      ToolResultBlock,
      ToolUseBlock,
      UserMessage,
  )

Line 174:

- options = ClaudeCodeOptions(
+ options = ClaudeAgentOptions(
      max_turns=self.config.claude_max_turns,
      cwd=str(working_directory),
      allowed_tools=self.config.claude_allowed_tools,
+     # NEW: Explicitly specify system prompt (default removed)
+     system_prompt={"type": "preset", "preset": "claude_code"},
+     # NEW: Enable settings sources if needed (disabled by default)
+     # setting_sources=["user", "project", "local"],
  )

2.2 Update tests/unit/test_claude/test_sdk_integration.py

- from claude_code_sdk import ClaudeCodeOptions
+ from claude_agent_sdk import ClaudeAgentOptions

Update imports in test methods (lines 87, 119, 171):

- from claude_code_sdk.types import AssistantMessage, ResultMessage
+ from claude_agent_sdk.types import AssistantMessage, ResultMessage

2.3 Update docs/todo-5-claude-integration.md

Update all code examples with new package name.

---

Phase 3: Configuration Updates (15 min)

3.1 System Prompt Decision

The new SDK removes default system prompts. Choose one:

Option A: Use Claude Code preset (recommended)

system_prompt={"type": "preset", "preset": "claude_code"}

Option B: Custom system prompt

system_prompt="Your custom system prompt here"

3.2 Settings Sources Review

Filesystem settings (CLAUDE.md, settings.json) are disabled by default.

Recommendation: Keep disabled for production deployments (better security/predictability).

If needed for project-specific settings:

setting_sources=["user", "project", "local"]

---

Phase 4: Testing (30-60 min)

4.1 Run unit tests

make test
# or
poetry run pytest tests/unit/test_claude/test_sdk_integration.py -v

4.2 Integration testing checklist

• Test basic query execution
• Test streaming callbacks
• Test timeout handling
• Test session management
• Test error handling (CLINotFoundError, ProcessError, etc.)
• Test with/without API key (CLI auth fallback)
• Test tool execution monitoring
• Test cost tracking

4.3 End-to-end testing

make run-debug

# Test via Telegram:
# 1. Send a simple query
# 2. Test /continue command
# 3. Test /status command
# 4. Verify cost tracking
# 5. Test error scenarios

---

Phase 5: Deployment (15 min)

5.1 Pre-deployment checks

• All tests pass (make test)
• Code linting passes (make lint)
• Dependencies locked (poetry.lock updated)
• Documentation updated

5.2 Deployment

# On deployment server
poetry install --no-dev
# Restart bot service

5.3 Post-deployment monitoring

• Monitor logs for first 24-48 hours
• Verify cost tracking accuracy
• Check for any error patterns

5.4 Rollback plan

# If issues arise:
git revert <migration-commit>
poetry install
# Restart bot service

---

Pre-Migration Checklist

• Review current SDK behavior and responses
• Backup current codebase (git tag pre-sdk-migration)
• Verify test coverage for SDK integration
• Document any custom configurations
• Plan maintenance window (if needed)

---

Post-Migration Checklist

• All tests pass
• Code linting passes
• Dependencies locked
• Documentation updated
• Deployment tested
• Monitor production logs
• Verify cost tracking
• Update README if needed

---

Additional Resources

• Official Migration Guide: https://code.claude.com/docs/en/sdk/migration-guide
• claude-agent-sdk PyPI: https://pypi.org/project/claude-agent-sdk/
• Anthropic Blog: https://www.anthropic.com/engineering/building-agents-with-the-claude-agent-sdk
• API Documentation: https://docs.claude.com/en/api

---

Questions to Resolve

• System Prompt: Use Claude Code preset or define custom?
• Settings Sources: Need CLAUDE.md/settings.json support?
• Deployment: Current deployment method confirmation?
• Timeline: Preferred migration window?

---

Estimated Timeline

Phase	Duration
Dependency update	10 min
Code updates	30 min
Configuration review	15 min
Testing	30-60 min
Deployment	15 min
Total	1.5-2 hours

---

Notes

• Migration can be done incrementally (test in dev first)
• No downtime required if properly tested
• Old SDK will continue working for now (no sunset date announced)
• New SDK enables future features (MCP servers, hooks, subagents)

[michaelansel]

whoops, I meant to create this on my fork, not here. But since it's here, I'll leave it and anyone who wants it can have it.