openclacky 0.9.4 → 0.9.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a9c12ba4b5e244e6dbbec7d723dc6d0f9c7e4e4523a82bafbb96f668e7b1a0f4
-  data.tar.gz: 5d6e7d71829aa2bafbe68dc825b6ec0e7bd4c1ad004804d43ef9121a46fa6671
+  metadata.gz: a499294341fb7b3fd0f4884ecc672705317c1f33d4ead1531ebdd34465a8f5f8
+  data.tar.gz: a2c023146c5ed2b91c0777e31266800ff933fd053bee146430c0587cc8fc1999
 SHA512:
-  metadata.gz: 1dd7ede95260c506b7dfb89cd5596ea4ba9ac4e6949e17067b84ec6a9a2686892a27fafd1e25bf80a6c0ade211f398c3f6b8ab87d3e7167ea808fe88398f46be
-  data.tar.gz: 38771322fb7651494b4595d82e315a3a6ddf902ae3bf4141d4ea01a63a65ffd1c9adb1dcf91da43d29ead77f673025e1559d0ad688fafbfa7673738dcf393052
+  metadata.gz: 32640a8ff88ebfe3c37f69c9362c6935a876515a30a9fbff14d6496af6dbc2ec3c0df227db4a62d362c80d44a117f63e5c0ce48dc96f4229d1a03c1761b01eae
+  data.tar.gz: 72ed3bf45504176b76904cbeb90bcf32e5606c65405deb4b26fa3e6923e1e977c99615f5221d27a318e7585c5831523770ddae97b23affc2306efc2ef00fa9e4

data/CHANGELOG.md

@@ -7,6 +7,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.6] - 2026-03-18
+
+### Added
+- **Environment-aware context injection**: the agent now automatically detects your OS, desktop environment, and screen info and includes it in every session — so it can give OS-specific advice without you having to explain your setup
+- **File attachments via IM channels**: you can now send images and documents directly through Feishu or WeCom to the agent, which processes them just like files sent via the Web UI
+- **Unified file attachment pipeline for Web UI**: images and Office/PDF documents can now be attached in the web chat interface with automatic image compression before upload
+- **Skills can now be installed from local zip files**: `skill-add` now accepts a local file path (not just a URL), so you can install skills from a downloaded zip without hosting it anywhere
+- **Skill import bar in Web UI**: the Skills settings page now has an import bar where you can paste a URL or upload a local zip file directly — no terminal needed to install new skills
+- **`$SKILL_DIR` available in skill instructions**: skill files can now reference `$SKILL_DIR` to get the absolute path to their own directory, making it easy to reference supporting files with correct paths
+- **`product-help` built-in skill**: the agent can now answer questions about Clacky's own features, configuration, and usage through a dedicated built-in skill
+
+### Fixed
+- **PDF and Office files now appear in glob results**: file discovery tools no longer skip `.pdf`, `.docx`, and other document formats — they show up correctly in file listings
+- **Chat history visible after message compression**: sessions where all user messages were compressed no longer show a blank history — prior conversation is now correctly replayed
+- **Stale message reference in task history**: an internal bug (`@messages` vs `@history`) that could cause incorrect task history in compressed sessions is fixed
+- **File-only messages handled correctly in channel UI**: sending a file without text via IM channels no longer causes a display issue in the channel UI
+- **WeCom WebSocket client stability**: fixed async dispatch and frame acknowledgment in the WeCom WS client to reduce dropped messages and connection issues
+- **Session serializer variable fix**: corrected a stale variable reference in session replay that could cause errors when restoring sessions
+- **`web_fetch` compatibility improved**: better request headers make web page fetching more reliable across more sites
+- **Reasoning content preserved in API messages**: `reasoning_content` fields are no longer stripped from messages, fixing potential issues with reasoning-capable models
+
+### More
+- Markdown links in chat now open in a new tab
+- Removed public skill store tab from the Skills panel (store content is now integrated differently)
+- Reduce WebSocket ping log noise in HTTP server
+- Centralize message cleanup logic in `MessageHistory`
+
+## [0.9.5] - 2026-03-17
+
+### Added
+- **License activation now navigates directly to Brand Skills tab**: after entering a valid license key, the UI automatically opens the Brand Skills settings tab — no extra steps needed to find and load your skills
+- **Version badge always clickable**: clicking the version number in the sidebar now always works regardless of update state; when already on the latest version, a small "up to date" popover appears and auto-dismisses
+
+### Improved
+- **MessageHistory domain object**: agent message handling is now encapsulated in a dedicated `MessageHistory` class, making the codebase cleaner and message operations (compression, caching, transient marking) more reliable and testable
+- **Brand skill isolation via transient message marking**: brand skill subagent calls no longer spin up a separate isolated agent; instead, messages are marked as transient and stripped after the call — simpler architecture with the same isolation guarantees
+- **License activation flow simplified**: the `activate-license` skill is replaced with direct in-UI navigation and settings highlighting, reducing round-trips and making activation feel more native
+
+### Fixed
+- **Tilde (`~`) in file paths now expanded correctly**: tool preview checks now expand `~` to the home directory before checking file existence, so paths like `~/Documents/file.txt` no longer falsely report as missing
+- **Subagent with empty arguments no longer crashes**: when a skill invocation passes empty arguments, a safe placeholder message is used instead of raising an error
+- **Version popover shows "up to date" state**: clicking the version badge when already on the latest version now shows a friendly confirmation instead of silently falling through to open the settings panel
+
+### More
+- Simplify error messages in brand config decryption
+- Update test matchers to match simplified error messages
+
 ## [0.9.4] - 2026-03-16
 
 ### Fixed

