schwarm-cli 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 485f701799de73d084bf43fff3cc0ebf1244a41397775baea03de793b860b4b9
-  data.tar.gz: 6125bc6e805189c3faa9ec3d33ff6545fd77c4c93ab966ccae142a2fc50102a5
+  metadata.gz: 066e7d9d88f9e9d06311933b23308735d9856580de1f2d2dfc320d90f45f6deb
+  data.tar.gz: f46de7b54809c3283f14669c0727d308d6e5b8d24066c0e99618c7945b0b044f
 SHA512:
-  metadata.gz: 1ef6550c32124fe3a2125dc2e79d10c05ec918bbabafd17918d1c13274954b33fae413cd679f58e5484c4b02b97bda64c6d495a62fb02d38e1afba389de7ac69
-  data.tar.gz: 2057d8334094ab913ebc115ed3818a54887cafa922688bcc66f54be4035322d51466ccd7610a1aad0b68f59ccb643604551a7b7e791168ba49f3be4a9e83dbf7
+  metadata.gz: 28ae5f67cdd2bbca5a04d1571171252adb36fd7eaccc489f8306038887c52e55c65fea6e348fc5af1ac849f5fd6725be49741d3f68cadfd863897d370fc9ac44
+  data.tar.gz: ace4db1afda31bcdc3b4555c7167c3259ec2723ec9a86f6750b9c6eb85ef4dcf26cc71f7e1e636b2882d510cb1e006daf277988851758467412811f445a9765c

data/lib/schwarm_cli/client/agent_sessions.rb

@@ -3,8 +3,9 @@
 module SchwarmCli
   class Client
     class AgentSessions < Resource
-      def list(source: nil, status: nil, page: nil, per_page: nil)
+      def list(source: nil, status: nil, page: nil, per_page: nil, active: nil)
         params = { source:, status:, page:, per_page: }.compact
+        params[:active] = active unless active.nil?
         get("/api/v2/agent_sessions", params).body
       end
 

data/lib/schwarm_cli/client/tasks.rb

@@ -3,8 +3,9 @@
 module SchwarmCli
   class Client
     class Tasks < Resource
-      def list(status: nil, repository_id: nil, page: nil, per_page: nil, query: nil)
-        params = { status:, repository_id:, page:, per_page:, q: query }.compact
+      def list(query: nil, **filters)
+        params = filters.compact
+        params[:q] = query if query
         get("/api/v2/tasks", params).body
       end
 

data/lib/schwarm_cli/commands/agents.rb

@@ -6,10 +6,13 @@ module SchwarmCli
       desc "list", "List repository agents"
       option :repo, type: :string, desc: "Filter by repository ID"
       option :query, type: :string, desc: "Search by name"
+      pagination_options
       def list
         handle_errors do
