Claude Desktop Right-to-Left (RTL) Support Patch

A robust, lightweight, and secure utility to enable proper Right-to-Left (RTL) rendering in the official Claude Desktop application for Right-to-Left languages such as Persian, Arabic, and Hebrew.

---

The Problem

Claude Desktop is built as an Electron application but does not provide default RTL layout handling. When mixing Persian, Arabic, or Hebrew sentences with English terms or code blocks, text alignment and paragraph direction display incorrectly, severely impacting legibility.

The Solution

This tool injects a lightweight, high-performance bidirectional (bidi) layout script directly into Claude Desktop's preload system. It automatically formats RTL paragraphs to align right and set direction, while keeping code blocks, monospace blocks, and English text formatted LTR.

---

How It Works (Architecture Overview)

Transition from Proof of Concept (PoC)

The initial prototype attempted to inject code by:

1. Patching Claude Desktop to bypass internal security restrictions blocking Chromium DevTools.
2. Opening a Chromium DevTools Protocol (CDP) WebSocket port on localhost.
3. Running a permanent background Python daemon that connected to the CDP port and injected JavaScript.
4. Wrapping the executable in a bash wrapper to launch it with custom flags.

Why we abandoned this architecture:

• Security Risk: Leaving a remote debugging port open on localhost (port 9333) allows any other application running on the system to connect, inspect your chats, steal authentication credentials, or manipulate the application's local filesystem and MCP tools.
• Overhead: Running a permanent Python daemon in the background wastes memory and CPU.
• Fragility: If the websocket connection drops or port binding fails, RTL support breaks silently.
• Portability: Setting up a launcher wrapper, custom .desktop shortcuts, and a systemd service is highly platform-dependent and increases the maintenance burden.

Modern Production Architecture

The production-ready tool uses Preload Injection via Streamed ASAR Rewriting:

graph TD
    A[claude-rtl tool] -- 1. Read & Parse --> B(app.asar Header)
    A -- 2. Append RTL bidi script --> C(mainWindow.js Preload)
    A -- 3. Rebuild contiguous payload --> D[app.asar Patched]
    E[Claude Desktop Startup] --> F{Check domain}
    F -- claude.ai --> G[Run Preload + RTL script]
    F -- other --> H[Skip RTL]

Loading

1. Direct Preload Injection: Instead of a background daemon injecting code via DevTools, we append our bidi detection script directly onto Claude Desktop's main preload script (.vite/build/mainWindow.js) inside its packaged application archive (app.asar).
2. Zero Overhead & Ports: No TCP ports are opened, and no background daemon runs. The bidi formatting code runs natively inside the Electron renderer process, executing only when the main window loads claude.ai.
3. Streamed ASAR Rewrite: We implemented a custom pure-Python ASAR library (src/claude_rtl/asar.py) that reads the binary header, modifies the target preload script size, offsets all subsequent files, and writes the patched ASAR in a single contiguous write pass.
   • Atomic safety: It writes to a temporary file in the target folder and swaps it atomically (via os.replace), ensuring that a crash or disk overflow never corrupts the Claude Desktop installation.
   • Zero external dependencies: Requires only standard Python libraries (no Node.js/npm/npx required).

---

Documentation & Guides

For more in-depth information, check out our dedicated guides:

• Installation Guide: Detailed installation instructions for Linux, macOS, and Windows.
• Architecture Overview: The design decisions, security analysis, and streamed ASAR writer implementation details.
• Troubleshooting Guide: Fixes for permission issues, unaligned text, and manual recovery.
• Frequently Asked Questions (FAQ): Privacy, safety, code block safeguards, and customization.

---

Installation & Usage

Prerequisites

• Python 3.7+ installed on your system.
• Claude Desktop installed (Linux, macOS, or Windows).

Direct Installation (Recommended)

1. Clone this repository:

   git clone https://github.com/jooya98/claude-rtl.git
   cd claude-rtl

2. Run the patcher with administrative privileges (needed to write to /usr/lib on Linux):

   sudo python3 bin/claude-rtl install

   (On Windows/macOS, run your command prompt/terminal as Administrator without sudo).

3. Restart Claude Desktop. Mixed Persian, Arabic, or Hebrew chats will now render with correct alignment.

For more details, see the Installation Guide.

---

Command Line Interface Reference

The claude-rtl CLI tool provides simple commands for managing the patch:

# Check the status of the patch (is it installed, is there a backup, etc.)
python3 bin/claude-rtl status

# Install the RTL patch (automatically stops/cleans up any old systemd prototype daemons)
sudo python3 bin/claude-rtl install

# Uninstall the patch and safely restore the original backed-up app.asar
sudo python3 bin/claude-rtl uninstall

# Run diagnostic verification on paths, permissions, and directories
python3 bin/claude-rtl diagnose

---

Troubleshooting & FAQ

Please refer to the Troubleshooting Guide and FAQ for quick solutions to common issues.

---

License

This project is licensed under the MIT License.