data/lib/clacky/agent/cost_tracker.rb

@@ -125,7 +125,7 @@ module Clacky
         tool_tokens = 0
         summary_tokens = 0
 
-        @messages.each do |msg|
+        @history.to_a.each do |msg|
           tokens = estimate_tokens(msg[:content])
           case msg[:role]
           when "system"

data/lib/clacky/agent/llm_caller.rb

@@ -19,9 +19,14 @@ module Clacky
         retries = 0
 
         begin
-          # Use active_messages to filter out "future" messages after undo
-          messages_to_send = respond_to?(:active_messages) ? active_messages : @messages
-          
+          # Use active_messages (Time Machine) when undone, otherwise send full history.
+          # to_api strips internal fields and handles orphaned tool_calls.
+          messages_to_send = if respond_to?(:active_messages)
+            active_messages
+          else
+            @history.to_api
+          end
+
           response = @client.send_messages_with_tools(
             messages_to_send,
             model: current_model,
@@ -40,6 +45,17 @@ module Clacky
             @ui&.show_error("Network failed after #{max_retries} retries: #{e.message}")
             raise AgentError, "Network connection failed after #{max_retries} retries: #{e.message}"
           end
+        rescue RetryableError => e
+          @ui&.clear_progress
+          retries += 1
+          if retries <= max_retries
+            @ui&.show_warning("#{e.message} (#{retries}/#{max_retries})")
+            sleep retry_delay
+            retry
+          else
+            @ui&.show_error("LLM service unavailable after #{max_retries} retries. Please try again later.")
+            raise AgentError, "LLM service unavailable after #{max_retries} retries"
+          end
         ensure
           @ui&.clear_progress
         end

data/lib/clacky/agent/memory_updater.rb

@@ -44,12 +44,12 @@ module Clacky
         @memory_updating = true
         @ui&.show_progress("Updating long-term memory…")
 
-        @messages << {
+        @history.append({
           role: "user",
           content: build_memory_update_prompt,
           system_injected: true,
           memory_update: true
-        }
+        })
 
         true
       end
@@ -59,7 +59,7 @@ module Clacky
       def cleanup_memory_messages
         return unless @memory_prompt_injected
 
-        @messages.reject! { |m| m[:memory_update] }
+        @history.delete_where { |m| m[:memory_update] }
         @memory_prompt_injected = false
         @memory_updating = false
         @ui&.clear_progress

data/lib/clacky/agent/message_compressor_helper.rb

@@ -24,7 +24,8 @@ module Clacky
         end
 
         # Insert compression message
-        @messages << compression_context[:compression_message]
+        compression_message = compression_context[:compression_message]
+        @history.append(compression_message)
 
         begin
           # Execute compression using shared LLM call logic
@@ -33,13 +34,11 @@ module Clacky
           true
         rescue Clacky::AgentInterrupted => e
           @ui&.log("Idle compression canceled: #{e.message}", level: :info)
-          # Remove the compression message we added
-          @messages.pop if @messages.last == compression_context[:compression_message]
+          @history.rollback_before(compression_message)
           false
         rescue => e
           @ui&.log("Idle compression failed: #{e.message}", level: :error)
-          # Remove the compression message we added
-          @messages.pop if @messages.last == compression_context[:compression_message]
+          @history.rollback_before(compression_message)
           false
         end
       end
@@ -53,7 +52,7 @@ module Clacky
 
         # Calculate total tokens and message count
         total_tokens = total_message_tokens[:total]
-        message_count = @messages.length
+        message_count = @history.size
 
         # Force compression (for idle compression) - use lower threshold
         if force
@@ -90,11 +89,12 @@ module Clacky
         @compression_level += 1
 
         # Get the most recent N messages, ensuring tool_calls/tool results pairs are kept together
-        recent_messages = get_recent_messages_with_tool_pairs(@messages, target_recent_count)
+        all_messages = @history.to_a
+        recent_messages = get_recent_messages_with_tool_pairs(all_messages, target_recent_count)
         recent_messages = [] if recent_messages.nil?
 
         # Build compression instruction message (to be inserted into conversation)
-        compression_message = @message_compressor.build_compression_message(@messages, recent_messages: recent_messages)
+        compression_message = @message_compressor.build_compression_message(all_messages, recent_messages: recent_messages)
 
         return nil if compression_message.nil?
 
@@ -103,7 +103,7 @@ module Clacky
           compression_message: compression_message,
           recent_messages: recent_messages,
           original_token_count: total_tokens,
-          original_message_count: @messages.length,
+          original_message_count: @history.size,
           compression_level: @compression_level
         }
       end
@@ -117,7 +117,7 @@ module Clacky
 
         # Rebuild message list with compression
         # Note: we need to remove the compression instruction message we just added
-        original_messages = @messages[0..-2]  # All except the last (compression instruction)
+        original_messages = @history.to_a[0..-2]  # All except the last (compression instruction)
 
         # Archive compressed messages to a chunk MD file before discarding them
         chunk_index = @compressed_summaries.size + 1
@@ -128,12 +128,12 @@ module Clacky
           compression_level: compression_context[:compression_level]
         )
 
-        @messages = @message_compressor.rebuild_with_compression(
+        @history.replace_all(@message_compressor.rebuild_with_compression(
           compressed_content,
           original_messages: original_messages,
           recent_messages: compression_context[:recent_messages],
           chunk_path: chunk_path
-        )
+        ))
 
         # Track this compression
         @compressed_summaries << {

data/lib/clacky/agent/session_serializer.rb

@@ -10,7 +10,7 @@ module Clacky
       def restore_session(session_data)
         @session_id = session_data[:session_id]
         @name = session_data[:name] || ""
-        @messages = session_data[:messages]
+        @history = MessageHistory.new(session_data[:messages] || [])
         @todos = session_data[:todos] || []  # Restore todos from session
         @iterations = session_data.dig(:stats, :total_iterations) || 0
         @total_cost = session_data.dig(:stats, :total_cost_usd) || 0.0
@@ -39,13 +39,11 @@ module Clacky
         last_error = session_data.dig(:stats, :last_error)
 
         if last_status == "error" && last_error
-          # Find and remove the last user message that caused the error
-          # This allows the user to retry with a different prompt
-          last_user_index = @messages.rindex { |m| m[:role] == "user" }
+          # Trim back to just before the last real user message that caused the error
+          last_user_index = @history.last_real_user_index
           if last_user_index
-            @messages = @messages[0...last_user_index]
+            @history.truncate_from(last_user_index)
 
-            # Trigger a hook to notify about the rollback
             @hooks.trigger(:session_rollback, {
               reason: "Previous session ended with error",
               error_message: last_error,
@@ -92,7 +90,8 @@ module Clacky
             active_task_id: @active_task_id || 0
           },
           config: {
-            models: @config.models,
+            # NOTE: api_key and other sensitive credentials are intentionally excluded
+            # to prevent leaking secrets into session files on disk.
             permission_mode: @config.permission_mode.to_s,
             enable_compression: @config.enable_compression,
             enable_prompt_caching: @config.enable_prompt_caching,
@@ -100,7 +99,7 @@ module Clacky
             verbose: @config.verbose
           },
           stats: stats_data,
-          messages: @messages
+          messages: @history.to_a
         }
       end
 
@@ -108,13 +107,7 @@ module Clacky
       # @param limit [Integer] Number of recent user messages to retrieve (default: 5)
       # @return [Array<String>] Array of recent user message contents
       def get_recent_user_messages(limit: 5)
-        # Filter messages to only include real user messages (exclude system-injected ones)
-        user_messages = @messages.select do |m|
-          m[:role] == "user" && !m[:system_injected]
-        end
-
-        # Extract text content from the last N user messages
-        user_messages.last(limit).map do |msg|
+        @history.real_user_messages.last(limit).map do |msg|
           extract_text_from_content(msg[:content])
         end
       end
@@ -129,11 +122,11 @@ module Clacky
       #   created_at < before. Pass nil to get the most recent rounds.
       # @return [Hash] { has_more: Boolean } — whether older rounds exist beyond this page
       def replay_history(ui, limit: 20, before: nil)
-        # Split @messages into rounds, each starting at a real user message
+        # Split @history into rounds, each starting at a real user message
         rounds = []
         current_round = nil
 
-        @messages.each do |msg|
+        @history.to_a.each do |msg|
           role = msg[:role].to_s
 
           # A real user message can have either a String content or an Array content
@@ -163,62 +156,31 @@ module Clacky
           rounds = rounds.select { |r| r[:user_msg][:created_at] && r[:user_msg][:created_at] < before }
         end
 
+        # Fallback: when the conversation was compressed and no user messages remain in the
+        # kept slice, render the surviving assistant/tool messages directly so the user can
+        # still see the last visible state of the chat (e.g. compressed summary + recent work).
+        if rounds.empty?
+          visible = @history.to_a.reject { |m| m[:role].to_s == "system" || m[:system_injected] }
+          visible.each { |msg| _replay_single_message(msg, ui) }
+          return { has_more: false }
+        end
+
         has_more = rounds.size > limit
         # Take the most recent `limit` rounds
         page = rounds.last(limit)
 
         page.each do |round|
           msg = round[:user_msg]
-          display_text = extract_text_from_content(msg[:content])
-          # Extract image data URLs from multipart content (for history replay rendering)
-          images = extract_images_from_content(msg[:content])
-          # Emit user message with its timestamp for dedup on the frontend
-          ui.show_user_message(display_text, created_at: msg[:created_at], images: images)
+          raw_text = extract_text_from_content(msg[:content])
+          # Files are stored as system_injected messages (skipped below), not embedded in user text.
+          ui.show_user_message(raw_text, created_at: msg[:created_at])
 
           round[:events].each do |ev|
             # Skip system-injected messages (e.g. synthetic skill content, memory prompts)
             # — they are internal scaffolding and must not be shown to the user.
             next if ev[:system_injected]
 
-            case ev[:role].to_s
-            when "assistant"
-              # Text content
-              text = extract_text_from_content(ev[:content]).to_s.strip
-              ui.show_assistant_message(text) unless text.empty?
-
-              # Tool calls embedded in assistant message
-              Array(ev[:tool_calls]).each do |tc|
-                name     = tc[:name] || tc.dig(:function, :name) || ""
-                args_raw = tc[:arguments] || tc.dig(:function, :arguments) || {}
-                args     = args_raw.is_a?(String) ? (JSON.parse(args_raw) rescue args_raw) : args_raw
-
-                # Special handling: request_user_feedback question is shown as an
-                # assistant message (matching real-time behavior), not as a tool call.
-                if name == "request_user_feedback"
-                  question = args.is_a?(Hash) ? (args[:question] || args["question"]).to_s : ""
-                  ui.show_assistant_message(question) unless question.empty?
-                else
-                  ui.show_tool_call(name, args)
-                end
-              end
-
-              # Emit token usage stored on this message (for history replay display)
-              ui.show_token_usage(ev[:token_usage]) if ev[:token_usage]
-
-            when "user"
-              # Anthropic-format tool results (role: user, content: array of tool_result blocks)
-              next unless ev[:content].is_a?(Array)
-
-              ev[:content].each do |blk|
-                next unless blk.is_a?(Hash) && blk[:type] == "tool_result"
-
-                ui.show_tool_result(blk[:content].to_s)
-              end
-
-            when "tool"
-              # OpenAI-format tool result
-              ui.show_tool_result(ev[:content].to_s)
-            end
+            _replay_single_message(ev, ui)
           end
         end
 
@@ -227,6 +189,52 @@ module Clacky
 
       private
 
+      # Render a single non-user message into the UI.
+      # Used by both the normal round-based replay and the compressed-session fallback.
+      def _replay_single_message(msg, ui)
+        return if msg[:system_injected]
+
+        case msg[:role].to_s
+        when "assistant"
+          # Text content
+          text = extract_text_from_content(msg[:content]).to_s.strip
+          ui.show_assistant_message(text, files: []) unless text.empty?
+
+          # Tool calls embedded in assistant message
+          Array(msg[:tool_calls]).each do |tc|
+            name     = tc[:name] || tc.dig(:function, :name) || ""
+            args_raw = tc[:arguments] || tc.dig(:function, :arguments) || {}
+            args     = args_raw.is_a?(String) ? (JSON.parse(args_raw) rescue args_raw) : args_raw
+
+            # Special handling: request_user_feedback question is shown as an
+            # assistant message (matching real-time behavior), not as a tool call.
+            if name == "request_user_feedback"
+              question = args.is_a?(Hash) ? (args[:question] || args["question"]).to_s : ""
+              ui.show_assistant_message(question, files: []) unless question.empty?
+            else
+              ui.show_tool_call(name, args)
+            end
+          end
+
+          # Emit token usage stored on this message (for history replay display)
+          ui.show_token_usage(msg[:token_usage]) if msg[:token_usage]
+
+        when "user"
+          # Anthropic-format tool results (role: user, content: array of tool_result blocks)
+          return unless msg[:content].is_a?(Array)
+
+          msg[:content].each do |blk|
+            next unless blk.is_a?(Hash) && blk[:type] == "tool_result"
+
+            ui.show_tool_result(blk[:content].to_s)
+          end
+
+        when "tool"
+          # OpenAI-format tool result
+          ui.show_tool_result(msg[:content].to_s)
+        end
+      end
+
       # Replace the system message in @messages with a freshly built system prompt.
       # Called after restore_session so newly installed skills and any other
       # configuration changes since the session was saved take effect immediately.
@@ -237,13 +245,7 @@ module Clacky
         @skill_loader.load_all
 
         fresh_prompt = build_system_prompt
-        system_index = @messages.index { |m| m[:role] == "system" }
-
-        if system_index
-          @messages[system_index] = { role: "system", content: fresh_prompt }
-        else
-          @messages.unshift({ role: "system", content: fresh_prompt })
-        end
+        @history.replace_system_prompt(fresh_prompt)
       rescue StandardError => e
         # Log and continue — a stale system prompt is better than a broken restore
         Clacky::Logger.warn("refresh_system_prompt failed during session restore: #{e.message}")

data/lib/clacky/agent/skill_manager.rb

@@ -155,9 +155,8 @@ module Clacky
         skill = parsed[:skill]
         arguments = parsed[:arguments]
 
-        # Encrypted brand skills and fork-agent skills must run in an isolated subagent.
-        # Injecting their plaintext into @messages would expose confidential content to the LLM.
-        if skill.encrypted? || skill.fork_agent?
+        # fork_agent skills still run in an isolated subagent.
+        if skill.fork_agent?
           execute_skill_with_subagent(skill, arguments)
           return
         end
@@ -173,23 +172,31 @@ module Clacky
         # real LLM call would find an assistant message at the tail of the history,
         # causing a 400 "invalid message order" error.
         #
+        # For encrypted (brand) skills, both injected messages are marked transient: true
+        # so they are excluded from session.json serialization. The LLM sees the content
+        # during the current session, but it is never persisted to disk.
+        #
         # Final message order:
         #   user:      "/skill-name [args]"          ← real user input
         #   assistant: "[expanded skill content]"    ← system_injected (skill instructions)
         #   user:      "[SYSTEM] Please proceed..."  ← system_injected (Claude compat shim)
-        @messages << {
+        transient = skill.encrypted?
+
+        @history.append({
           role: "assistant",
           content: expanded_content,
           task_id: task_id,
-          system_injected: true
-        }
+          system_injected: true,
+          transient: transient
+        })
 
-        @messages << {
+        @history.append({
           role: "user",
           content: "[SYSTEM] The skill instructions above have been loaded. Please proceed to execute the task now.",
           task_id: task_id,
-          system_injected: true
-        }
+          system_injected: true,
+          transient: transient
+        })
 
         @ui&.show_info("Injected skill content for /#{skill.identifier}")
       end
@@ -293,21 +300,21 @@ module Clacky
           system_prompt_suffix: skill_instructions
         )
 
