From 7397ac11fcd81124e22ed856fc285700e1d6d687 Mon Sep 17 00:00:00 2001
From: Ousama Ben Younes <benyounes.ousama@gmail.com>
Date: Tue, 7 Jul 2026 20:00:08 +0000
Subject: [PATCH] docs: clarify Claude client setup (#56)

---
 README.md                  | 24 ++++++++++++++++++++++++
 tests/readme-usage.test.ts | 30 ++++++++++++++++++++++++++++++
 2 files changed, 54 insertions(+)
 create mode 100644 tests/readme-usage.test.ts

diff --git a/README.md b/README.md
index 23daa524..e56c71fc 100644
--- a/README.md
+++ b/README.md
@@ -55,6 +55,30 @@ normally — pxpipe compresses the *request* only, never the model's output.
 Recent turns stay text; the system prompt, tool docs, and older bulk history
 are imaged.
 
+## Use with Claude clients
+
+Start the proxy in one terminal, then point the client at it.
+
+Claude Code CLI on macOS/Linux:
+
+```bash
+npx pxpipe-proxy
+ANTHROPIC_BASE_URL=http://127.0.0.1:47821 claude
+```
+
+Claude Code CLI on Windows PowerShell:
+
+```powershell
+npx pxpipe-proxy
+$env:ANTHROPIC_BASE_URL = "http://127.0.0.1:47821"
+claude
+```
+
+Claude Desktop can use the same `ANTHROPIC_BASE_URL` environment variable for
+its bundled Claude Code runtime. Start `pxpipe` first, then launch Claude
+Desktop from an environment where `ANTHROPIC_BASE_URL` is set to
+`http://127.0.0.1:47821`.
+
 ## The honest part
 
 - **It is lossy.** Exact 12-char hex strings in dense imaged content:
diff --git a/tests/readme-usage.test.ts b/tests/readme-usage.test.ts
new file mode 100644
index 00000000..becedd4f
--- /dev/null
+++ b/tests/readme-usage.test.ts
@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest';
+import * as fs from 'node:fs';
+
+const README_PATH = 'README.md';
+const USAGE_HEADING = '## Use with Claude clients';
+const REQUIRED_USAGE_TEXT = [
+  'Claude Code CLI',
+  'ANTHROPIC_BASE_URL=http://127.0.0.1:47821 claude',
+  'Windows PowerShell',
+  '$env:ANTHROPIC_BASE_URL',
+  'Claude Desktop',
+  'ANTHROPIC_BASE_URL',
+] as const;
+
+describe('README usage documentation', () => {
+  it('documents CLI, Windows PowerShell, and Claude Desktop setup', () => {
+    const readme = fs.readFileSync(README_PATH, 'utf8');
+    const sectionStart = readme.indexOf(USAGE_HEADING);
+
+    expect(sectionStart).toBeGreaterThanOrEqual(0);
+
+    const nextSectionStart = readme.indexOf('\n## ', sectionStart + USAGE_HEADING.length);
+    const section =
+      nextSectionStart === -1 ? readme.slice(sectionStart) : readme.slice(sectionStart, nextSectionStart);
+
+    for (const requiredText of REQUIRED_USAGE_TEXT) {
+      expect(section).toContain(requiredText);
+    }
+  });
+});