openclacky 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 49800afa935670c288d9f421595df4246b61e76ed0f2a74e1a7a754e85e26162
-  data.tar.gz: dba09cac5a79485b743aaad4568ce2e4fe2e13772d6b8c43a360ec11eca7c762
+  metadata.gz: 9d6ba5a62f7a352730705db11aff8ab76af059764903eb4413bd5a0aa835fecf
+  data.tar.gz: 58ba8fdcf23b5dabcc4a8ed709be0f34a9d27a5be83601fee685a638eb3ff445
 SHA512:
-  metadata.gz: 2b723771f71d880d99582f6bfd4d23a66f54ee3caa87f7ed228360f015cadb52a20be9d6869c6e35612740ddb889ceb762efa541a41bc25810f5897d47a333e1
-  data.tar.gz: 5c425e94d2bf4c4d68175b740d840b9cd6270ef91f2e68e6d8403fbb6fbc5336b07bd65308907dbb8d8c3cd1cb906c4c5f64ae7710a7e0619ab2aaae0ddc278b
+  metadata.gz: 00e3f00119cad74d7da43519a1a12332e509c0050946d713dea17db539bbadf0099e96ea5369cc19046fd0bc1c224849cbbaf43addfe0708858780a370067b3b
+  data.tar.gz: 4e7888c952dd49c664c67212c0986b62bd7745887dae7d85bce14b3f36c544fc5bd9ca27f1851f04e14477cfd9316938605b6ae0f89b19652cadd1442c6dc564

data/CHANGELOG.md

@@ -5,6 +5,27 @@ 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.0.1] - 2026-05-06
+
+### Added
+- **OpenRouter Anthropic API support.** You can now route Claude model requests through OpenRouter, giving access to Anthropic models via a single OpenRouter API key — useful when Anthropic direct access is limited in your region.
+- **GPT provider support.** Direct GPT provider configuration is now available alongside other providers, making it easier to switch between different OpenAI-compatible endpoints.
+- **OCR-powered PDF reading.** PDF files that contain scanned images (non-text PDFs) are now readable via OCR, allowing the agent to extract content from scanned documents, invoices, and image-heavy PDFs.
+- **Terminal output size control.** The agent now limits terminal output to a configurable size, preventing token overflows when running commands that produce very long output.
+- **Memories & Trash manager in Web UI.** A new management panel lets you browse, review, and delete agent memories and trashed files directly from the Web UI.
+- **Watchdog for interrupt messages.** A background watchdog ensures interrupt signals reliably stop the agent even when it's deep in a tool execution loop.
+- **Skill import with category directory scanning.** When importing skills from openclaw packages, nested category directories are now scanned automatically, so all skills in a category bundle are imported at once.
+
+### Improved
+- **Deploy skill simplified.** The deploy skill now uses Railway CLI directly without custom helper tools, making deployments more reliable and the codebase significantly lighter.
+- **Fix double-render of progress indicators.** Progress spinners and status lines no longer render twice in quick succession, keeping the Web UI output clean.
+- **Session idle status tracking and file descriptor cleanup.** Sessions now correctly report idle state when the agent finishes, and open file descriptors are properly closed to avoid resource leaks.
+- **GPT-4.1 and GPT-5 pricing added.** Model cost tracking now includes the latest GPT-4.1 and GPT-5 pricing tiers.
+
+### Fixed
+- **UTF-8 encoding error in file preview.** Opening files with non-UTF-8 characters no longer crashes the preview — they are now handled gracefully.
+- **Expand `~` in openfile path.** The "open file in editor" API endpoint now correctly expands `~` to the user's home directory.
+
 ## [1.0.0] - 2026-04-30
 
 ### Added

data/README.md