-        # Run subagent with the actual task as the sole user turn
-        result = subagent.run(arguments)
+        # Run subagent with the actual task as the sole user turn.
+        # If the user typed the skill command with no arguments (e.g. "/jade-appraisal"),
+        # use a generic trigger phrase so the user message is never empty.
+        task_input = arguments.to_s.strip.empty? ? "Please proceed." : arguments
+        result = subagent.run(task_input)
 
         # Generate summary
         summary = generate_subagent_summary(subagent)
 
-        # Insert summary back to parent agent messages (replacing the instruction message)
-        # Find and replace the last message with subagent_instructions flag
-        messages_with_instructions = @messages.select { |m| m[:subagent_instructions] }
-        if messages_with_instructions.any?
-          instruction_msg = messages_with_instructions.last
-          instruction_msg[:content] = summary
-          instruction_msg.delete(:subagent_instructions)
-          instruction_msg[:subagent_result] = true
-          instruction_msg[:skill_name] = skill.identifier
+        # Mutate the subagent_instructions message in-place to become the result summary
+        @history.mutate_last_matching(->(m) { m[:subagent_instructions] }) do |m|
+          m[:content] = summary
+          m.delete(:subagent_instructions)
+          m[:subagent_result] = true
+          m[:skill_name] = skill.identifier
         end
 
         # Log completion

