claude_swarm 0.1.4 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4597e6fdc67837e39ae1c175cc9dded454460ec00488d92aa81cab928737b4a
-  data.tar.gz: 46790b958dc4916a3df066ae7384e753c84c6c4cc624ac62754cab646f2c9102
+  metadata.gz: 32206b2e4ec4228e8d9c2450447f0508a2c58378d37c80ce24d327a54653ee05
+  data.tar.gz: c11bf2d8042b73de10ee2f40c01e977d8bae0a8bd74e23b74fc29216735396c3
 SHA512:
-  metadata.gz: f876006a8368881b252e675fab2b2999ae5a79574caff9db081ea7ea72402ce172524d7c6a2fe9c4b967502971a1cab83895dfd1f339592a516c58298450426a
-  data.tar.gz: b55120d481b8605e11a7024f1d6626f5c1fecca18627b6247e4b517c16e29d762166408a1753b1fc1b845c80f820f9701ce30ef2b0edb7e8a58da1b3635d0cc4
+  metadata.gz: 5e639606be661128f4c23411f6e9c4164cf9b212ce37e6f99178ba33e4d67a5eb0995b25c1dbe885fff0c20230ea12e347c7b04c7b3bef8b4313353bce6cb948
+  data.tar.gz: 8d51962bb83f7268510b44a1aff1b13c5f5260c008b8bb26b41d971d0fbdd816c76a9221c275c028851c7ccc825c2aeee7b0d7d0e311f50485119693b3b5791a

data/.rubocop.yml

@@ -59,4 +59,7 @@ Metrics/ModuleLength:
   Enabled: false
 
 Minitest/MultipleAssertions:
+  Enabled: false
+
+Metrics/ParameterLists:
   Enabled: false

data/CHANGELOG.md

@@ -1,3 +1,19 @@
+## [0.1.6]
+- Refactor: move tools out of the ClaudeMcpServer class
+- Move logging into code executor and save instance interaction streams to session.log
+- Human readable logs with thoughts and tool calls
+
+## [0.1.5]
+
+### Changed
+- **Improved command execution**: Switched from `exec` to `Dir.chdir` + `system` for better process handling and proper directory context
+- Command arguments are now passed as an array instead of a shell string, eliminating the need for manual shell escaping
+- Added default prompt behavior: when no `-p` flag is provided, a default prompt is added to help Claude understand it should start working
+
+### Internal
+- Updated test suite to match new command execution implementation
+- Removed shellwords escaping tests as they're no longer needed with array-based command execution
+
 ## [0.1.4]
 
 ### Added

data/README.md

@@ -52,7 +52,7 @@ swarm:
     frontend:
       description: "Frontend specialist handling UI and user experience"
       directory: ./frontend
-      model: sonnet
+      model: opus
       tools:
         - Edit
         - Write
@@ -60,7 +60,7 @@ swarm:
     backend:
       description: "Backend developer managing APIs and data layer"
       directory: ./backend  
-      model: sonnet
+      model: opus
       tools:
         - Edit
         - Write
@@ -111,14 +111,14 @@ swarm:
     react_dev:
       description: "React developer specializing in components and state management"
       directory: ./web-frontend/src
-      model: sonnet
+      model: opus
       prompt: "You specialize in React components and state management"
       tools: [Edit, Write, "Bash(npm:*)"]
     
     css_expert:
       description: "CSS specialist handling styling and responsive design"
       directory: ./web-frontend/styles
-      model: sonnet
+      model: opus
       prompt: "You handle all CSS and styling concerns"
       tools: [Edit, Write, Read]
     
@@ -133,21 +133,21 @@ swarm:
     api_dev:
       description: "API developer building REST endpoints"
       directory: ./api-server/src
-      model: sonnet
+      model: opus
       prompt: "You develop REST API endpoints"
       tools: [Edit, Write, Bash]
     
     database_expert:
       description: "Database specialist managing schemas and migrations"
       directory: ./api-server/db
-      model: sonnet
+      model: opus
       prompt: "You handle database schema and migrations"
       tools: [Edit, Write, "Bash(psql:*, migrate:*)"]
     
     mobile_lead:
       description: "Mobile team lead coordinating cross-platform development"
       directory: ./mobile-app
-      model: sonnet
+      model: opus
       connections: [ios_dev, android_dev]
       prompt: "You coordinate mobile development across platforms"
       tools: [Read, Edit]
@@ -155,21 +155,21 @@ swarm:
     ios_dev:
       description: "iOS developer building native Apple applications"
       directory: ./mobile-app/ios
-      model: sonnet
+      model: opus
       prompt: "You develop the iOS application"
       tools: [Edit, Write, "Bash(xcodebuild:*, pod:*)"]
     
     android_dev:
       description: "Android developer creating native Android apps"
       directory: ./mobile-app/android
-      model: sonnet
+      model: opus
       prompt: "You develop the Android application"
       tools: [Edit, Write, "Bash(gradle:*, adb:*)"]
     
     devops:
       description: "DevOps engineer managing CI/CD and infrastructure"
       directory: ./infrastructure