@@ -6,77 +6,79 @@
 [![Downloads](https://img.shields.io/gem/dt/openclacky?label=downloads&style=flat-square&color=brightgreen)](https://rubygems.org/gems/openclacky)
 [![License](https://img.shields.io/badge/license-MIT-lightgrey?style=flat-square)](LICENSE.txt)
 
-**From expertise to business — turn your professional knowledge into a monetizable OpenClaw Skill.**
+**The most Token-efficient open-source AI Agent.**
 
-OpenClacky is the creator-side platform for the OpenClaw ecosystem. Package your methods and workflows into encrypted, white-labeled Skills that your clients install and use — under your name, your brand, your price.
+OpenClacky matches Claude Code on capability at comparable cost, and saves significantly against other open-source agents (~50% vs OpenClaw, ~3× cheaper than Hermes). 100% open source (MIT), BYOK with any OpenAI-compatible model, built on two years of Agentic R&D and harness engineering.
 
-## Why OpenClacky?
+> Website: https://www.openclacky.com/ · Backed by **MiraclePlus · ZhenFund · Sequoia China · Hillhouse Capital**
 
-The OpenClaw ecosystem has 5,700+ Skills and growing. But almost all of them are open-sourced, free, and easily copied. The real scarcity isn't more Skills — it's **expertise-backed, production-grade Skills worth paying for**.
+## Why OpenClacky?
 
-OpenClacky is built for the people who have that expertise.
+Same task, how much do you pay? Under comparable agent workloads, OpenClacky saves a large amount of Token spend compared to mainstream alternatives.
 
-|  | **Openclaw** | **OpenClacky** |
+| Agent | Relative cost | Notes |
 |---|---|---|
-| **Core model** | Open sharing | Encrypted & protected |
-| **Primary users** | Users who install Skills | Creators who sell Skills |
-| **Revenue** | None | Creator-defined pricing |
-| **Brand** | Platform brand | Your own brand |
-| **Driven by** | Technical contributors | Domain expertise |
+| **OpenClacky** | **~0.8–1.2×** | 16 tools · ~100% cache hit · subagent routing |
+| Claude Code | 1.0× (baseline) | World-class harness, closed-source subscription |
+| OpenClaw | ~1.5× | Comparable harness agent |
+| Hermes | ~3× | 52 built-in tools — schema bloat ~3–4× |
 
-## How It Works
+*Numbers are averages measured on internal common agent tasks, using Claude Code as the baseline. Full benchmark reports will be published on GitHub.*
 
-**Four steps from capability to business:**
+## Feature comparison
 
-1. **Craft your Skill** — Turn your domain methodology into a repeatable AI workflow
-2. **Encrypt & protect** — Your logic stays yours; clients can't inspect or copy it
-3. **Package your brand** — Ship under your name, your logo, your onboarding experience
-4. **Launch & acquire** — One-click sales page, built-in SEO, start converting traffic
+Core agent capability is roughly on par across the field — the real differentiators are **cost, openness, Skill evolution, and integrations**.
 
-## Who It's For
+| Feature | Claude Code | OpenClaw | Hermes | **OpenClacky** |
+|---|:---:|:---:|:---:|:---:|
+| Token cost | 1.0× | ~1.5× | ~3× | **~0.8–1.2×** |
+| Open source | ❌ Closed | ✅ Open | ✅ Open | ✅ MIT |
+| BYOK / model freedom | ❌ Anthropic only | ✅ | ✅ | ✅ |
+| Skill self-evolution | ❌ | ❌ | ✅ | ✅ |
+| IM integration (Feishu / WeCom / WeChat) | ❌ | ✅ | ✅ | ✅ |
 
-OpenClacky is built for domain experts whose knowledge can be expressed as *information processing + executable actions*:
+## How we get the cost down
 
-- **SEO specialists** — keyword research, content scoring, rank monitoring
-- **Lawyers** — contract review, case retrieval, risk flagging
-- **Traders** — signal detection, strategy backtesting, automated execution
-- **Data analysts** — cleaning, modeling, report generation
-- **Content strategists** — topic selection, outlines, drafts at scale
+Not by cutting features — by compounding the right choice at every layer.
 
-## Features
+### 1. Ultra-high cache hit rate
+Sessions never restart, double cache markers, **Insert-then-Compress** — the system prompt is never mutated, so compression still reuses the cache. **Measured cache hit rate: near 100%.**
 
-- [x] **Skill builder** — Create AI workflows via conversation or UI, iterate and ship fast
-- [x] **Encryption** — Protect your knowledge assets; end users cannot read your Skill source
-- [x] **White-label packaging** — Your brand, your product line, your client experience
-- [x] **Auto-update delivery** — Push updates to all users seamlessly, with version control
-- [x] **Cross-platform distribution** — Windows, macOS, Linux — one Skill, every platform
-- [x] **Sales page generator** — Launch your storefront fast, with built-in SEO foundations
-- [x] **Cost monitoring** — Real-time token tracking, automatic compression (up to 90% savings)
-- [x] **Multi-provider support** — OpenAI, Anthropic, DeepSeek, and any OpenAI-compatible API
-- [ ] **Skill marketplace** — Discover and distribute premium Skills *(coming soon)*
+### 2. Minimal tool set
+Only **16 core tools**. Capabilities are offloaded to the Skill ecosystem via a single `invoke_skill` meta-tool. Tool count is not the metric — task completion rate is.
 
-## Coding Support
+| OpenClacky | Claude Code | OpenClaw | Hermes |
+|:--:|:--:|:--:|:--:|
+| **16** | 40+ | 23 | 52 |
 
-OpenClacky also works as a general AI coding assistant — scaffold full-stack Rails apps, add features, or explore an unfamiliar codebase:
+### 3. Idle-time auto-compression
+Go to a meeting, grab coffee — the agent compresses long context in the background and pre-warms the cache. Your first message back hits the cache directly. **Cold-start first-token cost reduced by 50%+.**
 
-```bash
-$ openclacky
-> /new my-app        # scaffold a full-stack Rails app
-> Add user auth with email and password
-> How does the payment module work?
-```
+### 4. BYOK — you pick the model, you set the cost
+Any OpenAI-compatible API, plug and play. Official direct, aggregate routing, compatible relays — the choice is 100% yours. Use Claude for code, auto-route subtasks to DeepSeek, save another chunk of tokens.
+
+Built on **2 years · 3 generations of agentic architecture · 6 core harness engineering decisions**.
+
+## Skills — the soul of the agent
 
-Built on a production-ready Rails architecture with one-click deployment, dev/prod isolation, and automatic backups.
+- **Invoke with `/`** — instant browse, fuzzy search, direct call. Hundreds of Skills at your fingertips.
+- **Create Skills in natural language** — just describe what you want; the agent drafts `SKILL.md`, breaks down steps, and runs validation. No code required.
+- **Self-evolving** — after each run, the agent updates the Skill based on execution context and results. The next call is more stable and more accurate.
+- **Open & compatible** — supports Claude Skills / Markdown Pack / custom formats.
+- **Monetizable** — polished Skills can be packaged for sale, with encrypted distribution, License management, and creator-defined pricing.
 
 ## Installation
 
-### Method 1: One-line Install (Recommended)
+### Desktop installer (recommended)
 
-```bash
-/bin/bash -c "$(curl -sSL https://raw.githubusercontent.com/clacky-ai/openclacky/main/scripts/install.sh)"
-```
+Double-click to install — environment, dependencies, and Skills all set up automatically.
+
+- **macOS** — [Download `.dmg`](https://oss.1024code.com/openclacky-installer/official/openclacky-installer.dmg) (Apple Silicon / Intel)
+- **Windows** — [Download `.exe`](https://oss.1024code.com/openclacky-installer/official/openclacky-installer.exe) (Windows 10 2004+ / Windows 11)
 
-### Method 2: RubyGems
+More options: https://www.openclacky.com/
+
+### Command line
 
 **Requirements:** Ruby >= 3.1.0
 
@@ -84,6 +86,12 @@ Built on a production-ready Rails architecture with one-click deployment, dev/pr
 gem install openclacky
 ```
 
+Or one-line install:
+
+```bash
+/bin/bash -c "$(curl -sSL https://raw.githubusercontent.com/clacky-ai/openclacky/main/scripts/install.sh)"
+```
+
 ## Quick Start
 
 ### Terminal (CLI)
@@ -95,16 +103,16 @@ openclacky            # start interactive agent in current directory
 ### Web UI
 
 ```bash
-openclacky server     # start the web server (default: http://localhost:7070)
+openclacky server     # default: http://localhost:7070
 ```
 
-Then open **http://localhost:7070** in your browser. You'll get a full-featured chat interface with multi-session support — run separate sessions for coding, copywriting, research, and more, all in parallel.
+Open **http://localhost:7070** for a full chat interface with multi-session support — run coding, copywriting, research sessions in parallel.
 
 Options:
 
 ```bash
-openclacky server --port 8080          # custom port
-openclacky server --host 0.0.0.0      # listen on all interfaces (e.g. remote access)
+openclacky server --port 8080        # custom port
+openclacky server --host 0.0.0.0     # listen on all interfaces (remote access)
 ```
 
 ## Configuration
@@ -114,7 +122,26 @@ $ openclacky
 > /config
 ```
 
-You'll be prompted to set your **API Key**, **Model**, and **Base URL** (any OpenAI-compatible provider).
+Set your **API Key**, **Model**, and **Base URL** (any OpenAI-compatible provider).
+
+Supported out of the box: **Claude (Anthropic) · GPT (OpenAI) · DeepSeek · Kimi (Moonshot) · MiniMax · OpenRouter** — or any custom endpoint.
+
+## Coding use case
+
+OpenClacky works as a general AI coding assistant — scaffold full-stack apps, add features, or explore unfamiliar codebases:
+
+```bash
+$ openclacky
+> /new my-app        # scaffold a new project
+> Add user auth with email and password
+> How does the payment module work?
+```
+
+## Advanced — Creator Program
+
+Already power users are turning their workflows into vertical AI experts on OpenClacky — encrypted distribution, License management, self-set pricing. Legal, healthcare, financial planning, and more.
+
+Learn more: https://www.openclacky.com/ → Creators
 
 ## Install from Source
 
@@ -125,6 +152,13 @@ bundle install
 bin/clacky
 ```
 
+## Trust & Credibility
+
+- **100% open source** — MIT License, all code public, all decisions traceable
+- **2 years of Agentic R&D** — 3 generations of architecture
+- **16 core tools** — minimal by design
+- **Backed by** MiraclePlus · ZhenFund · Sequoia China · Hillhouse Capital
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/clacky-ai/openclacky. Contributors are expected to adhere to the [code of conduct](https://github.com/clacky-ai/openclacky/blob/main/CODE_OF_CONDUCT.md).

data/lib/clacky/agent/cost_tracker.rb

@@ -105,8 +105,25 @@ module Clacky
         cache_write = usage[:cache_creation_input_tokens] || 0
         cache_read = usage[:cache_read_input_tokens] || 0
 
-        # Calculate token delta from previous iteration
-        delta_tokens = total_tokens - @previous_total_tokens
+        # Calculate token delta from previous iteration.
+        #
+        # Two conventions exist for total_tokens across providers:
+        #   - OpenAI (default):    cumulative per-request input+output (grows
+        #                          with history every turn). Delta = total - prev.
+        #   - Anthropic direct:    already the per-turn new compute
+        #                          (raw_input + cache_creation + output).
+        #                          The MessageFormat sets :total_is_per_turn so
+        #                          we use total_tokens directly as the delta.
+        #
+        # Without this branch, Anthropic's per-turn total would be treated as
+        # cumulative and produce negative / nonsensical deltas whenever cached
+        # prefixes make the per-turn new-compute smaller than the previous turn.
+        delta_tokens =
+          if usage[:total_is_per_turn]
+            total_tokens
+          else
+            total_tokens - @previous_total_tokens
+          end
         @previous_total_tokens = total_tokens  # Update for next iteration
 
         {

data/lib/clacky/agent/llm_caller.rb

@@ -54,6 +54,20 @@ module Clacky
         max_retries = 10
         retry_delay = 5
         retries = 0
+
+        # Track whether any of the retry/fallback branches below opened a
+        # "retrying" progress slot via show_progress(progress_type:
+        # "retrying", phase: "active"). If so, we MUST close it before
+        # leaving call_llm — otherwise the UI's legacy shim in
+        # UI2::UIController keeps the :quiet ProgressHandle alive, its
+        # ticker thread keeps running, and the user sees a frozen
+        # "Network failed: ... (681s)" line long after the task finished.
+        #
+        # The close is done in the outer ensure below so it runs on:
+        #   - normal success (response returned)
+        #   - unrecoverable failure (raise propagates out)
+        #   - BadRequestError reasoning-content retry success
+        retrying_progress_opened = false
         # One-shot flag set by the BadRequestError rescue below when the server
         # complained about missing reasoning_content. The subsequent retry will
         # pad every assistant message's reasoning_content, which satisfies
@@ -67,6 +81,7 @@ module Clacky
         thinking_retry_attempted = false
 
         begin
+          begin
           # 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)
@@ -118,6 +133,7 @@ module Clacky
               phase: "active",
               metadata: { attempt: retries, total: max_retries }
             )
+            retrying_progress_opened = true
             sleep retry_delay
             retry
           else
@@ -144,6 +160,7 @@ module Clacky
               phase: "active",
               metadata: { attempt: retries, total: max_retries }
             )
+            retrying_progress_opened = true
             sleep retry_delay
             retry
           else
@@ -180,6 +197,7 @@ module Clacky
               phase: "active",
             metadata: { attempt: retries, total: current_max }
           )
+          retrying_progress_opened = true
           sleep retry_delay
           retry
         else
@@ -213,6 +231,21 @@ module Clacky
         response[:token_usage] = token_data
 
         response
+        ensure
+          # Close any "retrying" progress slot that was opened during the
+          # retry/fallback loop above. The legacy UI shim allocates a
+          # separate :quiet ProgressHandle under the "retrying" key; if it
+          # is never finished its ticker thread keeps running and the user
+          # sees a stale "Network failed: ... (NNN s)" line long after the
+          # task has completed. This ensure runs on:
+          #   - successful retry → close the slot, message is "Recovered"
+          #     so the final frame is informative rather than blank
+          #   - unrecoverable failure that raises out → close the slot so
+          #     the spinner doesn't linger while the error bubbles up
+          if retrying_progress_opened
+            @ui&.show_progress(progress_type: "retrying", phase: "done")
+          end
+        end
       end
 
       # Attempt to activate the provider fallback model for the given primary model.

data/lib/clacky/agent/message_compressor_helper.rb

@@ -47,11 +47,41 @@ module Clacky
             handle_compression_response(response, compression_context, progress: handle)
             true
           rescue Clacky::AgentInterrupted => e
-            @ui&.log("Idle compression canceled: #{e.message}", level: :info)
+            # User cancelled the idle compression — finish the quiet progress
+            # slot in place so the user sees exactly what happened (rather
+            # than the "Idle detected..." line being silently removed).
+            final = "Idle compression cancelled: #{e.message}"
+            if handle
+              handle.finish(final_message: final)
+            else
+              @ui&.log(final, level: :info)
+            end
             @history.rollback_before(compression_message)
+            Clacky::Logger.info("[idle-compress] cancelled: #{e.message}")
             false
           rescue => e
-            @ui&.log("Idle compression failed: #{e.message}", level: :error)
+            # Compression failed (most commonly: network errors after all
+            # LlmCaller retries exhausted). Previously this only wrote an
+            # @ui.log(:error) that was easy to miss — especially when no
+            # other output followed. Now we:
+            #   1. Replace the active quiet progress line with the error so
+            #      the user always sees *something* where the spinner was.
+            #   2. Emit a show_warning for a more prominent entry.
+            #   3. Persist to Clacky::Logger so post-mortem is possible even
+            #      if the terminal scrollback has rolled past.
+            final = "Idle compression failed: #{e.message}"
+            if handle
+              handle.finish(final_message: final)
+            else
+              @ui&.log(final, level: :error)
+            end
+            @ui&.show_warning(final)
+            Clacky::Logger.warn(
+              "[idle-compress] failed",
+              error_class: e.class.name,
+              error_message: e.message,
+              backtrace: e.backtrace&.first(5)
+            )
             @history.rollback_before(compression_message)
             false
           end

data/lib/clacky/agent.rb

@@ -78,7 +78,6 @@ module Clacky
       @cost_source = :estimated  # Track whether cost is from API or estimated
       @task_cost_source = :estimated  # Track cost source for current task
       @previous_total_tokens = 0  # Track tokens from previous iteration for delta calculation
-      @interrupted = false  # Flag for user interrupt
       @latest_latency = nil  # Most recent LLM call's latency metrics (see Client#send_messages_with_tools)
       @ui = ui  # UIController for direct UI interaction
       @debug_logs = []  # Debug logs for troubleshooting
@@ -360,9 +359,6 @@ module Clacky
         task_interrupted = false
 
         loop do
-
-          break if should_stop?
-
           @iterations += 1
           @hooks.trigger(:on_iteration, @iterations)
 
@@ -929,12 +925,6 @@ module Clacky
       end
     end
 
-    # Interrupt the agent's current run
-    # Called when user presses Ctrl+C during agent execution
-    def interrupt!
-      @interrupted = true
-    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.
@@ -1001,16 +991,7 @@ module Clacky
 
     # Check if agent is currently running
     def running?
-      @start_time != nil && !should_stop?
-    end
-
-    private def should_stop?
-      if @interrupted
-        @interrupted = false  # Reset for next run
-        return true
-      end
-
-      false
+      !@start_time.nil?
     end
 
     private def build_result(status = :success, error: nil)

data/lib/clacky/client.rb

@@ -12,14 +12,29 @@ module Clacky
       @api_key = api_key
       @base_url = base_url
       @model = model
-      @use_anthropic_format = anthropic_format
       # Detect Bedrock: ABSK key prefix (native AWS) or abs- model prefix (Clacky AI proxy)
       @use_bedrock = MessageFormat::Bedrock.bedrock_api_key?(api_key, model)
 
+      # Resolve provider once — reused for capability + api-type lookups.
+      provider_id = Providers.resolve_provider(base_url: @base_url, api_key: @api_key)
+
+      # Decide anthropic_format dynamically based on provider+model, falling
+      # back to the explicit constructor flag for unknown providers / custom
+      # base_urls. This lets e.g. OpenRouter's Claude models auto-route to the
+      # native /v1/messages endpoint (preserving cache_control byte-for-byte)
+      # without requiring any change to user YAML.
+      provider_prefers_anthropic = provider_id &&
+                                   Providers.anthropic_format_for_model?(provider_id, @model)
+      @use_anthropic_format = provider_prefers_anthropic || anthropic_format
+
+      # Remember the provider id so we can tune connection headers below
+      # (OpenRouter's /v1/messages accepts either Bearer or x-api-key, but
+      # some OpenRouter-compatible relays only honour Bearer — send both).
+      @provider_id = provider_id
+
       # Determine vision support once at construction time.
       # Non-vision models (DeepSeek, Kimi, MiniMax, etc.) reject image_url
       # content blocks; the conversion layer strips them when this is false.
-      provider_id = Providers.resolve_provider(base_url: @base_url, api_key: @api_key)
       @vision_supported = Providers.supports?(provider_id, :vision, model_name: @model)
     end
 
@@ -47,7 +62,7 @@ module Clacky
       elsif anthropic_format?
         minimal_body = { model: model, max_tokens: 16,
                          messages: [{ role: "user", content: "hi" }] }.to_json
-        response = anthropic_connection.post("v1/messages") { |r| r.body = minimal_body }
+        response = anthropic_connection.post(anthropic_messages_path) { |r| r.body = minimal_body }
       else
         minimal_body = { model: model, max_tokens: 16,
                          messages: [{ role: "user", content: "hi" }] }.to_json
@@ -77,7 +92,7 @@ module Clacky
         parse_simple_bedrock_response(response)
       elsif anthropic_format?
         body     = MessageFormat::Anthropic.build_request_body(messages, model, [], max_tokens, false)
-        response = anthropic_connection.post("v1/messages") { |r| r.body = body.to_json }
+        response = anthropic_connection.post(anthropic_messages_path) { |r| r.body = body.to_json }
         parse_simple_anthropic_response(response)
       else
         body     = { model: model, max_tokens: max_tokens, messages: messages }
@@ -206,7 +221,7 @@ module Clacky
       messages = apply_message_caching(messages) if caching_enabled
 
       body     = MessageFormat::Anthropic.build_request_body(messages, model, tools, max_tokens, caching_enabled)
-      response = anthropic_connection.post("v1/messages") { |r| r.body = body.to_json }
+      response = anthropic_connection.post(anthropic_messages_path) { |r| r.body = body.to_json }
 
       raise_error(response) unless response.status == 200
       check_html_response(response)
@@ -333,6 +348,14 @@ module Clacky
         conn.headers["x-api-key"]      = @api_key
         conn.headers["anthropic-version"] = "2023-06-01"
         conn.headers["anthropic-dangerous-direct-browser-access"] = "true"
+        # OpenRouter's /v1/messages endpoint authenticates with a Bearer
+        # token (the OpenRouter API key), not Anthropic's x-api-key. We send
+        # both so the same connection code works for direct Anthropic and
+        # for OpenRouter-proxied Claude — each endpoint ignores the header
+        # it doesn't recognise.
+        if @provider_id == "openrouter"
+          conn.headers["Authorization"] = "Bearer #{@api_key}"
+        end
         conn.options.timeout      = 300
         conn.options.open_timeout = 10
         conn.ssl.verify           = false
@@ -340,6 +363,22 @@ module Clacky
       end
     end
 
+    # Correct relative path for the Anthropic /v1/messages endpoint, accounting
+    # for whether the configured base_url already includes a "/v1" segment.
+    #
+    # Examples:
+    #   base_url = "https://api.anthropic.com"         → "v1/messages"
+    #   base_url = "https://openrouter.ai/api/v1"      → "messages"
+    #   base_url = "https://openrouter.ai/api/v1/"     → "messages"
+    #
+    # Without this, OpenRouter would receive POST /api/v1/v1/messages → 404
+    # (HTML error page), which bubbles up as the infamous
+    # "Invalid API endpoint or server error (received HTML instead of JSON)".
+    private def anthropic_messages_path
+      base = @base_url.to_s.chomp("/")
+      base.end_with?("/v1") ? "messages" : "v1/messages"
+    end
+
     # ── Error handling ────────────────────────────────────────────────────────
 
     def handle_test_response(response)

data/lib/clacky/default_parsers/pdf_parser.rb

@@ -12,15 +12,33 @@
 #   exit 0 — success
 #   exit 1 — failure
 #
-# This file lives in ~/.clacky/parsers/ and can be modified by the LLM
-# to add new capabilities (e.g. OCR for scanned PDFs).
+# This file lives in ~/.clacky/parsers/ and can be modified by the LLM.
 #
-# VERSION: 1
+# Extraction pipeline (first successful step wins):
+#   1. pdftotext (poppler)     — fastest, text-based PDFs
+#   2. pdfplumber (Python)     — handles more layouts
+#                                (→ pdf_parser_plumber.py)
+#   3. OCR (tesseract)         — scanned / image-only PDFs
+#                                (→ pdf_parser_ocr.py)
+#
+# Each extractor is a plain, self-contained function. Python-backed steps
+# shell out to a sibling .py script so the LLM can edit them directly
+# (with proper syntax highlighting, linters, and per-file run/debug)
+# instead of wrestling with embedded heredocs.
+#
+# VERSION: 3
 
 require "open3"
 
+# Minimum useful output (in bytes). Below this, a step is considered a
+# miss and the next fallback is tried.
 MIN_CONTENT_BYTES = 20
 
+# Script directory — resolve sibling .py helpers relative to this file
+# so it works both from the gem's default_parsers/ dir and from the
+# copied-to-user ~/.clacky/parsers/ dir.
+SCRIPT_DIR = File.dirname(File.expand_path(__FILE__))
+
 def try_pdftotext(path)
   stdout, _stderr, status = Open3.capture3("pdftotext", "-layout", "-enc", "UTF-8", path, "-")
   return nil unless status.success?
@@ -32,18 +50,10 @@ rescue Errno::ENOENT
 end
 
 def try_pdfplumber(path)
-  script = <<~PYTHON
-    import sys, pdfplumber
-    with pdfplumber.open(sys.argv[1]) as pdf:
-        pages = []
-        for i, page in enumerate(pdf.pages, 1):
-            t = page.extract_text()
-            if t and t.strip():
-                pages.append(f"--- Page {i} ---\\n{t.strip()}")
-        print("\\n\\n".join(pages))
-  PYTHON
+  script = File.join(SCRIPT_DIR, "pdf_parser_plumber.py")
+  return nil unless File.exist?(script)
 
-  stdout, _stderr, status = Open3.capture3("python3", "-c", script, path)
+  stdout, _stderr, status = Open3.capture3("python3", script, path)
   return nil unless status.success?
   text = stdout.strip
   return nil if text.bytesize < MIN_CONTENT_BYTES
@@ -52,6 +62,34 @@ rescue Errno::ENOENT
   nil # python3 not available
 end
 
+# OCR fallback for scanned/image-only PDFs.
+# See pdf_parser_ocr.py for the actual extraction logic.
+#
+# Installation hints (also printed on final failure):
+#   macOS:   brew install tesseract tesseract-lang poppler
+#            pip3 install pytesseract pdf2image
+#   Linux:   apt install tesseract-ocr tesseract-ocr-chi-sim poppler-utils
+#            pip3 install pytesseract pdf2image
+def try_ocr(path)
+  # Quick capability check — avoid spawning python if tesseract is missing.
+  _stdout, _stderr, status = Open3.capture3("tesseract", "--version")
+  return nil unless status.success?
+
+  script = File.join(SCRIPT_DIR, "pdf_parser_ocr.py")
+  return nil unless File.exist?(script)
+
+  stdout, stderr, status = Open3.capture3("python3", script, path)
+  unless status.success?
+    warn stderr.strip unless stderr.strip.empty?
+    return nil
+  end
+  text = stdout.strip
+  return nil if text.bytesize < MIN_CONTENT_BYTES
+  text
+rescue Errno::ENOENT
+  nil # tesseract or python3 not available
+end
+
 # --- main ---
 
 path = ARGV[0]
@@ -66,14 +104,17 @@ unless File.exist?(path)
   exit 1
 end
 
-text = try_pdftotext(path) || try_pdfplumber(path)
+# Try each extractor in order; first non-nil result wins.
+text = try_pdftotext(path) || try_pdfplumber(path) || try_ocr(path)
 
 if text
   print text
   exit 0
 else
   warn "Could not extract text from PDF."
-  warn "Tip: install poppler for text-based PDFs: brew install poppler"
-  warn "For scanned PDFs, consider adding OCR support (e.g. tesseract)."
+  warn "For text-based PDFs, install poppler: brew install poppler (macOS) / apt install poppler-utils (Linux)"
+  warn "For scanned PDFs (OCR):"
+  warn "  macOS: brew install tesseract tesseract-lang poppler && pip3 install pytesseract pdf2image"
+  warn "  Linux: apt install tesseract-ocr tesseract-ocr-chi-sim poppler-utils && pip3 install pytesseract pdf2image"
   exit 1
 end