openclacky 1.2.6 → 1.2.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a71c34a2e50f2202679cafd9c31fe7807ea5e9a6a6fad42ba352e19f9ea01282
-  data.tar.gz: 3baa2b1aed288586bec516576bf8729b630392e4e4b9aeb3b65bca704060b3d1
+  metadata.gz: '080944ed788d584c01c97ba01a27a63b2d2ab341ecf88140a63424460dcb105e'
+  data.tar.gz: 3c2b51bde81be7c18b3384297609f0163d5e6ed40de7121185a4cc374e576f10
 SHA512:
-  metadata.gz: e334e6f5e8726d02933c60d69aed8da4b98f417b1f7d0e0676b3d58bc8a15f9214317a5cde6f3ef8094f69e1fdff8cee6fb822beb076c0eef9e5544770256029
-  data.tar.gz: 76c8e019789e513382079f942dd7d4036dd68f7b6dac26822e6ec4e0dda410e8d2ad55b1ebaabd58ad388fb2cafa4fa1cb3350fc9a5673fbbb9120893c98ffd6
+  metadata.gz: c21e88b443f05ae75979ca4b890142ad15283382ba39fba434a3478f9f3a7f08b13c50fd5760d128662dee26374d69695e6b35e0d25e8f92cdad7351517f564f
+  data.tar.gz: fd37b0b3d64bc68ac777c84beef22be2c6f10c260b5e959273b953aae739c1f176bce7dae5c01c738acb332c5eded97eb973250f51576accbce58ee5f9e12139

data/CHANGELOG.md