-          data = client.agents.list(repository_id: options[:repo], query: options[:query])
-          output_list(data, columns: [%w[ID id], %w[NAME name], %w[REPO github_repository_id],
+          data = fetch_paged do |page_params|
+            client.agents.list(repository_id: options[:repo], query: options[:query], **page_params)
+          end
+          output_list(data, columns: [%w[ID id], %w[NAME name], %w[REPO github_repository_name],
                                       %w[ENABLED enabled], %w[SCHEDULE schedule]])
         end
       end

data/lib/schwarm_cli/commands/base.rb

@@ -9,6 +9,16 @@ module SchwarmCli
       class_option :url, type: :string, desc: "Schwarm server URL (overrides config)"
       class_option :token, type: :string, desc: "API key (overrides config)"
 
+      DEFAULT_LIST_LIMIT = 20
+
+      # Declares --limit, --page, --all options for the next method.
+      def self.pagination_options
+        method_option :limit, type: :numeric,
+                              desc: "Max results per page (default: #{DEFAULT_LIST_LIMIT})"
+        method_option :page, type: :numeric, desc: "Page number (1-indexed)"
+        method_option :all, type: :boolean, default: false, desc: "Fetch all pages (no cap)"
+      end
+
       private
 
       def client
@@ -19,8 +29,36 @@ module SchwarmCli
         if options[:json]
           Formatters::Json.format(data)
         else
-          Formatters::Table.format_list(data["data"], columns:)
+          Formatters::Table.format_list(data["data"], columns:, meta: data["meta"])
+        end
+      end
+
+      # Yields pagination params to the block (once per page). With --all, pages
+      # through all results; otherwise a single call using --limit/--page (or the
+      # CLI default limit). Returns the merged payload.
+      def fetch_paged(&block)
+        if options[:all]
+          fetch_all_pages(&block)
+        else
+          per_page = options[:limit] || DEFAULT_LIST_LIMIT
+          block.call({ page: options[:page], per_page: }.compact)
+        end
+      end
+
+      def fetch_all_pages
+        merged_data = []
+        page = 1
+        per_page = options[:limit] || 200
+        meta = nil
+        loop do
+          response = yield({ page:, per_page: })
+          merged_data.concat(response["data"] || [])
+          meta = response["meta"]
+          break unless meta && page < meta["total_pages"].to_i
+
+          page += 1
         end
+        { "data" => merged_data, "meta" => meta&.merge("page" => 1, "per_page" => merged_data.size) }
       end
 
       def output_record(data, fields:)

data/lib/schwarm_cli/commands/main.rb

@@ -59,6 +59,12 @@ module SchwarmCli
       end
 
       map %w[-v --version] => :version
+
+      desc "skill", "Print the agent skill documenting how AI agents use the Schwarm CLI"
+      def skill
+        path = File.expand_path("../../../schwarm-skill.md", __dir__)
+        puts File.read(path)
+      end
     end
   end
 end

data/lib/schwarm_cli/commands/recurring.rb

@@ -6,10 +6,13 @@ module SchwarmCli
       desc "list", "List recurring tasks"
       option :repo, type: :string, desc: "Filter by repository ID"
       option :query, type: :string, desc: "Search by name"
+      pagination_options
       def list
         handle_errors do
-          data = client.recurring.list(repository_id: options[:repo], query: options[:query])
-          output_list(data, columns: [%w[ID id], %w[NAME name], %w[REPO github_repository_id],
+          data = fetch_paged do |page_params|
+            client.recurring.list(repository_id: options[:repo], query: options[:query], **page_params)
+          end
+          output_list(data, columns: [%w[ID id], %w[NAME name], %w[REPO github_repository_name],
                                       %w[ENABLED enabled], %w[SCHEDULE schedule]])
         end
       end

data/lib/schwarm_cli/commands/repo_skills.rb

@@ -6,11 +6,14 @@ module SchwarmCli
       desc "list", "List repository-skill associations"
       option :repo, type: :string, desc: "Filter by repository ID"
       option :skill, type: :string, desc: "Filter by skill ID"
+      pagination_options
       def list
         handle_errors do
-          data = client.repo_skills.list(repository_id: options[:repo], skill_id: options[:skill])
-          output_list(data, columns: [%w[ID id], %w[REPO github_repository_id],
-                                      %w[SKILL skill_id]])
+          data = fetch_paged do |page_params|
+            client.repo_skills.list(repository_id: options[:repo], skill_id: options[:skill], **page_params)
+          end
+          output_list(data, columns: [%w[ID id], %w[REPO github_repository_name],
+                                      %w[SKILL skill_name]])
         end
       end
 

data/lib/schwarm_cli/commands/repos.rb

@@ -6,9 +6,12 @@ module SchwarmCli
       desc "list", "List repositories"
       option :status, type: :string, desc: "Filter by status"
       option :query, type: :string, desc: "Search by name"
+      pagination_options
       def list
         handle_errors do
-          data = client.repositories.list(status: options[:status], query: options[:query])
+          data = fetch_paged do |page_params|
+            client.repositories.list(status: options[:status], query: options[:query], **page_params)
+          end
           output_list(data, columns: [%w[ID id], %w[NAME name], %w[STATUS status]])
         end
       end

data/lib/schwarm_cli/commands/secrets.rb

@@ -5,10 +5,13 @@ module SchwarmCli
     class Secrets < Base
       desc "list", "List secret files"
       option :repo, type: :string, desc: "Filter by repository ID"
+      pagination_options
       def list
         handle_errors do
-          data = client.secrets.list(repository_id: options[:repo])
-          output_list(data, columns: [%w[ID id], %w[NAME name], %w[REPO github_repository_id],
+          data = fetch_paged do |page_params|
+            client.secrets.list(repository_id: options[:repo], **page_params)
+          end
+          output_list(data, columns: [%w[ID id], %w[NAME name], %w[REPO github_repository_name],
                                       %w[PATH path]])
         end
       end

data/lib/schwarm_cli/commands/sessions.rb

@@ -3,12 +3,19 @@
 module SchwarmCli
   module Commands
     class Sessions < Base
-      desc "list", "List agent sessions"
+      desc "list", "List agent sessions (shows active ones by default)"
       option :source, type: :string, desc: "Filter by source"
       option :status, type: :string, desc: "Filter by status"
+      pagination_options
       def list
         handle_errors do
-          data = client.sessions.list(source: options[:source], status: options[:status])
+          active_only = options[:status].nil? && !options[:all]
+          data = fetch_paged do |page_params|
+            client.sessions.list(
+              source: options[:source], status: options[:status],
+              active: active_only ? true : nil, **page_params
+            )
+          end
           output_list(data, columns: [%w[ID id], %w[SOURCE source], %w[STATUS status],
                                       %w[CREATED created_at]])
         end

data/lib/schwarm_cli/commands/shared_agents.rb

@@ -5,9 +5,12 @@ module SchwarmCli
     class SharedAgentsCmd < Base
       desc "list", "List shared agents"
       option :query, type: :string, desc: "Search by name"
+      pagination_options
       def list
         handle_errors do
-          data = client.shared_agents.list(query: options[:query])
+          data = fetch_paged do |page_params|
+            client.shared_agents.list(query: options[:query], **page_params)
+          end
           output_list(data, columns: [%w[ID id], %w[NAME name], %w[ENABLED enabled],
                                       %w[SCHEDULE schedule]])
         end

data/lib/schwarm_cli/commands/skill_files.rb

@@ -6,9 +6,12 @@ module SchwarmCli
       class_option :skill, type: :string, required: true, desc: "Skill ID"
 
       desc "list", "List skill files"
+      pagination_options
       def list
         handle_errors do
-          data = client.skill_files.list(skill_id: options[:skill])
+          data = fetch_paged do |page_params|
+            client.skill_files.list(skill_id: options[:skill], **page_params)
+          end
           output_list(data, columns: [%w[ID id], %w[PATH path], %w[CREATED created_at]])
         end
       end

data/lib/schwarm_cli/commands/skills.rb

@@ -5,9 +5,12 @@ module SchwarmCli
     class SkillsCmd < Base
       desc "list", "List skills"
       option :query, type: :string, desc: "Search by name"
+      pagination_options
       def list
         handle_errors do
-          data = client.skills.list(query: options[:query])
+          data = fetch_paged do |page_params|
+            client.skills.list(query: options[:query], **page_params)
+          end
           output_list(data, columns: [%w[ID id], %w[NAME name], %w[GLOBAL global]])
         end
       end

data/lib/schwarm_cli/commands/tasks.rb

@@ -3,15 +3,16 @@
 module SchwarmCli
   module Commands
     class Tasks < Base
-      desc "list", "List tasks"
+      desc "list", "List tasks (excludes archived by default)"
       option :status, type: :string, desc: "Filter by status"
       option :repo, type: :string, desc: "Filter by repository ID"
       option :query, type: :string, desc: "Search by name"
+      pagination_options
       def list
         handle_errors do
-          data = client.tasks.list(status: options[:status], repository_id: options[:repo], query: options[:query])
+          data = fetch_paged { |page_params| client.tasks.list(**list_attrs, **page_params) }
           output_list(data, columns: [%w[ID id], %w[NAME name], %w[STATUS status],
-                                      %w[REPO github_repository_id], %w[CREATED created_at]])
+                                      %w[REPO github_repository_name], %w[CREATED created_at]])
         end
       end
 
@@ -113,8 +114,43 @@ module SchwarmCli
         end
       end
 
+      desc "handoff", "Hand off the current local branch to schwarm as a ready task"
+      option :prompt, type: :string, desc: "Task prompt"
+      option :prompt_file, type: :string, desc: "Read prompt from file"
+      option :repo, type: :string, desc: "Repository ID (skips origin auto-detect)"
+      option :name, type: :string, desc: "Task name (defaults to the branch name)"
+      def handoff
+        prompt = read_prompt
+        abort "Error: --prompt or --prompt-file is required." if prompt.nil? || prompt.strip.empty?
+
+        handle_errors do
+          result = SchwarmCli::HandsOffTask.new(client: client).call(
+            prompt: prompt, repo_override: options[:repo], name_override: options[:name]
+          )
+          print_handoff_result(result)
+        end
+      end
+
       private
 
+      def list_attrs
+        exclude_archived = options[:status].nil? && !options[:all]
+        {
+          status: options[:status], repository_id: options[:repo], query: options[:query],
+          archived: exclude_archived ? false : nil
+        }
+      end
+
+      def print_handoff_result(result)
+        if result.success?
+          puts "Pushed #{result.branch_name} to origin."
+          puts "Task #{result.task_id} created (status: #{result.status})."
+          puts "  #{result.task_url}"
+        else
+          abort "Error: #{result.error_message}"
+        end
+      end
+
       def create_attrs
         {
           name: options[:name], prompt: read_prompt,

data/lib/schwarm_cli/commands/templates.rb

@@ -5,9 +5,12 @@ module SchwarmCli
     class Templates < Base
       desc "list", "List task templates"
       option :query, type: :string, desc: "Search by name"
+      pagination_options
       def list
         handle_errors do
-          data = client.templates.list(query: options[:query])
+          data = fetch_paged do |page_params|
+            client.templates.list(query: options[:query], **page_params)
+          end
           output_list(data, columns: [%w[ID id], %w[NAME name], %w[CREATED created_at]])
         end
       end

data/lib/schwarm_cli/formatters/table.rb

@@ -3,7 +3,7 @@
 module SchwarmCli
   module Formatters
     module Table
-      def self.format_list(records, columns:)
+      def self.format_list(records, columns:, meta: nil)
         if records.empty?
           puts "No results found."
           return
@@ -14,6 +14,18 @@ module SchwarmCli
         records.each do |record|
           puts format_row(columns.map { |_, key| record[key].to_s }, columns, widths)
         end
+        footer = pagination_footer(records, meta)
+        puts "\n#{footer}" if footer
+      end
+
+      def self.pagination_footer(records, meta)
+        meta = meta&.transform_keys(&:to_s)
+        total = meta && meta["total_count"]
+        return nil if total.nil? || total <= records.size
+
+        parts = ["showing #{records.size} of #{total}"]
+        parts << "page #{meta['page']} of #{meta['total_pages']}" if meta["total_pages"].to_i > 1
+        "#{parts.join(' · ')} — use --all or --page/--limit to see more"
       end
 
       def self.format_record(record, fields:)
@@ -33,7 +45,7 @@ module SchwarmCli
         values.zip(columns).map { |val, (_, key)| val.ljust(widths[key]) }.join("  ")
       end
 
-      private_class_method :column_widths, :format_row
+      private_class_method :column_widths, :format_row, :pagination_footer
     end
   end
 end

data/lib/schwarm_cli/git.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module SchwarmCli
+  # Minimal git shell-out wrapper.
+  #
+  # Returns a Result struct for every invocation so callers can pattern-match on
+  # +success?+ and surface +stderr+ verbatim when a command fails.
+  module Git
+    Result = Struct.new(:stdout, :stderr, :success?, keyword_init: true)
+
+    def self.run(*, chdir: Dir.pwd)
+      stdout, stderr, status = Open3.capture3("git", *, chdir: chdir)
+      Result.new(stdout: stdout, stderr: stderr, success?: status.success?)
+    end
+  end
+end

data/lib/schwarm_cli/hands_off_task.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module SchwarmCli
+  # Runs preflight checks, pushes the current branch, and creates a schwarm
+  # task pointing at it. Returns a Result the CLI command prints.
+  class HandsOffTask
+    Result = Struct.new(:success?, :task_id, :task_url, :branch_name, :status, :error_message,
+                        keyword_init: true)
+
+    def initialize(git: SchwarmCli::Git, client: SchwarmCli::Client.new)
+      @git = git
+      @client = client
+    end
+
+    def call(prompt:, repo_override:, name_override:)
+      repo, branch, error = run_preflight(repo_override)
+      return error if error
+
+      push_result = @git.run("push", "-u", "origin", "HEAD")
+      return failure(push_result.stderr.strip) unless push_result.success?
+
+      create_task(repo: repo, branch: branch, prompt: prompt, name_override: name_override)
+    rescue Faraday::Error => e
+      failure(parse_api_error(e))
+    end
+
+    private
+
+    def run_preflight(repo_override) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      return [nil, nil, failure("not in a git repository")] unless inside_work_tree?
+
+      origin = origin_url
+      unless github_url?(origin)
+        return [nil, nil, failure("handoff requires a GitHub `origin` remote (got `#{origin}`)")]
+      end
+
+      repo = resolve_repository(origin: origin, override: repo_override)
+      return [nil, nil, failure(missing_repo_message(origin, repo_override))] if repo.nil?
+
+      branch = current_branch
+      if branch.empty?
+        return [nil, nil, failure("not on a branch (detached HEAD). Check out a branch before handing off.")]
+      end
+
+      base_branch = repo["base_branch"]
+      if branch == base_branch
+        return [nil, nil,
+                failure("refusing to hand off the base branch `#{base_branch}`; create a feature branch first.")]
+      end
+
+      dirty = status_porcelain
+      return [nil, nil, failure("commit or stash your changes before handing off:\n#{dirty}")] unless dirty.empty?
+
+      [repo, branch, nil]
+    end
+
+    def missing_repo_message(origin, repo_override)
+      if repo_override
+        "no schwarm repository with id `#{repo_override}`."
+      else
+        "no schwarm repository matches origin `#{origin}`. Pass --repo <id> to override."
+      end
+    end
+
+    def inside_work_tree?
+      @git.run("rev-parse", "--is-inside-work-tree").success?
+    end
+
+    def origin_url
+      result = @git.run("remote", "get-url", "origin")
+      result.success? ? result.stdout.strip : ""
+    end
+
+    def github_url?(url)
+      url.include?("github.com")
+    end
+
+    def current_branch
+      @git.run("symbolic-ref", "--short", "HEAD").stdout.strip
+    end
+
+    def status_porcelain
+      @git.run("status", "--porcelain").stdout
+    end
+
+    def resolve_repository(origin:, override:)
+      if override
+        begin
+          return @client.repositories.find(override)["data"]
+        rescue Faraday::ResourceNotFound
+          return nil
+        end
+      end
+
+      slug = origin_slug(origin)
+      response = @client.repositories.list(query: slug)
+      Array(response["data"]).find { |r| normalize_url(r["github_url"]) == normalize_url(origin) }
+    end
+
+    def origin_slug(url)
+      # Accept both https://github.com/org/repo[.git] and git@github.com:org/repo.git
+      url.sub(%r{\Ahttps?://github\.com/}, "").sub(/\Agit@github\.com:/, "").sub(/\.git\z/, "")
+    end
+
+    def normalize_url(url)
+      return nil if url.nil?
+
+      url.sub(/\.git\z/, "").sub(/\Agit@github\.com:/, "https://github.com/")
+    end
+
+    def create_task(repo:, branch:, prompt:, name_override:)
+      response = @client.tasks.create(
+        name: name_override || branch,
+        branch_name: branch,
+        prompt: prompt,
+        status: "ready",
+        github_repository_id: repo["id"]
+      )
+      data = response["data"]
+      Result.new(
+        success?: true,
+        task_id: data["id"],
+        task_url: task_url_for(data["id"]),
+        branch_name: data["branch_name"],
+        status: data["status"]
+      )
+    end
+
+    def task_url_for(task_id)
+      base = ENV["SCHWARM_URL"] || SchwarmCli::Config.new.url
+      "#{base.chomp('/')}/tasks/#{task_id}"
+    end
+
+    def parse_api_error(error)
+      body = error.response&.dig(:body)
+      return error.message unless body.is_a?(String)
+
+      JSON.parse(body).dig("error", "message") || error.message
+    rescue JSON::ParserError
+      error.message
+    end
+
+    def failure(message)
+      Result.new(success?: false, error_message: message)
+    end
+  end
+end

data/lib/schwarm_cli/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SchwarmCli
-  VERSION = "0.1.0"
+  VERSION = "0.1.2"
 end

data/lib/schwarm_cli.rb

@@ -3,6 +3,8 @@
 require_relative "schwarm_cli/version"
 require_relative "schwarm_cli/config"
 require_relative "schwarm_cli/client"
+require_relative "schwarm_cli/git"
+require_relative "schwarm_cli/hands_off_task"
 require_relative "schwarm_cli/formatters/json"
 require_relative "schwarm_cli/formatters/table"
 require_relative "schwarm_cli/commands/main"

data/schwarm-skill.md

@@ -0,0 +1,226 @@
+# Schwarm
+
+Schwarm is a distributed system that orchestrates Claude Code agents working on
+tasks in parallel. Use the `schwarm` CLI to dispatch work to Schwarm from your
+local machine.
+
+## Prerequisites
+
+The `schwarm` CLI is installed and configured (`schwarm configure`).
+
+## Key Concepts
+
+- **Repository** — a GitHub repo linked to Schwarm. Tasks run against a repo.
+- **Task** — a unit of work. Schwarm creates an isolated git worktree and runs
+  Claude Code on it. Tasks have a lifecycle: draft -> ready -> claimed -> archived.
+- **Dependencies** — tasks can depend on other tasks, forming a DAG. A task with
+  unresolved dependencies stays in `waiting` until they're all archived.
+- **Node** — a worker machine that picks up `ready` tasks and runs Claude Code.
+
+## Workflows
+
+### 1. Dispatch a single task
+
+**When:** You have a self-contained piece of work to send to Schwarm.
+
+**Steps:**
+1. Find the repository ID:
+   ```bash
+   schwarm repos list
+   ```
+2. Create the task and start it immediately:
+   ```bash
+   schwarm tasks create --repo <REPO_ID> --name "Fix login bug" --prompt "The login form crashes when email is empty. Fix the validation in app/models/user.rb" --status ready
+   ```
+   Use `--prompt-file ./prompt.md` for long prompts.
+3. Check the created task:
+   ```bash
+   schwarm tasks show <TASK_ID>
+   ```
+
+**Watch for:** If you set `--status ready`, the task starts immediately. Omit
+`--status` (defaults to draft) if you want to review before starting.
+
+### 1b. Hand off a WIP branch to schwarm
+
+**When:** You have work in progress on a local branch and want schwarm to
+continue from where you left off. Schwarm picks up the same branch and
+continues committing to it.
+
+**Steps:**
+1. Make sure your working tree is clean (commit or stash local changes).
+2. Hand off from the current branch:
+   ```bash
+   schwarm tasks handoff --prompt "continue the validation logic, add tests"
+   ```
+   Use `--prompt-file ./handoff.md` for long prompts.
+3. Take note of the task ID printed on success; you can monitor it like any
+   other task.
+
+**Watch for:**
+- The command refuses to hand off the base branch (`main`). Create a feature
+  branch first.
+- It refuses if the working tree is dirty — commit or stash first.
+- If another non-archived task already owns this branch name, the command
+  will print the conflicting task ID. Archive or reset it first.
+- The repository is auto-detected from `git remote get-url origin`. Use
+  `--repo <id>` if you need to override it (e.g. in a fork).
+
+### 2. Dispatch a DAG of tasks
+
+**When:** You need to break work into multiple steps with ordering constraints.
+
+**Steps:**
+1. Create all tasks as drafts first:
+   ```bash
+   schwarm tasks create --repo <REPO_ID> --name "Step 1: Refactor models" --prompt "..."
+   schwarm tasks create --repo <REPO_ID> --name "Step 2: Add tests" --prompt "..." --depends-on <STEP1_ID>
+   schwarm tasks create --repo <REPO_ID> --name "Step 3: Update docs" --prompt "..." --depends-on <STEP1_ID>
+   schwarm tasks create --repo <REPO_ID> --name "Step 4: Integration tests" --prompt "..." --depends-on <STEP2_ID> <STEP3_ID>
+   ```
+2. Start all tasks — Schwarm cascades automatically:
+   ```bash
+   schwarm tasks start <STEP1_ID>
+   schwarm tasks start <STEP2_ID>
+   schwarm tasks start <STEP3_ID>
+   schwarm tasks start <STEP4_ID>
+   ```
+   Tasks with unresolved dependencies move to `waiting` and become `ready`
+   automatically when their dependencies are archived.
+
+**Watch for:** You must start all tasks, not just the root. Starting moves
+drafts to `ready` or `waiting` (depending on whether dependencies are resolved).
+Tasks left as `draft` will never run.
+
+### 3. Monitor task progress
+
+**When:** You've dispatched tasks and want to check on them.
+
+**Steps:**
+1. List active tasks:
+   ```bash
+   schwarm tasks list --status claimed
+   schwarm tasks list --status ready
+   schwarm tasks list --status error
+   ```
+2. Check a specific task:
+   ```bash
+   schwarm tasks show <TASK_ID>
+   ```
+   Look at Status, Branch, and Error fields.
+3. View agent session logs for debugging:
+   ```bash
+   schwarm sessions list --json
+   schwarm sessions show <SESSION_ID>
+   ```
+
+**Watch for:** A task in `claimed` status means a node is actively working on
+it. `ready` means it's waiting for a node to pick it up.
+
+### 4. Send a message to a running task
+
+**When:** A task is in `claimed` status and you want to give it additional
+instructions or course corrections.
+
+**Steps:**
+1. Send the message:
+   ```bash
+   schwarm tasks message <TASK_ID> --content "Also fix the validation for the password field"
+   ```
+
+**Watch for:** Messages are delivered asynchronously via the node's polling loop.
+The agent will see the message on its next check. Only works for `claimed` tasks.
+
+### 5. Handle failures
+
+**When:** A task has moved to `error` status.
+
+**Steps:**
+1. Check what went wrong:
+   ```bash
+   schwarm tasks show <TASK_ID>
+   ```
+   The Error field shows the failure reason.
+2. Decide: retry or reset.
+   - **Retry** — re-runs the task from where it left off (same worktree):
+     ```bash
+     schwarm tasks retry <TASK_ID>
+     ```
+   - **Reset** — moves the task back to `draft` for a fresh start:
+     ```bash
+     schwarm tasks reset <TASK_ID>
+     schwarm tasks start <TASK_ID>
+     ```
+
+**Watch for:** Use `retry` for transient failures (node crash, timeout). Use
+`reset` when you need to change the prompt or start clean. After reset, you
+must `start` again.
+
+### 6. Discover repos and templates
+
+**When:** Before creating tasks, you need to know what's available.
+
+**Steps:**
+1. List repositories:
+   ```bash
+   schwarm repos list
+   ```
+2. List task templates (pre-made prompts):
+   ```bash
+   schwarm templates list
+   schwarm templates show <TEMPLATE_ID>
+   ```
+3. Create a task from a template:
+   ```bash
+   schwarm tasks create --repo <REPO_ID> --name "Apply template" --template <TEMPLATE_ID> --status ready
+   ```
+
+### 7. Manage recurring tasks
+
+**When:** You want a task to run on a schedule (e.g., nightly tests).
+
+**Steps:**
+1. Create a recurring task:
+   ```bash
+   schwarm recurring create --repo <REPO_ID> --name "Nightly tests" --schedule "0 0 * * *" --prompt "Run the full test suite and fix any failures"
+   ```
+2. Toggle on/off:
+   ```bash
+   schwarm recurring toggle <ID>
+   ```
+3. List existing recurring tasks:
+   ```bash
+   schwarm recurring list --repo <REPO_ID>
+   ```
+
+### 8. Configure skills and agents
+
+**When:** You want to customize what skills or agent instructions are available
+for tasks in a repository.
+
+**Steps:**
+1. List available skills:
+   ```bash
+   schwarm skills list
+   ```
+2. Attach a skill to a repository:
+   ```bash
+   schwarm repo-skills create --repo <REPO_ID> --skill <SKILL_ID>
+   ```
+3. Create a repository agent (custom instructions for all tasks in a repo):
+   ```bash
+   schwarm agents create --repo <REPO_ID> --name "Code style" --prompt "Always follow the project's eslint config"
+   ```
+4. List agents for a repo:
+   ```bash
+   schwarm agents list --repo <REPO_ID>
+   ```
+
+## Tips
+
+- Use `--json` when parsing output programmatically.
+- Check task status before taking actions (e.g., only `retry` works on `error`
+  tasks, only `start` works on `draft` tasks).
+- When building a DAG, create all tasks as drafts first, then start them all.
+- For long prompts, write them to a file and use `--prompt-file`.
+- Run `schwarm <command> help` for full flag documentation on any command.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: schwarm-cli
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Vincent Garrigues
@@ -119,7 +119,10 @@ files:
 - lib/schwarm_cli/config.rb
 - lib/schwarm_cli/formatters/json.rb
 - lib/schwarm_cli/formatters/table.rb
+- lib/schwarm_cli/git.rb
+- lib/schwarm_cli/hands_off_task.rb
 - lib/schwarm_cli/version.rb
+- schwarm-skill.md
 homepage: https://github.com/getdexter/schwarm
 licenses:
 - MIT