data/lib/clacky/agent/time_machine.rb

@@ -90,15 +90,15 @@ module Clacky
         raise
       end
 
-      # Filter messages to only show tasks up to active_task_id
-      # This hides "future" messages when user has undone
+      # Filter messages to only show tasks up to active_task_id.
+      # This hides "future" messages when user has undone.
+      # Returns API-ready array (strips internal fields + handles orphaned tool_calls).
       # Made public for testing
       def active_messages
-        return @messages if @active_task_id == @current_task_id
-        
-        @messages.select do |msg|
-          msg_task_id = msg[:task_id] || 0
-          msg_task_id <= @active_task_id
+        return @history.to_api if @active_task_id == @current_task_id
+
+        @history.for_task(@active_task_id).map do |msg|
+          msg.reject { |k, _| MessageHistory::INTERNAL_FIELDS.include?(k) }
         end
       end
 
@@ -147,7 +147,7 @@ module Clacky
         tasks = []
         (1..@current_task_id).to_a.reverse.take(limit).reverse.each do |task_id|
           # Find first user message for this task
-          first_user_msg = @messages.find do |msg|
+          first_user_msg = @history.to_a.find do |msg|
             msg[:task_id] == task_id && msg[:role] == "user"
           end
 

data/lib/clacky/agent/tool_executor.rb

