schwarm-cli 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 407d8cf7c33a697ed71a0bd8b3345d278fa34705ec04fdc2ee358d55c7c549c2
-  data.tar.gz: 2949bbaf855be804caec35e0a25df038850c2bd4e7885421651f3cc48c4cbbe3
+  metadata.gz: 5ad711fe3997e1d3b3c18cee54f6621ecc3d895f01f7c09916e5bb1f217ea6c4
+  data.tar.gz: 3c0b5c575b1ee49423a547eeadc5a7310109e5ff294f718ee0e3cbd016f25dda
 SHA512:
-  metadata.gz: d3841fa2204bac7b1ee9debab270e7509925388563d49a72dcfbbfb61d8c7ab593ccc14a6c6ec978925c43c0a83f46603e0607a28a4e5d4696f50b87f1f7e8c4
-  data.tar.gz: cffebca5659d080e7b05ddd386e254acc3870b40678a59ee3e76acf5e5ee82119643ecd7390df00b7102768b5f8e11703900927a4ba035e211b0314e33a3fb5b
+  metadata.gz: a1650f63cca311d44de2f6c6b351a4bb1f81958ec5ce3093ac0a6745f5f1104ae632bcb38386bac177dd03e1274052bb47dd7967f2a0a689de1b9e28dd8227eb
+  data.tar.gz: b5696799424c27eb8a7808ff225a461e1573e28ffb4cb2261ecd541687344293e5f115fa743605273b612db9639c61ba1eb1ee70113deaca8f9e5dd26b70dc5d

data/README.md

@@ -0,0 +1,68 @@
+# schwarm-cli
+
+Command-line interface for [Schwarm](https://github.com/getdexter/schwarm) — a
+distributed system that orchestrates Claude Code agents working on tasks in
+parallel. Wraps the Schwarm Public API v2 to manage tasks, repositories,
+skills, agents, and more.
+
+## Installation
+
+Requires Ruby >= 4.0.
+
+```bash
+gem install schwarm-cli
+```
+
+This installs the `schwarm` executable.
+
+## Configuration
+
+Run the interactive configuration once to point the CLI at your Schwarm
+server and save an API key:
+
+```bash
+schwarm configure
+```
+
+You'll be prompted for:
+
+- **Server URL** (defaults to `https://schwarm.getdexter.net`)
+- **API Key** — create one from your Schwarm server's API Keys page
+
+The credentials are saved to `~/.schwarm/config/<env>.json` and the connection
+is tested before saving.
+
+## Usage
+
+List top-level commands:
+
+```bash
+schwarm help
+schwarm tree         # full command tree
+schwarm version
+```
+
+Common workflows:
+
+```bash
+schwarm repos list
+schwarm tasks list
+schwarm tasks create --repo <REPO_ID> --name "Fix bug" --prompt "..." --status ready
+schwarm tasks show <TASK_ID>
+schwarm tasks handoff --repo <REPO_ID> --name "Continue WIP"
+```
+
+For the full set of agent-oriented workflows (dispatching tasks, DAGs,
+handoffs, monitoring, messaging), print the bundled skill:
+
+```bash
+schwarm skill
+```
+
+This is the same document AI agents read to learn how to drive the CLI, and
+it's kept in sync with the gem at [`cli/schwarm-skill.md`](schwarm-skill.md).
+
+## Links
+
+- [Schwarm repository](https://github.com/getdexter/schwarm)
+- [Source](https://github.com/getdexter/schwarm/tree/main/cli)

data/lib/schwarm_cli/client/user_messages.rb

@@ -4,7 +4,7 @@ module SchwarmCli
   class Client
     class UserMessages < Resource
       def create(task_id:, content:)
-        post("/api/v2/tasks/#{task_id}/messages", { user_message: { content: } }).body
+        post("/api/v2/tasks/#{task_id}/messages", { message: { content: } }).body
       end
     end
   end

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/tasks.rb

@@ -114,6 +114,23 @@ 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
@@ -124,6 +141,16 @@ module SchwarmCli
         }
       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/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.1"
+  VERSION = "0.1.3"
 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,235 @@
+# 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 (archived excluded by default):
+   ```bash
+   schwarm tasks list
+   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.
+- `schwarm tasks list` excludes archived tasks by default. Use `--all` to
+  include them or `--status archived` to see only archived.
+- `schwarm sessions list` shows only active sessions (pending/running) by
+  default. Use `--all` to include terminal states.
+- All list commands support `--limit N` and `--page N` for pagination. The
+  footer shows "showing N of M · page X of Y".
+- Run `schwarm skill` to print this document — useful for piping into context
+  or refreshing your knowledge of the available workflows.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: schwarm-cli
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.3
 platform: ruby
 authors:
 - Vincent Garrigues
@@ -86,6 +86,7 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- README.md
 - bin/schwarm
 - lib/schwarm_cli.rb
 - lib/schwarm_cli/client.rb
@@ -119,7 +120,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