@@ -5,6 +5,40 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.8] - 2026-06-01
+
+### Added
+- Extensibility framework: patching, shell hooks, and channel user adapter plugins — customize Clacky behavior without modifying core code
+
+### Improved
+- Billing session list now shows session names, merged deleted sessions, and standardized token breakdown with cache hit/miss color coding
+
+### Fixed
+- Streaming LLM responses automatically retry when connection drops instead of silently truncating
+
+### More
+- Extend openclacky skill with additional extension points
+
+## [1.2.7] - 2026-06-01
+
+### Added
+- Session workspace file explorer — browse and download files in Web UI sidebar
+- Channel manager: new, clear, and skill commands
+- Top-up link in Web UI under billing section
+- Sub-model switching within active sessions
+- Claude 4.8 model support
+- Connection test improvements for custom Claude models
+
+### Fixed
+- Nil error in compress top match parsing
+- Empty 0-token responses causing agent stalls (close #218)
+- Brand config built-in skills loaded without MANIFEST.enc.json (C-5627)
+- Terminal .exe stdin isolation at command-wrap on WSL (close #221)
+- Overly verbose builtin skills installed message during onboarding
+
+### More
+- Add Docker installation section to README
+
 ## [1.2.6] - 2026-05-29
 
 ### Added

data/README.md

@@ -108,6 +108,40 @@ gem install openclacky
 
 see more: https://www.openclacky.com/docs/installation
 
+### Docker
+
+Build:
+
+```bash
+git clone https://github.com/clacky-ai/openclacky.git
+cd openclacky
+docker build -t openclacky .
+```
+
+**Linux:**
+
+```bash
+docker run -d --network=host -e CLACKY_ACCESS_KEY="" openclacky
+```
+
+`--network=host` is required so the agent inside the container can reach Chrome's remote debugging port running on the host.
+
+**macOS / Windows:**
+
+```bash
+docker run -d -p 7070:7070 -e CLACKY_ACCESS_KEY="" openclacky
+```
+
+> **Note:** On macOS/Windows, `--network=host` is not supported — browser automation may be limited.
+
+Open **http://localhost:7070** after starting.
+
+Environment variables:
+
+| Variable | Description |
+|---|---|
+| `CLACKY_ACCESS_KEY` | Protect the Web UI with an access key (empty = public mode) |
+
 
 ## Quick Start
 

data/README_CN.md

@@ -104,6 +104,40 @@ gem install openclacky
 
 详见：https://www.openclacky.com/docs/installation
 
+### Docker
+
+构建：
+
+```bash
+git clone https://github.com/clacky-ai/openclacky.git
+cd openclacky
+docker build -t openclacky .
+```
+
+**Linux:**
+
+```bash
+docker run -d --network=host -e CLACKY_ACCESS_KEY="" openclacky
+```
+
+`--network=host` 使容器与宿主机共享网络栈，Agent 可直接访问宿主机上运行的 Chrome 远程调试端口。
+
+**macOS / Windows:**
+
+```bash
+docker run -d -p 7070:7070 -e CLACKY_ACCESS_KEY="" openclacky
+```
+
+> **注意：** macOS/Windows 不支持 `--network=host`，浏览器自动化功能可能受限。
+
+启动后访问 **http://localhost:7070**。
+
+环境变量：
+
+| 变量 | 说明 |
+|---|---|
+| `CLACKY_ACCESS_KEY` | 设置访问密钥保护 Web UI（留空 = 公开模式） |
+
 ## 快速开始
 
 ### 终端（CLI）

data/lib/clacky/agent/cost_tracker.rb

@@ -177,7 +177,13 @@ module Clacky
           else
             total_tokens - @previous_total_tokens
           end
-        @previous_total_tokens = total_tokens  # Update for next iteration
+
+        # Guard: do NOT overwrite @previous_total_tokens with 0 when the upstream
+        # returns missing/zero usage (observed when history overflows the model
+        # context: response comes back as content="" + finish_reason="stop" +
+        # zero usage). Resetting to 0 would disable the compression trigger on
+        # subsequent turns and poison the session permanently.
+        @previous_total_tokens = total_tokens if total_tokens > 0
 
         {
           delta_tokens: delta_tokens,

data/lib/clacky/agent/message_compressor.rb

@@ -137,7 +137,8 @@ module Clacky
     # Returns the topics string if found, nil otherwise.
     # e.g. "<topics>Rails setup, database config</topics>" → "Rails setup, database config"
     def parse_topics(content)
-      m = content.match(/<topics>(.*?)<\/topics>/m)
+      return nil if content.nil? || content.to_s.empty?
+      m = content.to_s.match(/<topics>(.*?)<\/topics>/m)
       m ? m[1].strip : nil
     end
 

data/lib/clacky/agent/message_compressor_helper.rb

@@ -124,8 +124,12 @@ module Clacky
         # Check if compression is enabled
         return nil unless @config.enable_compression
 
-        # Use actual API-reported tokens from last request
-        total_tokens = @previous_total_tokens
+        # Use the larger of: API-reported tokens from last response, or current
+        # estimated history size. The estimate guards the case where a single
+        # huge tool result was just appended after the last API call — without
+        # this, the next request can ship the bloated history before any
+        # compression triggers (issue #218).
+        total_tokens = [@previous_total_tokens, @history.estimate_tokens].max
         message_count = @history.size
 
         # Force compression (for idle compression) - use lower threshold

data/lib/clacky/agent/session_serializer.rb

@@ -80,12 +80,28 @@ module Clacky
           end
         end
 
+        # Re-apply the per-session sub-model pin (if any). Done AFTER
+        # switch_model_by_id so the overlay isn't cleared by the card switch
+        # invariant. Validation happens at write-time (the WebUI/API enforces
+        # the name belongs to the card's provider) — at restore-time we trust
+        # what we previously wrote.
+        saved_sub_model = session_data.dig(:config, :sub_model)
+        if saved_sub_model && !saved_sub_model.to_s.empty?
+          set_session_sub_model(saved_sub_model)
+        end
+
         # Rebuild and refresh the system prompt so any newly installed skills
         # (or other configuration changes since the session was saved) are
         # reflected immediately — without requiring the user to create a new session.
         refresh_system_prompt
       end
 
+      private def persisted_card_field(key)
+        card_id = @config.current_model_id
+        return nil unless card_id
+        @config.models.find { |m| m["id"] == card_id }&.dig(key)
+      end
+
       # Generate session data for saving
       # @param status [Symbol] Status of the last task: :success, :error, or :interrupted
       # @param error_message [String] Error message if status is :error
@@ -134,10 +150,13 @@ module Clacky
             reasoning_effort: @reasoning_effort,
             # Persist the current model identity so the session can restore its
             # original model on restart. model_name + model_base_url form a
-            # composite key to avoid matching a different provider's model of
-            # the same name. Falls back to default if the model no longer exists.
-            model_name: @config.current_model&.dig("model"),
-            model_base_url: @config.current_model&.dig("base_url")
+            # composite key that points at the underlying card (NOT the
+            # sub-model overlay) — overlays are layered on top via :sub_model
+            # below so card lookup stays stable when the user toggles
+            # sub-models.
+            model_name: persisted_card_field("model"),
+            model_base_url: persisted_card_field("base_url"),
+            sub_model: @config.session_model_overlay_name
           },
           stats: stats_data,
           messages: @history.to_a

data/lib/clacky/agent.rb

@@ -137,6 +137,9 @@ module Clacky
       # Register built-in tools
       register_builtin_tools
 
+      # Load declarative shell hooks from ~/.clacky/hooks.yml
+      ShellHookLoader.load_into(@hooks)
+
       # Ensure user-space parsers are in place (~/.clacky/parsers/)
       Utils::ParserManager.setup!
 
@@ -172,6 +175,18 @@ module Clacky
       true
     end
 
+    # Pin this session to a sub-model name without changing its underlying
+    # card (credentials / base_url stay put). Pass nil or "" to clear and
+    # fall back to the card's default model. Validation that the name is
+    # listed under the current provider is the caller's job.
+    # @param model_name [String, nil]
+    # @return [Boolean]
+    def set_session_sub_model(model_name)
+      @config.session_model_overlay = model_name
+      rebuild_client_for_current_model!
+      true
+    end
+
     # Rebuild the underlying Client (and dependent components) to pick up
     # credentials/model name from the currently-selected model in @config.
     private def rebuild_client_for_current_model!
@@ -206,10 +221,16 @@ module Clacky
       model = @config.current_model
       return nil unless model
 
+      card_id = @config.current_model_id
+      base_entry = card_id ? @config.models.find { |m| m["id"] == card_id } : nil
+      sub_model = @config.session_model_overlay_name
+
       {
         id: model["id"],
         model: model["model"],
-        base_url: model["base_url"]
+        base_url: model["base_url"],
+        card_model: base_entry&.dig("model"),
+        sub_model: sub_model
       }
     end
 
@@ -1019,7 +1040,10 @@ module Clacky
       check_stale!
 
       formatted_messages = @client.format_tool_results(response, tool_results, model: current_model)
-      formatted_messages.each { |msg| @history.append(msg.merge(task_id: @current_task_id)) }
+      formatted_messages.each do |msg|
+        truncated = truncate_oversized_tool_content(msg)
+        @history.append(truncated.merge(task_id: @current_task_id))
+      end
 
       # Append a follow-up `role:"user"` message for any image payloads that
       # could not be delivered inside the tool message.
@@ -1055,6 +1079,26 @@ module Clacky
       end
     end
 
+    # Cap oversized tool result content to keep a single tool message from
+    # blowing up the prompt budget (issue #218: a 7350-path glob produced a
+    # ~890k-char result that pushed history past the model context window
+    # and poisoned the session). Only string content is truncated — Array
+    # content (multipart/image blocks) is left alone since image payloads
+    # are handled by the image_inject path above.
+    MAX_TOOL_RESULT_CHARS = 80_000
+
+    private def truncate_oversized_tool_content(msg)
+      content = msg[:content]
+      return msg unless content.is_a?(String) && content.length > MAX_TOOL_RESULT_CHARS
+
+      original_len = content.length
+      head = content[0, MAX_TOOL_RESULT_CHARS]
+      truncated = head + "\n\n[Tool result truncated: #{original_len} chars total, " \
+        "showing first #{MAX_TOOL_RESULT_CHARS}. Use a more specific query/limit, " \
+        "or read the raw output via file_reader/grep on the underlying source.]"
+      msg.merge(content: truncated)
+    end
+
     # Enqueue an inline skill injection to be flushed after observe().
     # Called by InvokeSkill#execute to avoid injecting during tool execution,
     # which would break Bedrock's toolUse/toolResult pairing requirement.

data/lib/clacky/agent_config.rb

@@ -211,6 +211,14 @@ module Clacky
       # Keys honored: "api_key", "base_url", "model", "anthropic_format".
       # @return [Hash, nil]
       @virtual_model_overlay = options[:virtual_model_overlay]
+
+      # Per-session sub-model override. Persists across restarts via the
+      # session file. Independent of @virtual_model_overlay (which is for
+      # short-lived subagent forks). Used by the WebUI sub-model switcher
+      # to pin a session to e.g. "dsk-deepseek-v4-pro" while the underlying
+      # card still says "abs-claude-sonnet-4-6". Only the "model" key is
+      # honored — sub-model switching never changes credentials.
+      @session_model_overlay = options[:session_model_overlay]
     end
 
     # Load configuration from file
@@ -354,6 +362,9 @@ module Clacky
       if @virtual_model_overlay
         copy.instance_variable_set(:@virtual_model_overlay, @virtual_model_overlay.dup)
       end
+      if @session_model_overlay
+        copy.instance_variable_set(:@session_model_overlay, @session_model_overlay.dup)
+      end
       copy
     end
 
@@ -431,9 +442,12 @@ module Clacky
       index = @models.find_index { |m| m["id"] == id }
       return false if index.nil?
 
+      previous_id = @current_model_id
       @current_model_id = id
       @current_model_index = index
 
+      @session_model_overlay = nil if previous_id != id
+
       true
     end
 
@@ -760,14 +774,18 @@ module Clacky
       resolved = resolve_current_model_entry
       return nil unless resolved
 
-      # If a virtual overlay is active (e.g. subagent running on lite-model
-      # credentials), return a *merged copy* so callers see the overlay fields
-      # but the shared @models hash is never mutated.
+      # Merge order (low → high): base entry, session-level sub-model override,
+      # then short-lived subagent overlay. Both layers are kept separate so
+      # a subagent fork can stack its own credentials on top of an active
+      # sub-model pin without erasing it.
+      merged = resolved
+      if @session_model_overlay && !@session_model_overlay.empty?
+        merged = merged.merge(@session_model_overlay)
+      end
       if @virtual_model_overlay && !@virtual_model_overlay.empty?
-        resolved.merge(@virtual_model_overlay)
-      else
-        resolved
+        merged = merged.merge(@virtual_model_overlay)
       end
+      merged.equal?(resolved) ? resolved : merged
     end
 
     # Internal: resolve the current model entry from @models (no overlay).
@@ -822,6 +840,36 @@ module Clacky
       @virtual_model_overlay
     end
 
+    # Apply a session-level sub-model override. Lives on this AgentConfig
+    # only (each session deep_copy's its own scalar ivar) and survives a
+    # restart through the session file. Pass nil or "" to clear.
+    #
+    # The override only rewrites the resolved current_model's "model" field —
+    # api_key / base_url / anthropic_format come from the underlying card,
+    # so the user's credentials and provider identity are untouched.
+    #
+    # @param model_name [String, nil] sub-model name, e.g. "dsk-deepseek-v4-pro"
+    def session_model_overlay=(model_name)
+      if model_name.nil? || model_name.to_s.strip.empty?
+        @session_model_overlay = nil
+      else
+        @session_model_overlay = { "model" => model_name.to_s.strip }
+      end
+    end
+
+    # @return [Hash, nil] the active session sub-model overlay
+    def session_model_overlay
+      @session_model_overlay
+    end
+
+    # Convenience accessor: the sub-model name currently pinned on this
+    # session, or nil when no override is active. Used by serializers and
+    # the WebUI to surface "card · sub-model" two-line displays.
+    # @return [String, nil]
+    def session_model_overlay_name
+      @session_model_overlay && @session_model_overlay["model"]
+    end
+
     # Query whether the *current* model supports a given capability.
     #
     # This is the single entry-point callers (Agent, downgrade pipeline, UI)

data/lib/clacky/billing/billing_store.rb

@@ -4,7 +4,7 @@ require "json"
 require "fileutils"
 require "securerandom"
 require_relative "billing_record"
-
+require_relative "../session_manager"
 module Clacky
   module Billing
     # Persistent storage for billing records using JSONL files
@@ -115,8 +115,112 @@ module Clacky
         }
       end
 
-      # Get daily cost breakdown for the last N days
-      # @param days [Integer] Number of days to include
+      # Get session-level summary statistics
+      # @param period [Symbol] :day, :week, :month, :year, or :all
+      # @param model [String, nil] Filter by model name
+      # @param limit [Integer] Maximum number of sessions to return
+      # @return [Array<Hash>] Session summaries sorted by cost descending
+      def session_summary(period: :month, model: nil, limit: 50)
+        from_time = period_start(period)
+        records = query(from: from_time, model: model)
+
+        # Load session names from session manager
+        session_names = load_session_names
+
+        # Group by session_id
+        by_session = records.group_by { |r| r.session_id || "unknown" }
+
+        active_sessions = []
+        deleted_records = []
+
+        by_session.each do |session_id, rs|
+          total_cost = rs.sum { |r| r.cost_usd || 0 }
+          total_prompt = rs.sum { |r| r.prompt_tokens || 0 }
+          total_completion = rs.sum { |r| r.completion_tokens || 0 }
+          total_cache_read = rs.sum { |r| r.cache_read_tokens || 0 }
+          total_cache_write = rs.sum { |r| r.cache_write_tokens || 0 }
+          first_record = rs.min_by { |r| r.timestamp }
+          last_record = rs.max_by { |r| r.timestamp }
+
+          entry = {
+            session_id: session_id,
+            session_name: session_names[session_id],
+            total_cost: total_cost.round(6),
+            total_tokens: total_prompt + total_completion,
+            prompt_tokens: total_prompt,
+            completion_tokens: total_completion,
+            cache_read_tokens: total_cache_read,
+            cache_write_tokens: total_cache_write,
+            requests: rs.size,
+            first_request: first_record&.timestamp&.iso8601,
+            last_request: last_record&.timestamp&.iso8601,
+            models: rs.map(&:model).uniq
+          }
+
+          if session_names[session_id]
+            active_sessions << entry
+          else
+            deleted_records << entry
+          end
+        end
+
+        # Merge all deleted sessions into a single row
+        if deleted_records.any?
+          merged = {
+            session_id: "_deleted_",
+            session_name: nil,
+            is_deleted: true,
+            total_cost: deleted_records.sum { |r| r[:total_cost] }.round(6),
+            total_tokens: deleted_records.sum { |r| r[:total_tokens] },
+            prompt_tokens: deleted_records.sum { |r| r[:prompt_tokens] },
+            completion_tokens: deleted_records.sum { |r| r[:completion_tokens] },
+            cache_read_tokens: deleted_records.sum { |r| r[:cache_read_tokens] },
+            cache_write_tokens: deleted_records.sum { |r| r[:cache_write_tokens] },
+            requests: deleted_records.sum { |r| r[:requests] },
+            first_request: deleted_records.map { |r| r[:first_request] }.compact.min,
+            last_request: deleted_records.map { |r| r[:last_request] }.compact.max,
+            models: deleted_records.flat_map { |r| r[:models] }.uniq
+          }
+          active_sessions << merged
+        end
+
+        # Sort by total cost descending
+        active_sessions.sort_by! { |s| -s[:total_cost] }
+
+        # Apply limit
+        limit ? active_sessions.first(limit) : active_sessions
+      end
+
+      # Load session names from session manager (including trashed sessions)
+      # Returns a hash mapping session_id to session name
+      def load_session_names
+        names = {}
+        begin
+          # Load from active sessions
+          manager = Clacky::SessionManager.new
+          manager.all_sessions.each do |session|
+            id = session[:session_id]
+            name = session[:name]
+            names[id] = name if id && name && !name.to_s.empty?
+          end
+
+          # Also load from trashed sessions
+          trash_dir = File.join(Dir.home, ".clacky", "trash", "sessions-trash")
+          if Dir.exist?(trash_dir)
+            Dir.glob(File.join(trash_dir, "*.json")).each do |filepath|
+              session = JSON.parse(File.read(filepath), symbolize_names: true) rescue next
+              id = session[:session_id]
+              name = session[:name]
+              names[id] = name if id && name && !name.to_s.empty?
+            end
+          end
+        rescue => e
+          # Silently fail if session manager is not available
+        end
+        names
+      end
+
+      # Get daily cost breakdown for the last N days      # @param days [Integer] Number of days to include
       # @param model [String, nil] Filter by model name
       # @return [Array<Hash>] Daily summaries with date and cost
       def daily_breakdown(days: 30, model: nil)

data/lib/clacky/brand_config.rb

@@ -783,12 +783,6 @@ module Clacky
 
       FileUtils.rm_f(tmp_zip)
 
-      if encrypted
-        manifest_path = File.join(dest_dir, "MANIFEST.enc.json")
-        raise "MANIFEST.enc.json missing after extraction" unless File.exist?(manifest_path)
-        JSON.parse(File.read(manifest_path))
-      end
-
       record_installed_skill(slug, version, skill_info["description"],
                              encrypted: encrypted,
                              description_zh: skill_info["description_zh"],

data/lib/clacky/cli.rb

@@ -559,7 +559,8 @@ module Clacky
         else
           error_message = format_error(exception)
           session_manager&.save(agent.to_session_data(status: :error, error_message: error_message))
-          ui_controller.show_error("Error: #{exception.message}")
+          code = exception.is_a?(Clacky::InsufficientCreditError) ? exception.error_code : nil
+          ui_controller.show_error("Error: #{exception.message}", code: code)
         end
       end
 
@@ -941,6 +942,111 @@ module Clacky
     end
 
     # ── billing command ────────────────────────────────────────────────────────
+    desc "patch_new ID TARGET", "Scaffold a runtime patch for a method (TARGET like Clacky::Tools::WebSearch#execute)"
+    long_desc <<-LONGDESC
+      Generate a method-override patch under ~/.clacky/patches/ID/. The current
+      method fingerprint is computed automatically and stored in meta.yml; you
+      only edit the method body in patch.rb. If a future gem version changes the
+      targeted method, the fingerprint will no longer match and the patch is
+      auto-disabled on next start (rather than applied and risking breakage).
+
+      Examples:
+        $ clacky patch_new fix-search Clacky::Tools::WebSearch#execute -d "bump timeout"
+    LONGDESC
+    option :desc, type: :string, aliases: "-d", default: "", desc: "Short description"
+    def patch_new(id, target)
+      require_relative "patch_loader"
+      path = Clacky::PatchLoader.scaffold(id, target, description: options[:desc])
+      puts "Created patch: #{path}"
+      puts "Edit patch.rb, then run: clacky patch_verify"
+    rescue ArgumentError, StandardError => e
+      warn "Error: #{e.message}"
+      exit 1
+    end
+
+    desc "patch_verify", "Load ~/.clacky/patches/ and report applied / disabled / skipped"
+    def patch_verify
+      require "clacky"
+      result = Clacky::PatchLoader.last_result
+
+      if result.applied.empty? && result.disabled.empty? && result.skipped.empty?
+        puts "No patches found in ~/.clacky/patches/"
+        return
+      end
+
+      result.applied.each  { |id| puts "[OK]       #{id}" }
+      result.disabled.each { |(id, reason)| puts "[DISABLED] #{id} — #{reason}" }
+      result.skipped.each  { |(id, reason)| puts "[SKIP]     #{id} — #{reason}" }
+      exit 1 if result.skipped.any?
+    end
+
+    desc "patch_list", "List patches under ~/.clacky/patches/ and their status"
+    def patch_list
+      invoke :patch_verify, []
+    end
+
+    desc "hook_new", "Scaffold a starter ~/.clacky/hooks.yml with an example guard script"
+    def hook_new
+      require_relative "shell_hook_loader"
+      path = Clacky::ShellHookLoader.scaffold
+      puts "Created hooks config: #{path}"
+      puts "Edit it, then run: clacky hook_verify"
+    rescue ArgumentError => e
+      warn "Error: #{e.message}"
+      exit 1
+    end
+
+    desc "hook_verify", "Load ~/.clacky/hooks.yml and report which hooks register"
+    def hook_verify
+      require_relative "agent/hook_manager"
+      require_relative "shell_hook_loader"
+      hm = Clacky::HookManager.new
+      result = Clacky::ShellHookLoader.load_into(hm)
+
+      if result.registered.empty? && result.skipped.empty?
+        puts "No hooks found in ~/.clacky/hooks.yml"
+        return
+      end
+
+      result.registered.each { |(event, name)| puts "[OK]   #{event} → #{name}" }
+      result.skipped.each { |(name, reason)| puts "[SKIP] #{name} — #{reason}" }
+      exit 1 if result.skipped.any?
+    end
+
+    desc "channel_new NAME", "Scaffold a custom channel adapter at ~/.clacky/channels/NAME/"
+    long_desc <<-LONGDESC
+      Generate a ready-to-edit channel adapter skeleton. The skeleton already
+      self-registers and implements the full adapter interface with TODO markers —
+      you only fill in the method bodies, then run `clacky channel_verify`.
+
+      Examples:
+        $ clacky channel_new slack
+    LONGDESC
+    def channel_new(name)
+      require_relative "server/channel"
+      path = Clacky::Channel::Adapters::UserAdapterLoader.scaffold(name)
+      puts "Created channel adapter: #{path}"
+      puts "Edit the TODO sections, then run: clacky channel_verify"
+    rescue ArgumentError => e
+      warn "Error: #{e.message}"
+      exit 1
+    end
+
+    desc "channel_verify", "Load user channel adapters and report which are valid"
+    def channel_verify
+      require_relative "server/channel"
+      result = Clacky::Channel::Adapters::UserAdapterLoader.last_result
+
+      if result.loaded.empty? && result.skipped.empty?
+        puts "No custom channel adapters found in ~/.clacky/channels/"
+        return
+      end
+
+      result.loaded.each { |n| puts "[OK]   #{n}" }
+      result.skipped.each { |(n, reason)| puts "[SKIP] #{n} — #{reason}" }
+      exit 1 if result.skipped.any?
+    end
+
     desc "billing", "Show billing summary and usage statistics"
     long_desc <<-LONGDESC
       Display billing summary with token usage and cost breakdown.