-      model: sonnet
+      model: opus
       prompt: "You handle CI/CD and infrastructure"
       tools: [Read, Edit, "Bash(docker:*, kubectl:*)"]
 ```
@@ -305,7 +305,7 @@ swarm:
     frontend:
       description: "Frontend developer specializing in React and TypeScript"
       directory: ./frontend
-      model: sonnet
+      model: opus
       connections: [architect]
       prompt: "You specialize in React, TypeScript, and modern frontend development"
       tools:
@@ -316,7 +316,7 @@ swarm:
     backend:
       description: "Backend developer building APIs and services"
       directory: ./backend
-      model: sonnet
+      model: opus
       connections: [architect, database]
       tools:
         - Edit
@@ -334,7 +334,7 @@ swarm:
     devops:
       description: "DevOps engineer handling deployment and infrastructure"
       directory: .
-      model: sonnet
+      model: opus
       connections: [architect]
       tools:
         - Read
@@ -367,7 +367,7 @@ swarm:
     data_analyst:
       description: "Data analyst processing research data and statistics"
       directory: ~/research/data
-      model: sonnet
+      model: opus
       tools:
         - Read
         - Write
@@ -381,7 +381,7 @@ swarm:
     writer:
       description: "Technical writer preparing research documentation"
       directory: ~/research/papers
-      model: sonnet
+      model: opus
       tools:
         - Edit
         - Write

data/claude-swarm.yml

@@ -6,7 +6,7 @@ swarm:
     lead_developer:
       description: "Lead developer coordinating the team and making architectural decisions"
       directory: .
-      model: sonnet
+      model: opus
       prompt: "You are the lead developer coordinating the team"
       tools: [Read, Edit, Bash, Write]
       connections: [frontend_dev]
@@ -16,6 +16,6 @@ swarm:
     frontend_dev:
       description: "Frontend developer specializing in React and modern web technologies"
       directory: .
-      model: sonnet
+      model: opus
       prompt: "You specialize in frontend development with React, TypeScript, and modern web technologies"
       tools: [Read, Edit, Write, "Bash(npm:*)", "Bash(yarn:*)", "Bash(pnpm:*)"]

data/lib/claude_swarm/claude_code_executor.rb

@@ -2,43 +2,85 @@
 
 require "json"
 require "open3"
+require "logger"
+require "fileutils"
 
 module ClaudeSwarm
   class ClaudeCodeExecutor
-    attr_reader :session_id, :last_response, :working_directory
+    SWARM_DIR = ".claude-swarm"
+    SESSIONS_DIR = "sessions"
 
-    def initialize(working_directory: Dir.pwd, model: nil, mcp_config: nil, vibe: false)
+    attr_reader :session_id, :last_response, :working_directory, :logger, :session_timestamp
+
+    def initialize(working_directory: Dir.pwd, model: nil, mcp_config: nil, vibe: false, instance_name: nil, calling_instance: nil)
       @working_directory = working_directory
       @model = model
       @mcp_config = mcp_config
       @vibe = vibe
       @session_id = nil
       @last_response = nil
+      @instance_name = instance_name
+      @calling_instance = calling_instance
+
+      # Setup logging
+      setup_logging
     end
 
     def execute(prompt, options = {})
-      cmd_array = build_command_array(prompt, options)
-
-      stdout, stderr, status = Open3.capture3(*cmd_array, chdir: @working_directory)
-
-      raise ExecutionError, "Claude Code execution failed: #{stderr}" unless status.success?
+      # Log the request
+      log_request(prompt)
 
-      begin
-        response = JSON.parse(stdout)
-        @last_response = response
-
-        # Extract and store session ID from the response
-        @session_id = response["session_id"]
+      cmd_array = build_command_array(prompt, options)
 
-        response
-      rescue JSON::ParserError => e
-        raise ParseError, "Failed to parse JSON response: #{e.message}\nOutput: #{stdout}"
+      # Variables to collect output
+      stderr_output = []
+      result_response = nil
+
+      # Execute command with streaming
+      Open3.popen3(*cmd_array, chdir: @working_directory) do |stdin, stdout, stderr, wait_thread|
+        stdin.close
+
+        # Read stderr in a separate thread
+        stderr_thread = Thread.new do
+          stderr.each_line { |line| stderr_output << line }
+        end
+
+        # Process stdout line by line
+        stdout.each_line do |line|
+          json_data = JSON.parse(line.strip)
+
+          # Log each JSON event
+          log_streaming_event(json_data)
+
+          # Capture session_id from system init
+          @session_id = json_data["session_id"] if json_data["type"] == "system" && json_data["subtype"] == "init"
+
+          # Capture the final result
+          result_response = json_data if json_data["type"] == "result"
+        rescue JSON::ParserError => e
+          @logger.warn("Failed to parse JSON line: #{line.strip} - #{e.message}")
+        end
+
+        # Wait for stderr thread to finish
+        stderr_thread.join
+
+        # Check exit status
+        exit_status = wait_thread.value
+        unless exit_status.success?
+          error_msg = stderr_output.join
+          @logger.error("Execution error for #{@instance_name}: #{error_msg}")
+          raise ExecutionError, "Claude Code execution failed: #{error_msg}"
+        end
       end
-    end
 
-    def execute_text(prompt, options = {})
-      response = execute(prompt, options)
-      response["result"] || ""
+      # Ensure we got a result
+      raise ParseError, "No result found in stream output" unless result_response
+
+      result_response
+    rescue StandardError => e
+      @logger.error("Unexpected error for #{@instance_name}: #{e.class} - #{e.message}")
+      @logger.error("Backtrace: #{e.backtrace.join("\n")}")
+      raise
     end
 
     def reset_session
@@ -52,12 +94,90 @@ module ClaudeSwarm
 
     private
 
+    def setup_logging
+      # Use environment variable for session timestamp if available (set by orchestrator)
+      # Otherwise create a new timestamp
+      @session_timestamp = ENV["CLAUDE_SWARM_SESSION_TIMESTAMP"] || Time.now.strftime("%Y%m%d_%H%M%S")
+
+      # Ensure the session directory exists
+      session_dir = File.join(Dir.pwd, SWARM_DIR, SESSIONS_DIR, @session_timestamp)
+      FileUtils.mkdir_p(session_dir)
+
+      # Create logger with session.log filename
+      log_filename = "session.log"
+      log_path = File.join(session_dir, log_filename)
+      @logger = Logger.new(log_path)
+      @logger.level = Logger::INFO
+
+      # Custom formatter for better readability
+      @logger.formatter = proc do |severity, datetime, _progname, msg|
+        "[#{datetime.strftime("%Y-%m-%d %H:%M:%S.%L")}] [#{severity}] #{msg}\n"
+      end
+
+      @logger.info("Started Claude Code executor for instance: #{@instance_name}") if @instance_name
+    end
+
+    def log_request(prompt)
+      @logger.info("#{@calling_instance} -> #{@instance_name}: \n---\n#{prompt}\n---")
+    end
+
+    def log_response(response)
+      @logger.info(
+        "($#{response["total_cost"]} - #{response["duration_ms"]}ms) #{@instance_name} -> #{@calling_instance}: \n---\n#{response["result"]}\n---"
+      )
+    end
+
+    def log_streaming_event(event)
+      return log_system_message(event) if event["type"] == "system"
+
+      # Add specific details based on event type
+      case event["type"]
+      when "assistant"
+        log_assistant_message(event["message"])
+      when "user"
+        log_user_message(event["message"]["content"])
+      when "result"
+        log_response(event)
+      end
+    end
+
+    def log_system_message(event)
+      @logger.debug("SYSTEM: #{JSON.pretty_generate(event)}")
+    end
+
+    def log_assistant_message(msg)
+      return if msg["stop_reason"] == "end_turn" # that means it is not a thought but the final answer
+
+      content = msg["content"]
+      @logger.debug("ASSISTANT: #{JSON.pretty_generate(content)}")
+      tool_calls = content.select { |c| c["type"] == "tool_use" }
+      tool_calls.each do |tool_call|
+        arguments = tool_call["input"].to_json
+        arguments = "#{arguments[0..300]} ...}" if arguments.length > 300
+
+        @logger.info(
+          "Tool call from #{@instance_name} -> Tool: #{tool_call["name"]}, ID: #{tool_call["id"]}, Arguments: #{arguments}"
+        )
+      end
+
+      text = content.select { |c| c["type"] == "text" }
+      text.each do |t|
+        @logger.info("#{@instance_name} is thinking:\n---\n#{t["text"]}\n---")
+      end
+    end
+
+    def log_user_message(content)
+      @logger.debug("USER: #{JSON.pretty_generate(content)}")
+    end
+
     def build_command_array(prompt, options)
       cmd_array = ["claude"]
 
       # Add model if specified
       cmd_array += ["--model", @model]
 
+      cmd_array << "--verbose"
+
       # Add MCP config if specified
       cmd_array += ["--mcp-config", @mcp_config] if @mcp_config
 
@@ -65,7 +185,7 @@ module ClaudeSwarm
       cmd_array += ["--resume", @session_id] if @session_id && !options[:new_session]
 
       # Always use JSON output format for structured responses
-      cmd_array += ["--output-format", "json"]
+      cmd_array += ["--output-format", "stream-json"]
 
       # Add non-interactive mode with prompt
       cmd_array += ["--print", "-p", prompt]

data/lib/claude_swarm/claude_mcp_server.rb

@@ -2,15 +2,13 @@
 
 require "fast_mcp"
 require "json"
-require "fileutils"
-require "logger"
 require_relative "claude_code_executor"
+require_relative "task_tool"
+require_relative "session_info_tool"
+require_relative "reset_session_tool"
 
 module ClaudeSwarm
   class ClaudeMcpServer
-    SWARM_DIR = ".claude-swarm"
-    SESSIONS_DIR = "sessions"
-
     # Class variables to share state with tool classes
     class << self
       attr_accessor :executor, :instance_config, :logger, :session_timestamp, :calling_instance
@@ -23,46 +21,19 @@ module ClaudeSwarm
         working_directory: instance_config[:directory],
         model: instance_config[:model],
         mcp_config: instance_config[:mcp_config_path],
-        vibe: instance_config[:vibe]
+        vibe: instance_config[:vibe],
+        instance_name: instance_config[:name],
+        calling_instance: calling_instance
       )
 
-      # Setup logging
-      setup_logging
-
       # Set class variables so tools can access them
       self.class.executor = @executor
       self.class.instance_config = @instance_config
-      self.class.logger = @logger
+      self.class.logger = @executor.logger
+      self.class.session_timestamp = @executor.session_timestamp
       self.class.calling_instance = @calling_instance
     end
 
-    private
-
-    def setup_logging
-      # Use environment variable for session timestamp if available (set by orchestrator)
-      # Otherwise create a new timestamp
-      self.class.session_timestamp ||= ENV["CLAUDE_SWARM_SESSION_TIMESTAMP"] || Time.now.strftime("%Y%m%d_%H%M%S")
-
-      # Ensure the session directory exists
-      session_dir = File.join(Dir.pwd, SWARM_DIR, SESSIONS_DIR, self.class.session_timestamp)
-      FileUtils.mkdir_p(session_dir)
-
-      # Create logger with session.log filename
-      log_filename = "session.log"
-      log_path = File.join(session_dir, log_filename)
-      @logger = Logger.new(log_path)
-      @logger.level = Logger::INFO
-
-      # Custom formatter for better readability
-      @logger.formatter = proc do |severity, datetime, _progname, msg|
-        "[#{datetime.strftime("%Y-%m-%d %H:%M:%S.%L")}] [#{severity}] #{msg}\n"
-      end
-
-      @logger.info("Started MCP server for instance: #{@instance_config[:name]}")
-    end
-
-    public
-
     def start
       server = FastMcp::Server.new(
         name: @instance_config[:name],
@@ -84,120 +55,5 @@ module ClaudeSwarm
       # Start the stdio server
       server.start
     end
-
-    class TaskTool < FastMcp::Tool
-      tool_name "task"
-      description "Execute a task using Claude Code"
-
-      arguments do
-        required(:prompt).filled(:string).description("The task or question for the agent")
-        optional(:new_session).filled(:bool).description("Start a new session (default: false)")
-        optional(:system_prompt).filled(:string).description("Override the system prompt for this request")
-      end
-
-      def call(prompt:, new_session: false, system_prompt: nil)
-        executor = ClaudeMcpServer.executor
-        instance_config = ClaudeMcpServer.instance_config
-        logger = ClaudeMcpServer.logger
-
-        options = {
-          new_session: new_session,
-          system_prompt: system_prompt || instance_config[:prompt]
-        }
-
-        # Add allowed tools from instance config
-        options[:allowed_tools] = instance_config[:tools] if instance_config[:tools]&.any?
-
-        begin
-          # Log the request
-          log_entry = {
-            timestamp: Time.now.utc.iso8601,
-            from_instance: ClaudeMcpServer.calling_instance, # The instance making the request
-            to_instance: instance_config[:name], # This instance is receiving the request
-            model: instance_config[:model],
-            working_directory: instance_config[:directory],
-            session_id: executor.session_id,
-            request: {
-              prompt: prompt,
-              new_session: new_session,
-              system_prompt: options[:system_prompt],
-              allowed_tools: options[:allowed_tools]
-            }
-          }
-
-          logger.info("REQUEST: #{JSON.pretty_generate(log_entry)}")
-
-          response = executor.execute(prompt, options)
-
-          # Log the response
-          response_entry = {
-            timestamp: Time.now.utc.iso8601,
-            from_instance: instance_config[:name], # This instance is sending the response
-            to_instance: ClaudeMcpServer.calling_instance, # The instance that made the request receives the response
-            session_id: executor.session_id, # Update with new session ID if changed
-            response: {
-              result: response["result"],
-              cost_usd: response["cost_usd"],
-              duration_ms: response["duration_ms"],
-              is_error: response["is_error"],
-              total_cost: response["total_cost"]
-            }
-          }
-
-          logger.info("RESPONSE: #{JSON.pretty_generate(response_entry)}")
-
-          # Return just the result text as expected by MCP
-          response["result"]
-        rescue ClaudeCodeExecutor::ExecutionError => e
-          logger.error("Execution error for #{instance_config[:name]}: #{e.message}")
-          raise StandardError, "Execution failed: #{e.message}"
-        rescue ClaudeCodeExecutor::ParseError => e
-          logger.error("Parse error for #{instance_config[:name]}: #{e.message}")
-          raise StandardError, "Parse error: #{e.message}"
-        rescue StandardError => e
-          logger.error("Unexpected error for #{instance_config[:name]}: #{e.class} - #{e.message}")
-          logger.error("Backtrace: #{e.backtrace.join("\n")}")
-          raise StandardError, "Unexpected error: #{e.message}"
-        end
-      end
-    end
-
-    class SessionInfoTool < FastMcp::Tool
-      tool_name "session_info"
-      description "Get information about the current Claude session for this agent"
-
-      arguments do
-        # No arguments needed
-      end
-
-      def call
-        executor = ClaudeMcpServer.executor
-
-        {
-          has_session: executor.has_session?,
-          session_id: executor.session_id,
-          working_directory: executor.working_directory
-        }
-      end
-    end
-
-    class ResetSessionTool < FastMcp::Tool
-      tool_name "reset_session"
-      description "Reset the Claude session for this agent, starting fresh on the next task"
-
-      arguments do
-        # No arguments needed
-      end
-
-      def call
-        executor = ClaudeMcpServer.executor
-        executor.reset_session
-
-        {
-          success: true,
-          message: "Session has been reset"
-        }
-      end
-    end
   end
 end

data/lib/claude_swarm/orchestrator.rb

@@ -51,32 +51,43 @@ module ClaudeSwarm
       end
 
       # Execute the main instance - this will cascade to other instances via MCP
-      exec(command)
+      Dir.chdir(main_instance[:directory]) do
+        system(*command)
+      end
     end
 
     private
 
     def build_main_command(instance)
-      parts = []
-      parts << "cd #{Shellwords.escape(instance[:directory])} &&"
-      parts << "claude"
-      parts << "--model #{instance[:model]}"
+      parts = [
+        "claude",
+        "--model",
+        instance[:model]
+      ]
 
       if @vibe
         parts << "--dangerously-skip-permissions"
       elsif instance[:tools].any?
         tools_str = instance[:tools].join(",")
-        parts << "--allowedTools '#{tools_str}'"
+        parts << "--allowedTools"
+        parts << tools_str
       end
 
-      parts << "--append-system-prompt #{Shellwords.escape(instance[:prompt])}" if instance[:prompt]
+      if instance[:prompt]
+        parts << "--append-system-prompt"
+        parts << instance[:prompt]
+      end
 
       mcp_config_path = @generator.mcp_config_path(@config.main_instance)
-      parts << "--mcp-config #{mcp_config_path}"
+      parts << "--mcp-config"
+      parts << mcp_config_path
 
-      parts << "-p #{Shellwords.escape(@prompt)}" if @prompt
-
-      parts.join(" ")
+      if @prompt
+        parts << "-p"
+        parts << @prompt
+      else
+        parts << "#{instance[:prompt]}\n\nNow just say 'I am ready to start'"
+      end
     end
   end
 end

data/lib/claude_swarm/reset_session_tool.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module ClaudeSwarm
+  class ResetSessionTool < FastMcp::Tool
+    tool_name "reset_session"
+    description "Reset the Claude session for this agent, starting fresh on the next task"
+
+    arguments do
+      # No arguments needed
+    end
+
+    def call
+      executor = ClaudeMcpServer.executor
+      executor.reset_session
+
+      {
+        success: true,
+        message: "Session has been reset"
+      }
+    end
+  end
+end

data/lib/claude_swarm/session_info_tool.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module ClaudeSwarm
+  class SessionInfoTool < FastMcp::Tool
+    tool_name "session_info"
+    description "Get information about the current Claude session for this agent"
+
+    arguments do
+      # No arguments needed
+    end
+
+    def call
+      executor = ClaudeMcpServer.executor
+
+      {
+        has_session: executor.has_session?,
+        session_id: executor.session_id,
+        working_directory: executor.working_directory
+      }
+    end
+  end
+end

data/lib/claude_swarm/task_tool.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module ClaudeSwarm
+  class TaskTool < FastMcp::Tool
+    tool_name "task"
+    description "Execute a task using Claude Code"
+
+    arguments do
+      required(:prompt).filled(:string).description("The task or question for the agent")
+      optional(:new_session).filled(:bool).description("Start a new session (default: false)")
+      optional(:system_prompt).filled(:string).description("Override the system prompt for this request")
+    end
+
+    def call(prompt:, new_session: false, system_prompt: nil)
+      executor = ClaudeMcpServer.executor
+      instance_config = ClaudeMcpServer.instance_config
+
+      options = {
+        new_session: new_session,
+        system_prompt: system_prompt || instance_config[:prompt]
+      }
+
+      # Add allowed tools from instance config
+      options[:allowed_tools] = instance_config[:tools] if instance_config[:tools]&.any?
+
+      response = executor.execute(prompt, options)
+
+      # Return just the result text as expected by MCP
+      response["result"]
+    end
+  end
+end

data/lib/claude_swarm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ClaudeSwarm
-  VERSION = "0.1.4"
+  VERSION = "0.1.6"
 end

data/sdk-docs.md

@@ -0,0 +1,426 @@
+# SDK
+
+> Programmatically integrate Claude Code into your applications using the SDK.
+
+The Claude Code SDK allows developers to programmatically integrate Claude Code into their applications. It enables running Claude Code as a subprocess, providing a way to build AI-powered coding assistants and tools that leverage Claude's capabilities.
+
+The SDK currently support command line usage. TypeScript and Python SDKs are coming soon.
+
+## Authentication
+
+To use the Claude Code SDK, we recommend creating a dedicated API key:
+
+1. Create an Anthropic API key in the [Anthropic Console](https://console.anthropic.com/)
+2. Then, set the `ANTHROPIC_API_KEY` environment variable. We recommend storing this key securely (eg. using a Github [secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions))
+
+## Basic SDK usage
+
+The Claude Code SDK allows you to use Claude Code in non-interactive mode from your applications. Here's a basic example:
+
+```bash
+# Run a single prompt and exit (print mode)
+$ claude -p "Write a function to calculate Fibonacci numbers"
+
+# Using a pipe to provide stdin
+$ echo "Explain this code" | claude -p
+
+# Output in JSON format with metadata
+$ claude -p "Generate a hello world function" --output-format json
+
+# Stream JSON output as it arrives
+$ claude -p "Build a React component" --output-format stream-json
+```
+
+## Advanced usage
+
+### Multi-turn conversations
+
+For multi-turn conversations, you can resume conversations or continue from the most recent session:
+
+```bash
+# Continue the most recent conversation
+$ claude --continue
+
+# Continue and provide a new prompt
+$ claude --continue "Now refactor this for better performance"
+
+# Resume a specific conversation by session ID
+$ claude --resume 550e8400-e29b-41d4-a716-446655440000
+
+# Resume in print mode (non-interactive)
+$ claude -p --resume 550e8400-e29b-41d4-a716-446655440000 "Update the tests"
+
+# Continue in print mode (non-interactive)
+$ claude -p --continue "Add error handling"
+```
+
+### Custom system prompts
+
+You can provide custom system prompts to guide Claude's behavior:
+
+```bash
+# Override system prompt (only works with --print)
+$ claude -p "Build a REST API" --system-prompt "You are a senior backend engineer. Focus on security, performance, and maintainability."
+
+# System prompt with specific requirements
+$ claude -p "Create a database schema" --system-prompt "You are a database architect. Use PostgreSQL best practices and include proper indexing."
+```
+
+You can also append instructions to the default system prompt:
+
+```bash
+# Append system prompt (only works with --print)
+$ claude -p "Build a REST API" --append-system-prompt "After writing code, be sure to code review yourself."
+```
+
+### MCP Configuration
+
+The Model Context Protocol (MCP) allows you to extend Claude Code with additional tools and resources from external servers. Using the `--mcp-config` flag, you can load MCP servers that provide specialized capabilities like database access, API integrations, or custom tooling.
+
+Create a JSON configuration file with your MCP servers:
+
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-filesystem",
+        "/path/to/allowed/files"
+      ]
+    },
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_TOKEN": "your-github-token"
+      }
+    }
+  }
+}
+```
+
+Then use it with Claude Code:
+
+```bash
+# Load MCP servers from configuration
+$ claude -p "List all files in the project" --mcp-config mcp-servers.json
+
+# Important: MCP tools must be explicitly allowed using --allowedTools
+# MCP tools follow the format: mcp__$serverName__$toolName
+$ claude -p "Search for TODO comments" \
+  --mcp-config mcp-servers.json \
+  --allowedTools "mcp__filesystem__read_file,mcp__filesystem__list_directory"
+
+# Use an MCP tool for handling permission prompts in non-interactive mode
+$ claude -p "Deploy the application" \
+  --mcp-config mcp-servers.json \
+  --allowedTools "mcp__permissions__approve" \
+  --permission-prompt-tool mcp__permissions__approve
+```
+
+Note: When using MCP tools, you must explicitly allow them using the `--allowedTools` flag. MCP tool names follow the pattern `mcp__<serverName>__<toolName>` where:
+
+* `serverName` is the key from your MCP configuration file
+* `toolName` is the specific tool provided by that server
+
+This security measure ensures that MCP tools are only used when explicitly permitted.
+
+### Custom permission prompt tool
+
+Optionally, use `--permission-prompt-tool` to pass in an MCP tool that we will use to check whether or not the user grants the model permissions to invoke a given tool. When the model invokes a tool the following happens:
+
+1. We first check permission settings: all [settings.json files](/en/docs/claude-code/settings), as well as `--allowedTools` and `--disallowedTools` passed into the SDK; if one of these allows or denies the tool call, we proceed with the tool call
+2. Otherwise, we invoke the MCP tool you provided in `--permission-prompt-tool`
+
+The `--permission-prompt-tool` MCP tool is passed the tool name and input, and must return a JSON-stringified payload with the result. The payload must be one of:
+
+```ts
+// tool call is allowed
+{
+  "behavior": "allow",
+  "updatedInput": {...}, // updated input, or just return back the original input
+}
+
+// tool call is denied
+{
+  "behavior": "deny",
+  "message": "..." // human-readable string explaining why the permission was denied
+}
+```
+
+For example, a TypeScript MCP permission prompt tool implementation might look like this:
+
+```ts
+const server = new McpServer({
+  name: "Test permission prompt MCP Server",
+  version: "0.0.1",
+});
+
+server.tool(
+  "approval_prompt",
+  'Simulate a permission check - approve if the input contains "allow", otherwise deny',
+  {
+    tool_name: z.string().describe("The tool requesting permission"),
+    input: z.object({}).passthrough().describe("The input for the tool"),
+  },
+  async ({ tool_name, input }) => {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            JSON.stringify(input).includes("allow")
+              ? {
+                  behavior: "allow",
+                  updatedInput: input,
+                }
+              : {
+                  behavior: "deny",
+                  message: "Permission denied by test approval_prompt tool",
+                }
+          ),
+        },
+      ],
+    };
+  }
+);
+```
+
+To use this tool, add your MCP server (eg. with `--mcp-config`), then invoke the SDK like so:
+
+```sh
+claude -p "..." \
+  --permission-prompt-tool mcp__test-server__approval_prompt \
+  --mcp-config my-config.json
+```
+
+Usage notes:
+
+* Use `updatedInput` to tell the model that the permission prompt mutated its input; otherwise, set `updatedInput` to the original input, as in the example above. For example, if the tool shows a file edit diff to the user and lets them edit the diff manually, the permission prompt tool should return that updated edit.
+* The payload must be JSON-stringified
+
+## Available CLI options
+
+The SDK leverages all the CLI options available in Claude Code. Here are the key ones for SDK usage:
+
+| Flag                       | Description                                                      | Example                                                        |
+| :------------------------- | :--------------------------------------------------------------- | :------------------------------------------------------------- |
+| `--print`, `-p`            | Run in non-interactive mode                                      | `claude -p "query"`                                            |
+| `--output-format`          | Specify output format (`text`, `json`, `stream-json`)            | `claude -p --output-format json`                               |
+| `--resume`, `-r`           | Resume a conversation by session ID                              | `claude --resume abc123`                                       |
+| `--continue`, `-c`         | Continue the most recent conversation                            | `claude --continue`                                            |
+| `--verbose`                | Enable verbose logging                                           | `claude --verbose`                                             |
+| `--max-turns`              | Limit agentic turns in non-interactive mode                      | `claude --max-turns 3`                                         |
+| `--system-prompt`          | Override system prompt (only with `--print`)                     | `claude --system-prompt "Custom instruction"`                  |
+| `--append-system-prompt`   | Append to system prompt (only with `--print`)                    | `claude --append-system-prompt "Custom instruction"`           |
+| `--allowedTools`           | Comma/space-separated list of allowed tools (includes MCP tools) | `claude --allowedTools "Bash(npm install),mcp__filesystem__*"` |
+| `--disallowedTools`        | Comma/space-separated list of denied tools                       | `claude --disallowedTools "Bash(git commit),mcp__github__*"`   |
+| `--mcp-config`             | Load MCP servers from a JSON file                                | `claude --mcp-config servers.json`                             |
+| `--permission-prompt-tool` | MCP tool for handling permission prompts (only with `--print`)   | `claude --permission-prompt-tool mcp__auth__prompt`            |
+
+For a complete list of CLI options and features, see the [CLI usage](/en/docs/claude-code/cli-usage) documentation.
+
+## Output formats
+
+The SDK supports multiple output formats:
+
+### Text output (default)
+
+Returns just the response text:
+
+```bash
+$ claude -p "Explain file src/components/Header.tsx"
+# Output: This is a React component showing...
+```
+
+### JSON output
+
+Returns structured data including metadata:
+
+```bash
+$ claude -p "How does the data layer work?" --output-format json
+```
+
+Response format:
+
+```json
+{
+  "type": "result",
+  "subtype": "success",
+  "cost_usd": 0.003,
+  "is_error": false,
+  "duration_ms": 1234,
+  "duration_api_ms": 800,
+  "num_turns": 6,
+  "result": "The response text here...",
+  "session_id": "abc123"
+}
+```
+
+### Streaming JSON output
+
+Streams each message as it is received:
+
+```bash
+$ claude -p "Build an application" --output-format stream-json
+```
+
+Each conversation begins with an initial `init` system message, followed by a list of user and assistant messages, followed by a final `result` system message with stats. Each message is emitted as a separate JSON object.
+
+## Message schema
+
+Messages returned from the JSON API are strictly typed according to the following schema:
+
+```ts
+type SDKMessage =
+  // An assistant message
+  | {
+      type: "assistant";
+      message: Message; // from Anthropic SDK
+      session_id: string;
+    }
+
+  // A user message
+  | {
+      type: "user";
+      message: MessageParam; // from Anthropic SDK
+      session_id: string;
+    }
+
+  // Emitted as the last message
+  | {
+      type: "result";
+      subtype: "success";
+      cost_usd: float;
+      duration_ms: float;
+      duration_api_ms: float;
+      is_error: boolean;
+      num_turns: int;
+      result: string;
+      session_id: string;
+    }
+
+  // Emitted as the last message, when we've reached the maximum number of turns
+  | {
+      type: "result";
+      subtype: "error_max_turns";
+      cost_usd: float;
+      duration_ms: float;
+      duration_api_ms: float;
+      is_error: boolean;
+      num_turns: int;
+      session_id: string;
+    }
+
+  // Emitted as the first message at the start of a conversation
+  | {
+      type: "system";
+      subtype: "init";
+      session_id: string;
+      tools: string[];
+      mcp_servers: {
+        name: string;
+        status: string;
+      }[];
+    };
+```
+
+We will soon publish these types in a JSONSchema-compatible format. We use semantic versioning for the main Claude Code package to communicate breaking changes to this format.
+
+`Message` and `MessageParam` types are available in Anthropic SDKs. For example, see the Anthropic [TypeScript](https://github.com/anthropics/anthropic-sdk-typescript) and [Python](https://github.com/anthropics/anthropic-sdk-python/) SDKs.
+
+## Examples
+
+### Simple script integration
+
+```bash
+#!/bin/bash
+
+# Simple function to run Claude and check exit code
+run_claude() {
+    local prompt="$1"
+    local output_format="${2:-text}"
+
+    if claude -p "$prompt" --output-format "$output_format"; then
+        echo "Success!"
+    else
+        echo "Error: Claude failed with exit code $?" >&2
+        return 1
+    fi
+}
+
+# Usage examples
+run_claude "Write a Python function to read CSV files"
+run_claude "Optimize this database query" "json"
+```
+
+### Processing files with Claude
+
+```bash
+# Process a file through Claude
+$ cat mycode.py | claude -p "Review this code for bugs"
+
+# Process multiple files
+$ for file in *.js; do
+    echo "Processing $file..."
+    claude -p "Add JSDoc comments to this file:" < "$file" > "${file}.documented"
+done
+
+# Use Claude in a pipeline
+$ grep -l "TODO" *.py | while read file; do
+    claude -p "Fix all TODO items in this file" < "$file"
+done
+```
+
+### Session management
+
+```bash
+# Start a session and capture the session ID
+$ claude -p "Initialize a new project" --output-format json | jq -r '.session_id' > session.txt
+
+# Continue with the same session
+$ claude -p --resume "$(cat session.txt)" "Add unit tests"
+```
+
+## Best practices
+
+1. **Use JSON output format** for programmatic parsing of responses:
+
+   ```bash
+   # Parse JSON response with jq
+   result=$(claude -p "Generate code" --output-format json)
+   code=$(echo "$result" | jq -r '.result')
+   cost=$(echo "$result" | jq -r '.cost_usd')
+   ```
+
+2. **Handle errors gracefully** - check exit codes and stderr:
+
+   ```bash
+   if ! claude -p "$prompt" 2>error.log; then
+       echo "Error occurred:" >&2
+       cat error.log >&2
+       exit 1
+   fi
+   ```
+
+3. **Use session management** for maintaining context in multi-turn conversations
+
+4. **Consider timeouts** for long-running operations:
+
+   ```bash
+   timeout 300 claude -p "$complex_prompt" || echo "Timed out after 5 minutes"
+   ```
+
+5. **Respect rate limits** when making multiple requests by adding delays between calls
+
+## Real-world applications
+
+The Claude Code SDK enables powerful integrations with your development workflow. One notable example is the [Claude Code GitHub Actions](/en/docs/claude-code/github-actions), which uses the SDK to provide automated code review, PR creation, and issue triage capabilities directly in your GitHub workflow.
+
+## Related resources
+
+* [CLI usage and controls](/en/docs/claude-code/cli-usage) - Complete CLI documentation
+* [GitHub Actions integration](/en/docs/claude-code/github-actions) - Automate your GitHub workflow with Claude
+* [Tutorials](/en/docs/claude-code/tutorials) - Step-by-step guides for common use cases

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: claude_swarm
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.6
 platform: ruby
 authors:
 - Paulo Arruda
 bindir: exe
 cert_chain: []
-date: 2025-05-30 00:00:00.000000000 Z
+date: 2025-06-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -67,7 +67,11 @@ files:
 - lib/claude_swarm/configuration.rb
 - lib/claude_swarm/mcp_generator.rb
 - lib/claude_swarm/orchestrator.rb
+- lib/claude_swarm/reset_session_tool.rb
+- lib/claude_swarm/session_info_tool.rb
+- lib/claude_swarm/task_tool.rb
 - lib/claude_swarm/version.rb
+- sdk-docs.md
 homepage: https://github.com/parruda/claude-swarm
 licenses: []
 metadata: