Skip to content

Claude Code SDK Improvements

Overview

Collection of planned improvements to enhance the Claude Code SDK developer experience, focusing on better logging, conversation management, and utility functions.

Recent Developments

Subagent Configuration and Tool Permissions

  • October 15, 2025: MCP Tool Naming Resolution - Discovered critical configuration pattern for subagent tool permissions
  • MCP tools follow naming convention: mcp__[mcpName]__[toolName]
  • Server name in agent configuration must match dictionary key, not internal server name
  • Correct pattern: mcpServers: { "helpScout": helpScoutMcp } prevents tool permission failures

Subagent Architecture Patterns

  • October 15, 2025: Subagents delegated via tool calls from main agent with prompt parameters
  • Results pushed back into conversation as user messages
  • Questions remain about blocking vs non-blocking execution and parallel subagent capabilities
  • SDK documentation needs more comprehensive examples for complex subagent scenarios

Logging and Message Formatting

  • August 24, 2025: Log Formatting Tool Discovery - Community-developed solution identified for Claude Code output formatting
  • August 22, 2025: Identified need for better SDK output formatting
  • Current approach dumps raw JSON, making debugging difficult
  • Planning reusable Bun package for formatted Claude Code SDK logs
  • Opportunity to gain NPM publishing experience while solving real problem

Conversation Persistence Investigation

  • SDK supports conversation continuation via option.continue: true
  • Resume functionality available with option.resume: {conversation id}
  • Claude Code maintains conversation state in ~/.claude.json
  • Need abstraction layer to productize this feature

Planned Improvements

1. Enhanced Logging Package

Objective: Create readable, formatted output from Claude Code SDK calls

Current Issues: - Raw JSON dumps are hard to parse visually - No structured formatting for debugging - Poor developer experience during development

Planned Solution: - Reusable Bun package for log formatting - Pretty-printed, structured output - Configurable verbosity levels - Integration examples for common use cases - Community Tool Integration: Evaluate existing community-developed formatting solutions - Potential collaboration with existing tools rather than building from scratch

2. Conversation Management Abstraction

Objective: Simplify conversation persistence for production applications

Current State: - Basic SDK support exists but requires manual management - State stored in user-specific .claude.json file - No built-in abstraction for application-level persistence

Planned Features: - Abstract conversation state management - Application-level persistence options - Session management utilities - Multi-user conversation handling

3. Subagent Configuration Utilities

Objective: Simplify MCP tool configuration and subagent setup

Current Issues: - Complex naming conventions for MCP tools - Tool permission configuration pitfalls - Limited examples for subagent patterns - Manual server name management required

Planned Solution: - Utility functions for MCP server configuration - Type-safe tool name generation helpers - Subagent configuration templates - Best practices documentation and examples

4. NPM Package Publishing Strategy

Goal: Distribute internal utilities that could benefit broader community

Candidates for Publication: - Claude Code SDK logging utilities - Message formatting helpers - Conversation persistence abstractions - File selector utilities (already identified) - MCP configuration utilities (new addition)

Technical Insights

MCP Configuration Patterns

Critical Discovery: Server naming in agent configuration affects tool accessibility

Problem: When defining MCP tools for subagents, tool permissions fail if server names don't match dictionary keys

Solution Pattern:

// Define MCP server with internal name
const mcpName = "helpScout";
const helpScoutMcp = createSdkMcpServer({ name: mcpName, version: "1.0", tools });

// Utility for tool name formatting
export const CoreMcpToolNames = {
    applyTags: formatMcpToolName(mcpName, applyTagsTool.name), // becomes "mcp__helpScout__applyTags"
};

// INCORRECT - uses variable name as key
mcpServers: { helpScoutMcp }  // Server becomes "helpScoutMcp", breaks tool access

// CORRECT - matches internal server name
mcpServers: { "helpScout": helpScoutMcp }  // Server remains "helpScout", tools work

// Alternative pattern for consistency
const mcpServers: Record<string, McpServerConfig> = {};
mcpServers[helpScoutMcp.name] = helpScoutMcp;

Subagent Architecture Behaviors

  • Subagents inherit all tools from parent by default when tools array is empty
  • Explicit tool allowlisting via tools: [toolName] restricts permissions but requires correct naming
  • Tool calls return results as user messages in conversation flow
  • Uncertainty around parallel execution capabilities and blocking behavior

Current SDK Limitations

  • Limited logging and debugging capabilities
  • Manual conversation state management required
  • Raw output format not developer-friendly
  • Missing utility functions for common patterns
  • Documentation gaps around advanced subagent patterns
  • Tool permission configuration not well-documented

AI SDK Comparison

  • Team wishes AI SDK had wrapper for Claude Code SDK
  • "It's probably just a matter of time" before official integration
  • Current SDK has layered complexity that could benefit from simplification

Implementation Notes

Memory Management Patterns

  • Preference for HTTP-based local MCP servers
  • Shared program memory between MCP server and agent code
  • Useful for maintaining state across interactions
  • Enables easy test state extraction for E2E testing

Publishing Strategy

  • Start with internal utilities that solve real problems
  • Use as learning experience for NPM publishing process
  • Consider making some MCP servers independent packages
  • Build experience before tackling larger abstractions

Resources & References

Current Tools

  • AI SDK v5 - Potential integration target
  • Bun package ecosystem - Publishing platform
  • NPM registry - Distribution mechanism

Community Impact

Developer Experience Goals

  • Reduce barrier to entry for Claude Code SDK adoption
  • Provide better debugging and development tools
  • Create reusable patterns for common use cases
  • Share internal utilities that could benefit others

Knowledge Sharing

  • Document common patterns and solutions
  • Provide examples and best practices
  • Build community around Claude Code development
  • Contribute to broader AI development ecosystem