@@ -346,15 +346,17 @@ module Clacky
       # @return [nil] Always returns nil (no errors for write)
       private def show_write_preview(args)
         path = args[:path] || args['path']
+        # Expand ~ to home directory so File.exist? works correctly
+        expanded_path = path&.start_with?("~") ? File.expand_path(path) : path
         new_content = args[:content] || args['content'] || ""
 
-        is_new_file = !(path && File.exist?(path))
+        is_new_file = !(expanded_path && File.exist?(expanded_path))
         @ui&.show_file_write_preview(path, is_new_file: is_new_file)
 
         if is_new_file
           @ui&.show_diff("", new_content, max_lines: 50)
         else
-          old_content = File.read(path)
+          old_content = File.read(expanded_path)
           @ui&.show_diff(old_content, new_content, max_lines: 50)
         end
         nil
@@ -369,14 +371,17 @@ module Clacky
         new_string = args[:new_string] || args['new_string'] || ""
         replace_all = args[:replace_all] || args['replace_all'] || false
 
+        # Expand ~ to home directory so File.exist? and File.read work correctly
+        expanded_path = path&.start_with?("~") ? File.expand_path(path) : path
+
         @ui&.show_file_edit_preview(path)
 
-        if !path || path.empty?
+        if !expanded_path || expanded_path.empty?
           @ui&.show_file_error("No file path provided")
           return { error: "No file path provided for edit operation" }
         end
 
-        unless File.exist?(path)
+        unless File.exist?(expanded_path)
           @ui&.show_file_error("File not found: #{path}")
           return { error: "File not found: #{path}", path: path }
         end
@@ -386,7 +391,7 @@ module Clacky
           return { error: "No old_string provided (nothing to replace)" }
         end
 
-        file_content = File.read(path)
+        file_content = File.read(expanded_path)
 
         # Use the same find_match logic as Edit tool to handle fuzzy matching
         # (trim, unescape, smart line matching) — prevents diff from being blank