Skip to content
Back to search

gvzdv-plugins

MarketplaceWorks with Claude CodeGitHub

Mike Gvozdev's Claude Code plugins.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gvzdv--claudish-to-english/badge.svg)](/listings/gvzdv--claudish-to-english)

HTML

<a href="/listings/gvzdv--claudish-to-english"><img src="/api/listings/gvzdv--claudish-to-english/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Directly from this repository (also serves its own marketplace):

/plugin marketplace add gvzdv/claudish-to-english
/plugin install claudish-to-english@gvzdv-plugins

The plugin is `Submitted and pending review` on the Claude Marketplace since August 10. ~~After review by the Anthropic team, the plugin will be available to install from the community marketplace:~~ ~~/plugin marketplace add anthropics/claude-plugins-community~~ ~~/plugin install claudish-to-english@claude-community~~

If the install summary says `Run /reload-plugins to activate.`, run that command.

**Try before installing** (loads it for one session, no install):

claude --plugin-dir /path/to/claudish-to-english

Run `/reload-plugins` after edits; if it doesn't load, check the `/plugin` **Errors** tab.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 17 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "gvzdv-plugins",
  3. "owner": {
  4. "name": "Mike Gvozdev",
  5. "email": "mv.gvozdev@gmail.com",
  6. "url": "https://github.com/gvzdv"
  7. },
  8. "description": "Mike Gvozdev's Claude Code plugins.",
  9. "plugins": [
  10. {
  11. "name": "claudish-to-english",
  12. "source": "./",
  13. "description": "Shows a plain-English rewrite of each Claude Code assistant message, produced by a local LLM (ollama, default), the Anthropic API, or any OpenAI-compatible API. Display-only.",
  14. "category": "productivity"
  15. }
  16. ]
  17. }
README.md · README · 762 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # claudish-to-english
  2. <p align="center">
  3. <img
  4. src="https://github.com/gvzdv/claudish-to-english/releases/download/assets/comparison.png"
  5. width="820"
  6. alt="Side-by-side comparison: a dense, jargon-heavy Claude message labeled 'Claudish' on the left, and its plain-English rewrite on the right">
  7. </p>
  8. A Claude Code plugin that shows a **plain-English rewrite** of each assistant
  9. message, produced by a **local LLM via ollama** (default), the **codex CLI**,
  10. the **Anthropic API**, or any **OpenAI-compatible API**. It is **display-only**:
  11. Claude's own reasoning and the saved transcript keep the original text — only
  12. what you read on screen changes.
  13. If your session speaks something other than English, so does the rewrite: it
  14. follows the message's own language, or the `language` setting Claude Code
  15. already answers in. See [Output language](#output-language).
  16. An optional second hook rewrites **Markdown files** into plain language when
  17. they are written or edited (opt-in, off by default). You can also rewrite any
  18. file, URL, or pasted text **on demand** — `/claudish file <path or URL>` in a session, or
  19. `claudish-md.sh` from a terminal. See
  20. [Rewriting a file or text on demand](#rewriting-a-file-or-text-on-demand).
  21. > Status: working prototype. Every hook fails **open** — if anything goes wrong
  22. > (provider down, timeout, missing key or dependency), you simply see Claude's
  23. > original text. The plugin can never swallow or corrupt an answer.
  24. ---
  25. ## Requirements (read this first)
  26. With the default `ollama` provider this plugin shells out to a **local** model,
  27. and nothing works until these are in place. (With `CLAUDISH_PROVIDER=anthropic`
  28. or `openai` you need only `jq`, `curl`, and an API key — see
  29. [Providers](#providers).)
  30. <a id="macos-setup"></a>
  31. <details>
  32. <summary><strong>macOS setup</strong></summary>
  33. | Requirement | Why | Install |
  34. |---|---|---|
  35. | **ollama**, running | Does the rewriting, locally | `brew install ollama` then `ollama serve` |
  36. | A pulled model | The actual rewriter | `ollama pull gemma4:26b-mlx` (~17 GB; choose the model that fits into your memory) |
  37. | `jq` | Parses hook JSON | ships with macOS 15+; else `brew install jq` |
  38. | `curl` | Talks to ollama | ships with macOS |
  39. Warm the model once after `ollama serve` (the first call is a slow cold load):
  40. ```bash
  41. ollama run gemma4:26b-mlx "hi"
  42. ```
  43. **If the local model isn't ready, the plugin does nothing to your text** —
  44. Claude's output shows normally, unchanged. That is by design, not a bug. It skips
  45. (fails open) when ollama is down, the request times out, or the model isn't
  46. pulled. The first time that happens in a session it tells you why: the display
  47. hook appends a one-line notice on screen, and the Markdown hook shows a
  48. `systemMessage`. So a silent skip is never a mystery (once per session; set
  49. `CLAUDISH_NOTICE=0` to silence it).
  50. **Pick a model you actually have.** The default is `gemma4:26b-mlx`, an
  51. Apple-silicon (MLX) build — the right choice on a Mac, but **macOS-only**. On
  52. Windows it doesn't run, so you must switch to a regular tag (see
  53. [Windows setup](#windows-setup)). Pull it (as above), or pull a smaller/faster
  54. model and point the plugin at it by setting `CLAUDISH_MODEL` to that model's
  55. exact ollama tag in your `env` (see
  56. [Configuring the plugin](#configuring-the-plugin)). If `CLAUDISH_MODEL` names a
  57. model you have not pulled, every rewrite is skipped — with the one-time notice
  58. above.
  59. </details>
  60. <a id="windows-setup"></a>
  61. <details>
  62. <summary><strong>Windows setup</strong></summary>
  63. The hooks are bash scripts; on Windows, Claude Code runs them through **Git
  64. Bash** (Git for Windows).
  65. | Requirement | Why | Install |
  66. |---|---|---|
  67. | **Ollama**, running | Does the rewriting, locally | `winget install Ollama.Ollama`, then launch the Ollama app; it serves on `localhost:11434` |
  68. | A pulled model | The actual rewriter | `ollama pull gemma4:26b` (choose a model that fits into your memory) |
  69. | `jq` | Parses hook JSON | `winget install jqlang.jq` |
  70. | `curl` | Talks to ollama | ships with Windows 10+ |
  71. | Git Bash | Runs the hook scripts | Claude Code users usually already have it; else `winget install Git.Git` |
  72. Restart your terminal after installing so `jq`, `ollama`, and Git Bash are on
  73. PATH (check `jq --version` and `ollama --version`).
  74. > **The default model is macOS-only — Windows users must override it.** The
  75. > plugin's default, `gemma4:26b-mlx`, is an Apple-silicon (MLX) build that doesn't
  76. > run on Windows, so leaving it unset means every rewrite is silently skipped.
  77. > Always set `CLAUDISH_MODEL` to a regular (non-MLX) tag on Windows. The table
  78. > above uses `gemma4:26b` as an example; choose another if it fits your machine
  79. > better.
  80. Warm the model once after launching Ollama (the first call is a slow cold load):
  81. ```powershell
  82. ollama run gemma4:26b "hi"
  83. ```
  84. Then set `CLAUDISH_MODEL` in the `env` block of your `settings.json` (see
  85. [Configuring the plugin](#configuring-the-plugin) — that method is identical on
  86. Windows), or for a one-off session from PowerShell:
  87. ```powershell
  88. $env:CLAUDISH_MODEL = "gemma4:26b"; claude
  89. ```
  90. Windows equivalents of the mid-session kill switch
  91. ([Toggling mid-session](#toggling-mid-session)):
  92. ```powershell
  93. New-Item -ItemType File $HOME\.claude\claudish-off # pause rewrites
  94. Remove-Item $HOME\.claude\claudish-off # resume
  95. ```
  96. (In Git Bash the `touch`/`rm` commands from that section work as-is.)
  97. Notes:
  98. - Write `CLAUDISH_MD_DIR` with forward slashes
  99. (`C:/dev/docs/plain`) so the bash-side path checks match
  100. - The `CLAUDISH_DEBUG=1` log lands under Git Bash's temp directory
  101. (`$TMPDIR/claudish-to-english/`, typically
  102. `C:\Users\<you>\AppData\Local\Temp\claudish-to-english\`).
  103. </details>
  104. ---
  105. ## Install
  106. Directly from this repository (also serves its own marketplace):
  107. ```shell
  108. /plugin marketplace add gvzdv/claudish-to-english
  109. ```
  110. ```shell
  111. /plugin install claudish-to-english@gvzdv-plugins
  112. ```
  113. The plugin is `Submitted and pending review` on the Claude Marketplace since August 10.
  114. ~~After review by the Anthropic team, the plugin will be available to install from the community marketplace:~~
  115. ~~/plugin marketplace add anthropics/claude-plugins-community~~
  116. ~~/plugin install claudish-to-english@claude-community~~
  117. If the install summary says `Run /reload-plugins to activate.`, run that command.
  118. **Try before installing** (loads it for one session, no install):
  119. ```bash
  120. claude --plugin-dir /path/to/claudish-to-english
  121. ```
  122. Run `/reload-plugins` after edits; if it doesn't load, check the `/plugin`
  123. **Errors** tab.
  124. ---
  125. ## Configuring the plugin
  126. There are two ways to control claudish, and they complement each other:
  127. - **`/claudish`** — a slash command for live, day-to-day toggles: on/off, display
  128. mode, language, and model. Changes take effect immediately, mid-session. This
  129. is what most people reach for. See
  130. [Controlling it live](#controlling-it-live-claudish).
  131. - **`CLAUDISH_*` environment variables** — your durable defaults, and the only
  132. way to set everything `/claudish` doesn't cover (provider, API keys, base URLs,
  133. the Markdown hook, timeouts). Full list in
  134. [Configuration](#configuration-env-vars) below.
  135. Set the durable ones in Claude Code's **`env` block in `settings.json`** — do
  136. **not** edit the plugin's own `hooks/hooks.json`, which lives in the read-only
  137. plugin cache (`~/.claude/plugins/cache/…`) and is overwritten on every update.
  138. For a personal, all-projects setup, use `~/.claude/settings.json`:
  139. ```json
  140. {
  141. "env": {
  142. "CLAUDISH_MODEL": "gemma4:26b-mlx",
  143. "CLAUDISH_MODE": "append"
  144. }
  145. }
  146. ```
  147. The hooks are subprocesses Claude Code spawns, so they inherit these. A few
  148. things to know:
  149. - **Restart Claude Code after editing `env`.** The value is captured at launch,
  150. so a running session keeps the old one.
  151. - **`env` does not merge across scopes.** The highest-precedence settings file
  152. that defines `env` supplies the *entire* block — it isn't combined with lower
  153. scopes. Precedence: managed → local → project → user. Keep all your
  154. `CLAUDISH_*` vars in whichever file wins.
  155. - **Scopes:** `~/.claude/settings.json` (all your projects) ·
  156. `.claude/settings.json` (shared with a repo, checked in) ·
  157. `.claude/settings.local.json` (just you, just this repo).
  158. Quick one-off without editing a file — hooks inherit the launching shell:
  159. ```bash
  160. CLAUDISH_MODEL=llama3.2:3b claude
  161. ```
  162. To confirm the hook is firing, set `CLAUDISH_DEBUG=1` and watch
  163. `"$TMPDIR"/claudish-to-english/debug.log`.
  164. ---
  165. ## Controlling it live: `/claudish`
  166. `/claudish` is the interactive front-end for the four most-used settings —
  167. on/off, display mode, language, and model. Changes take effect on the next
  168. assistant message, mid-session, with nothing to relaunch:
  169. ```
  170. /claudish show the dashboard (current state + where each value comes from)
  171. /claudish on resume rewrites (keeps the current mode)
  172. /claudish off pause rewrites (originals only; also pauses the Markdown hook)
  173. /claudish append show the original, then the rewrite below it
  174. /claudish replace show only the rewrite
  175. /claudish style X rewrite style: tldr | 5y (explain like I'm five) | caveman
  176. /claudish style reset to the default plain-language rewrite
  177. /claudish language fr rewrite into French (any name, incl. non-Latin like 简体中文)
  178. /claudish language reset to the session/settings language (see "Output language")
  179. /claudish model X use model X for whatever provider is configured
  180. /claudish model reset to the provider default
  181. /claudish last reprint the ORIGINAL of the last message (handy in replace mode)
  182. /claudish file PATH rewrite a Markdown file (or URL) into NAME.plain.md (see "on demand" below)
  183. /claudish cycle step off → append → replace → off
  184. /claudish reset clear ALL overrides — back to your env/settings defaults
  185. ```
  186. Bare `/claudish` prints a **dashboard** — each setting, its current value, and
  187. where that value comes from (an env var, a `/claudish` override, your
  188. `settings.json`, or the default):
  189. ```
  190. claudish · plain-language rewrite of each assistant message
  191. status replace · ⚠ /claudish — rewrite only; beats env, persists across sessions
  192. style tldr · ⚠ /claudish — beats env CLAUDISH_STYLE, persists across sessions
  193. language French · ⚠ /claudish — beats env & settings, persists across sessions
  194. model gemma4:26b-mlx · ollama provider default
  195. provider ollama · default
  196. ```
  197. Each switch writes a small flag file under `~/.claude/` that the hooks re-read
  198. every message (the paths and their `CLAUDISH_*_FILE` overrides are in the
  199. [env-var table](#configuration-env-vars); the underlying mechanism is under
  200. [Toggling mid-session](#toggling-mid-session)). A live `/claudish` switch **beats
  201. the matching env var** — `CLAUDISH_MODE`, `CLAUDISH_LANG`, or `CLAUDISH_MODEL`.
  202. **These overrides persist across sessions** (like the off-file), until you clear
  203. them with the per-setting `default` form, `/claudish on`, or `/claudish reset`.
  204. So a `/claudish language French` set today still applies to a session you open
  205. tomorrow. The state is never silent, though: the dashboard flags every persisting
  206. override with ⚠, and a `SessionStart` notice lists any that are active at the top
  207. of a new session (`CLAUDISH_NOTICE=0` silences it). For a *permanent* default,
  208. set the matching env var in `settings.json` rather than using `/claudish`.
  209. `/claudish last` works because the rewrite is display-only: the transcript always
  210. keeps Claude's original text, so the command just reprints it (prefixed with an
  211. internal `<!-- claudish:original -->` marker that tells the display hook not to
  212. rewrite that reply, and which is stripped from view).
  213. ---
  214. ## Output language
  215. The rewrite comes back in the **same language as the text it rewrites**. An
  216. Esperanto answer is simplified into Esperanto, an English one into English;
  217. nothing is translated unless you ask for it.
  218. To pin a language, set one. The hooks read the same `language` key Claude Code
  219. itself answers in, in the same order of precedence, so a session that already
  220. speaks Esperanto needs no extra configuration:
  221. | Source | Example |
  222. |---|---|
  223. | `CLAUDISH_LANG` (env) | `"CLAUDISH_LANG": "Esperanto"` |
  224. | `<project>/.claude/settings.local.json` | `"language": "Esperanto"` |
  225. | `<project>/.claude/settings.json` | `"language": "Esperanto"` |
  226. | `~/.claude/settings.json` | `"language": "Esperanto"` |
  227. The first one that is set wins, and the on-screen label then names it —
  228. 💬 In plain **Esperanto**:
  229. `CLAUDISH_LANG` set but **empty** ignores the settings key and goes back to
  230. following the input's language; set it to `English` to force English on a
  231. non-English session.
  232. A configured language is appended to the built-in prompt. A prompt supplied
  233. through `CLAUDISH_PROMPT_FILE` or `CLAUDISH_MD_PROMPT_FILE` replaces the whole
  234. prompt, language line included — that file is your prompt in full, and it
  235. states its own language (see below).
  236. An unreadable, malformed, or non-string setting is ignored the way every other
  237. failure here is: rewrites keep working, in the input's language.
  238. One caveat: a rewrite is only as good as the model that writes it, and small
  239. local models simplify English noticeably better than they simplify anything
  240. else. If non-English results disappoint, try a larger model or a cloud provider
  241. (see [Providers](#providers)).
  242. ---
  243. ## Customizing the rewrite prompt
  244. Each hook ships with a default system prompt that asks the model for plain
  245. language while preserving facts, code, and structure.
  246. For a quick change of tone without writing a prompt, the display hook also has
  247. three **built-in style presets** — `tldr` (a short summary), `5y` (explain like
  248. I'm five), and `caveman` (blunt caveman speak) — set with
  249. [`/claudish style`](#controlling-it-live-claudish) or
  250. `CLAUDISH_STYLE`. Each one labels its block with its own emoji, so the style in
  251. use is visible at a glance:
  252. | style | label |
  253. |---|---|
  254. | *(default)* | 💬 In plain **language**: |
  255. | `tldr` | 📌 **TL;DR**: |
  256. | `5y` | 👶 Like you're **five**: |
  257. | `caveman` | 🦴 **Ugh.** Me say: |
  258. The bold word is markdown, rendered by Claude Code itself — no ANSI colour
  259. codes, so the label cannot be washed out by a terminal colour scheme and stays
  260. readable when `claude -p` output is piped to a file. For full control, you can instead **replace** either prompt
  261. with your own to add specific rules or use wording that works better with your
  262. model (this wins over a style preset). To do so, point the hook at a file that
  263. holds the prompt:
  264. | Hook | Prompt file |
  265. |---|---|
  266. | Display (`rewrite.sh`) | `CLAUDISH_PROMPT_FILE` |
  267. | Markdown (`rewrite-md.sh`) | `CLAUDISH_MD_PROMPT_FILE` |
  268. The file's contents **replace** the built-in prompt, so
  269. include every instruction you want the model to follow — otherwise the defaults
  270. (keep facts, leave code blocks alone, output only the rewrite) are gone. Keeping
  271. the prompt in a file avoids escaping a long, multi-line prompt inside a JSON
  272. string. If the variable is unset, or the file is empty or unreadable, the hook
  273. falls back to its built-in default, so a bad path never stops rewrites.
  274. ```json
  275. {
  276. "env": {
  277. "CLAUDISH_PROMPT_FILE": "/ABS/PATH/prompts/plain.txt",
  278. "CLAUDISH_MD_PROMPT_FILE": "/ABS/PATH/prompts/md-plain.txt"
  279. }
  280. }
  281. ```
  282. The display hook still appends the **original user question** to your prompt, as
  283. context to keep the rewrite on-topic (see
  284. [How the display hook works](#how-the-display-hook-works)). Your prompt
  285. replaces only the base instruction.
  286. ---
  287. ## How the display hook works
  288. Claude Code fires the `MessageDisplay` event **once per streamed chunk**, not
  289. once per message. Each fire is a separate process carrying `message_id`,
  290. `index`, a `final` flag, and this chunk's `delta` (a text fragment, not the
  291. whole message). So the hook **buffers every delta** to a temp file (keyed by
  292. `message_id`) and only calls the model on the **final** chunk, once the whole
  293. message is known:
  294. ```
  295. chunk 0 (final:false) ─┐
  296. chunk 1 (final:false) ─┤ append each delta to $TMPDIR/claudish-to-english/<session>/<message>/<index>.part
  297. chunk 2 (final:false) ─┘ → emit nothing (append) or "" (replace)
  298. chunk 3 (final:true) ──► reconstruct full message → call ollama once → show the rewrite
  299. → delete the buffer
  300. ```
  301. On that final chunk it also reads the **original user question** from the
  302. transcript and passes it to the model as **context only** — to keep the rewrite
  303. on-topic. The model is told never to answer or repeat the question; it only
  304. rewrites the assistant's message.
  305. ### Display modes
  306. | `CLAUDISH_MODE` | On screen | Notes |
  307. |---|---|---|
  308. | `append` (default) | Original streams normally, then a 💬 In plain **language**: block is appended (💬 In plain **Esperanto**: when a language is configured; other styles use their own emoji — see [Customizing the rewrite prompt](#customizing-the-rewrite-prompt)). | Safest. No streaming loss; if the LLM fails you just don't get the extra block. |
  309. | `replace` | Only the simplified version (original chunks suppressed while streaming). | Experimental. Appears all at once after LLM latency; on failure it re-shows the full original. |
  310. ---
  311. ## Markdown file rewrite (optional second hook)
  312. A `PostToolUse` hook (`rewrite-md.sh`) rewrites Markdown **files** into plain
  313. language when they are written or edited. Unlike the display hook, this changes
  314. bytes on disk.
  315. **Opt-in by directory.** It does nothing unless `CLAUDISH_MD_DIR` is set, and it
  316. only touches `*.md` files whose resolved path is inside that directory. Every
  317. other `README`, `CLAUDE.md`, or doc you edit is left alone.
  318. | `CLAUDISH_MD_MODE` | Result | Notes |
  319. |---|---|---|
  320. | `sibling` (default) | Writes `NAME.plain.md` next to `NAME.md`. | Non-destructive; the original is never touched. |
  321. | `overwrite` | Replaces `NAME.md` in place. | Adds a `<!-- claudish-to-english:rewritten -->` marker so a re-write is skipped (idempotent). A weak model can degrade real docs — use with care. |
  322. In both modes: YAML frontmatter is split off and re-attached **verbatim**, fenced
  323. code is left to the model instruction, short files are skipped, and the write is
  324. atomic. Fail-open here means the file is left **exactly as the agent wrote it**.
  325. **Large files are slow.** `gemma4:26b-mlx` (the default) rewrites at roughly 60
  326. tokens/s, so a long plan or spec can take 30–120s. This hook allows up to
  327. `CLAUDISH_MD_TIMEOUT` (150s) inside a 180s `PostToolUse` hook budget; if a rewrite
  328. still times out you get the one-time notice above — raise those limits, or set
  329. `CLAUDISH_MODEL` to a smaller model.
  330. Enable it for one directory, in sibling mode (the safe default), the same way
  331. as every other setting — the `env` block of your `settings.json`:
  332. ```json
  333. {
  334. "env": {
  335. "CLAUDISH_MD_DIR": "/ABS/PATH/docs/plain",
  336. "CLAUDISH_MD_MODE": "sibling"
  337. }
  338. }
  339. ```
  340. In `overwrite` mode the marker comment is written **after** any YAML
  341. frontmatter, so the frontmatter stays on line 1 where parsers expect it.
  342. ---
  343. ## Rewriting a file or text on demand
  344. The hooks only act on what Claude writes. To rewrite **any** Markdown file, a
  345. Markdown document at a URL, or any text at all, whenever you like, use
  346. `claudish-md.sh`. It gives the same
  347. rewrite as the Markdown hook (same prompt, same frontmatter handling, same
  348. provider, model, and language settings, `/claudish` overrides included), but
  349. you choose the input and where the result goes.
  350. **Inside a session**, point `/claudish` at a file:
  351. ```
  352. /claudish file docs/architecture.md → writes docs/architecture.plain.md
  353. /claudish file ~/notes/meeting notes.md → paths with spaces work; no quotes needed
  354. /claudish file https://github.com/o/r/blob/main/docs/setup.md
  355. → writes ./setup.plain.md in the session's folder
  356. ```
  357. It writes `NAME.plain.md` next to the file and replies with one line naming it.
  358. The rewrite is not shown in the chat, so Claude never has to read the whole
  359. document back to you. Open the file to read it.
  360. **From a terminal**, run the script directly:
  361. ```bash
  362. claudish-md.sh notes.md # rewrite -> stdout
  363. claudish-md.sh notes.md -o simple.md # rewrite -> simple.md
  364. claudish-md.sh notes.md --sibling # rewrite -> notes.plain.md
  365. pbpaste | claudish-md.sh # any text on stdin -> stdout
  366. claudish-md.sh -l English notes.md # into English, whatever the input language
  367. claudish-md.sh https://example.com/guide.md # a URL -> stdout
  368. claudish-md.sh file:///Users/me/notes/guide.md # a file:// link works like the path
  369. claudish-md.sh 'C:\Users\me\notes\guide.md' # Windows paths too (Git Bash); quote backslashes
  370. claudish-md.sh --sibling https://example.com/guide.md # -> ./guide.plain.md
  371. ```
  372. **URLs.** Any public `http(s)` link to a Markdown or plain-text file works.
  373. Links to a *rendered* page on GitHub (`…/blob/…`), GitLab (`…/-/blob/…`), or
  374. Gist are quietly switched to the raw file, because the page itself is HTML. Any
  375. other page that comes back as HTML is refused with a message, rather than
  376. rewritten. The download is unauthenticated, so private repositories answer
  377. 404. It is limited to `CLAUDISH_MD_MAX_BYTES` (1 MB) and
  378. `CLAUDISH_MD_FETCH_TIMEOUT` (30s), and only `http`/`https` are followed, on
  379. redirects too. With `--sibling` (and `/claudish file`) the output is named
  380. after the last part of the URL and written in the current folder, since there
  381. is no folder next to a URL.
  382. For an installed plugin, the script is in the plugin cache. Bare `/claudish`
  383. prints its full path on the `files` line of the dashboard. That path changes
  384. when the plugin updates, so if you use the script often, an alias that finds
  385. the latest copy keeps working:
  386. ```bash
  387. alias claudish-md='"$(ls -d ~/.claude/plugins/cache/*/claudish-to-english/*/ | sort -V | tail -1)claudish-md.sh"'
  388. ```
  389. **Output language.** Like everything else in the plugin, the rewrite keeps the
  390. input's own language unless a language is configured (see
  391. [Output language](#output-language)). For English specifically, pass
  392. `-l English`, or set `/claudish language English` once — that also applies to
  393. `/claudish file`.
  394. How it differs from the hook, on purpose — you asked for *this* rewrite:
  395. - **No gates.** It ignores `CLAUDISH_MD_DIR`, the `.md` extension, and
  396. `CLAUDISH_MIN_CHARS`. It also runs while rewrites are paused
  397. (`/claudish off`), because pausing only stops the automatic hooks.
  398. - **It fails loudly.** A hook fails open by leaving the original on screen. A
  399. command you ran has no original to fall back to, so any problem (provider
  400. down, timeout, missing key, bad path) prints `claudish-md: <reason>` and exits
  401. non-zero. It still never prints or writes a partial or empty rewrite, and a
  402. file target is replaced atomically, only on success.
  403. - **Timeout.** The LLM call uses `CLAUDISH_MD_TIMEOUT` (150s). Under
  404. `/claudish file` it is capped at 110s (90s plus a 20s download for a URL),
  405. because Claude Code stops a slash command's shell step at 2 minutes. For a long document on a slow local
  406. model, run it from a terminal with a higher limit
  407. (`CLAUDISH_MD_TIMEOUT=600 claudish-md.sh --sibling big.md`), or pick a
  408. smaller model.
  409. Exit codes: `0` done, `1` the rewrite failed, `2` usage error. When writing a
  410. file, the absolute path written is printed on stdout.
  411. ---
  412. ## Providers
  413. Rewrites go through one of four providers, selected with `CLAUDISH_PROVIDER`
  414. (both hooks share the setting). The default is unchanged from upstream: local
  415. ollama, nothing leaves your machine.
  416. | Provider | Endpoint | Key | Default model |
  417. |---|---|---|---|
  418. | `ollama` (default) | `CLAUDISH_OLLAMA` (`http://localhost:11434`) | none | `gemma4:26b-mlx` |
  419. | `codex` | OpenAI codex CLI (`codex exec`) — uses the CLI's own login | none | *(CLI default)* |
  420. | `anthropic` | `CLAUDISH_ANTHROPIC_URL` (`https://api.anthropic.com`) + `/v1/messages` | `CLAUDISH_ANTHROPIC_KEY` or `ANTHROPIC_API_KEY` | `claude-haiku-4-5` |
  421. | `openai` | `CLAUDISH_OPENAI_URL` + `/chat/completions` | `CLAUDISH_OPENAI_KEY` or `OPENAI_API_KEY` | `gpt-5.6-luna` |
  422. ### codex
  423. `CLAUDISH_PROVIDER=codex` runs the rewrite through the OpenAI codex CLI
  424. (`codex exec`, read-only sandbox, outside any repo), using the CLI's own
  425. login. No API key and no local model server. `CLAUDISH_MODEL` overrides
  426. the CLI's configured model; unset uses the CLI default. `CLAUDISH_CODEX_EFFORT`
  427. overrides the CLI's reasoning effort for the rewrite only (e.g. `low` keeps a
  428. per-message rewrite fast even when the CLI's coding default is a high-effort
  429. tier). Requires `codex` on PATH; fails open like every other provider.
  430. > [!CAUTION]
  431. > The cloud providers pick their key up from the **ambient environment**
  432. > (`OPENAI_API_KEY` / `ANTHROPIC_API_KEY`), and `CLAUDISH_OPENAI_URL` defaults
  433. > to api.openai.com. Anything that puts those variables into the environment
  434. > Claude Code launches with — an `export` in your shell profile, a tool like
  435. > direnv loading a project's `.env` into your shell, or the `env` block of a
  436. > settings file — makes them visible to this plugin. In such an environment,
  437. > setting the single variable `CLAUDISH_PROVIDER=openai` starts sending every
  438. > assistant message (and, with the Markdown hook, file contents) to OpenAI's
  439. > cloud. Likewise, `CLAUDISH_PROVIDER=anthropic` will quietly spend the same
  440. > `ANTHROPIC_API_KEY` (and share its rate limits) that other tools on your
  441. > machine may rely on. Selecting a cloud provider IS the consent switch — set
  442. > it only when you mean it, and use the `CLAUDISH_*_KEY` variables when you
  443. > want the plugin on a dedicated key.
  444. ```bash
  445. # ollama (default) — local, nothing leaves your machine
  446. export CLAUDISH_PROVIDER=ollama
  447. export CLAUDISH_MODEL=gemma4:26b-mlx # the default; any pulled tag works
  448. # Anthropic — Claude Haiku
  449. export CLAUDISH_PROVIDER=anthropic
  450. export ANTHROPIC_API_KEY=sk-ant-...
  451. export CLAUDISH_MODEL=claude-haiku-4-5 # the default; override to taste
  452. # Anthropic — no API key: ride the Claude Code login you're already using.
  453. # Re-reads the OAuth access token from the macOS login Keychain (item
  454. # `Claude Code-credentials`), or ~/.claude/.credentials.json elsewhere, on
  455. # every call (Claude Code keeps it fresh while running, and these hooks only
  456. # run while it runs; a token past its expiresAt is discarded, not sent), and
  457. # authenticates with Authorization: Bearer + the oauth-2025-04-20 beta flag
  458. # instead of x-api-key. Rewrites then ride your Claude subscription — no
  459. # separate API billing. The token is only ever sent to
  460. # https://api.anthropic.com: this mode refuses to run with a
  461. # CLAUDISH_ANTHROPIC_URL override, so the credential cannot leak to a proxy.
  462. #
  463. # ⚠️ UNOFFICIAL — USE AT YOUR OWN RISK. Anthropic has not blessed third-party
  464. # use of the Claude Code token: this mode may stop working without warning,
  465. # and programmatic use of a subscription credential could put your Claude
  466. # account at risk. The first rewrite of each session repeats this caution on
  467. # screen. When the mode breaks, the hook fails open (original text,
  468. # once-per-session notice) like every other failure.
  469. export CLAUDISH_PROVIDER=anthropic
  470. export CLAUDISH_ANTHROPIC_AUTH=oauth
  471. export CLAUDISH_MODEL=claude-haiku-4-5 # the default; override to taste
  472. # OpenAI — GPT-5.6 Luna
  473. export CLAUDISH_PROVIDER=openai
  474. export OPENAI_API_KEY=sk-...
  475. export CLAUDISH_MODEL=gpt-5.6-luna # the default; override to taste
  476. # Any OpenAI-compatible server (LM Studio, llama.cpp server, vLLM, OpenRouter).
  477. # A key is only required for api.openai.com — local servers work keyless.
  478. export CLAUDISH_PROVIDER=openai
  479. export CLAUDISH_OPENAI_URL=http://localhost:1234/v1
  480. export CLAUDISH_MODEL=qwen3-30b
  481. ```
  482. Notes:
  483. - `CLAUDISH_MODEL` overrides any provider's default model.
  484. - Requests to api.openai.com send `reasoning_effort: "none"` (GPT-5.6-class
  485. models otherwise spend reasoning tokens on a plain rewrite). Custom
  486. OpenAI-compatible URLs get no such field, since some local servers reject
  487. unknown fields. Force one with `CLAUDISH_OPENAI_EFFORT`, or set it
  488. **explicitly empty** (`CLAUDISH_OPENAI_EFFORT=`) to omit the field even for
  489. api.openai.com — needed for models that reject `reasoning_effort` entirely.
  490. - The anthropic provider caps completions at `CLAUDISH_MAX_TOKENS` (default
  491. 4096, since the Messages API requires an explicit cap).
  492. - A rewrite that hits an output-token cap is **discarded**, not shown — on the
  493. ollama, anthropic, and openai providers (ollama's `done_reason: "length"`
  494. included): a half-finished
  495. rewrite on screen is confusing, and in the Markdown hook's `overwrite` mode
  496. it would replace your real document. You get the original text plus the
  497. once-per-session notice suggesting a higher cap.
  498. - Every provider failure stays fail-open: missing key, bad key, unreachable
  499. endpoint, or timeout just leaves the original text (plus the once-per-session
  500. notice, unless `CLAUDISH_NOTICE=0`).
  501. > **Privacy:** the cloud providers send each assistant message (and, for the
  502. > Markdown hook, file contents) to an external API. Read
  503. > [Privacy / egress](#privacy--egress) before switching away from ollama.
  504. ---
  505. ## Configuration (env vars)
  506. | Var | Default | Meaning |
  507. |---|---|---|
  508. | `CLAUDISH_ENABLED` | `1` | Master switch. `0` = pass everything through. Read once at session start. |
  509. | `CLAUDISH_OFF_FILE` | `~/.claude/claudish-off` | Runtime kill switch. While this file exists, rewrites pause — re-checked every message, so unlike env vars it works mid-session. See [Toggling mid-session](#toggling-mid-session). |
  510. | `CLAUDISH_MODE` | `append` | `append` or `replace` (display hook). |
  511. | `CLAUDISH_MODE_FILE` | `~/.claude/claudish-mode` | Runtime display-mode override: `append`/`replace` in this file wins over `CLAUDISH_MODE`, re-checked every message. Written by `/claudish append`/`replace`. See [Controlling it live](#controlling-it-live-claudish). |
  512. | `CLAUDISH_STYLE` | *(unset)* | Rewrite-style preset (display hook): `tldr` = a clearly shorter summary, `5y` = explain like I'm five, `caveman` = blunt caveman speak. Unset = the default plain-language rewrite. A usable `CLAUDISH_PROMPT_FILE` wins over any style (custom prompt > style > built-in); the output language still applies. |
  513. | `CLAUDISH_STYLE_FILE` | `~/.claude/claudish-style` | Runtime style override: `tldr`/`5y`/`caveman` in this file wins over `CLAUDISH_STYLE`, re-checked every message. Written by `/claudish style <tldr\|5y\|caveman>`. See [Controlling it live](#controlling-it-live-claudish). |
  514. | `CLAUDISH_PROMPT_FILE` | *(unset)* | Path to a file whose contents replace the display hook's system prompt (whole prompt, not merged). Empty/unreadable falls back to the built-in default. See [Customizing the rewrite prompt](#customizing-the-rewrite-prompt). |
  515. | `CLAUDISH_LANG` | *(unset)* | Language to rewrite into, e.g. `Esperanto`. Unset falls back to the `language` key in `.claude/settings*.json`; with neither set, the rewrite keeps the input's language. Empty ignores the settings key; `English` forces English. See [Output language](#output-language). |
  516. | `CLAUDISH_LANG_FILE` | `~/.claude/claudish-lang` | Runtime language override: a language name in this file wins over `CLAUDISH_LANG` and the settings key, re-checked every message. Written by `/claudish language <name>`. See [Controlling it live](#controlling-it-live-claudish). |
  517. | `CLAUDISH_PROVIDER` | `ollama` | `ollama`, `codex`, `anthropic`, or `openai` — which LLM serves rewrites (both hooks). |
  518. | `CLAUDISH_MODEL` | *(per provider)* | Model name; overrides the provider default (see [Providers](#providers)). The ollama default `gemma4:26b-mlx` is MLX (Apple-silicon only; Windows users must override). |
  519. | `CLAUDISH_MODEL_FILE` | `~/.claude/claudish-model` | Runtime model override: a model name in this file wins over `CLAUDISH_MODEL`, re-checked every message (applies to whatever provider is configured). Written by `/claudish model <name>`. See [Controlling it live](#controlling-it-live-claudish). |
  520. | `CLAUDISH_OLLAMA` | `http://localhost:11434` | ollama base URL. |
  521. | `CLAUDISH_ANTHROPIC_KEY` | *(unset)* | Anthropic API key; falls back to `ANTHROPIC_API_KEY`. |
  522. | `CLAUDISH_OPENAI_KEY` | *(unset)* | OpenAI(-compatible) API key; falls back to `OPENAI_API_KEY`. Only required for api.openai.com. |
  523. | `CLAUDISH_OPENAI_URL` | `https://api.openai.com/v1` | Base URL for any OpenAI-compatible endpoint (LM Studio, llama.cpp server, vLLM, OpenRouter, ...). Trailing slashes are ignored. |
  524. | `CLAUDISH_ANTHROPIC_URL` | `https://api.anthropic.com` | Base URL for the anthropic provider — override for proxies/gateways that speak the Messages API. |
  525. | `CLAUDISH_OPENAI_EFFORT` | `none` on api.openai.com, else *(unset)* | `reasoning_effort` sent with openai-provider requests. Set explicitly empty to omit the field. |
  526. | `CLAUDISH_CODEX_EFFORT` | *(unset)* | `model_reasoning_effort` for the codex provider (e.g. `low`). Unset uses the codex CLI's configured effort. Applies to the rewrite only. |
  527. | `CLAUDISH_MAX_TOKENS` | `4096` | Completion cap for the anthropic provider. Rewrites that hit the cap are discarded (fail-open), with a notice to raise it. |
  528. | `CLAUDISH_MIN_CHARS` | `200` | Skip messages/files whose prose (code stripped) is shorter than this. Counted in **characters**, so one threshold means the same length in every script. |
  529. | `CLAUDISH_STUB` | `0` | `1` = deterministic stub instead of the model (for testing display mechanics). |
  530. | `CLAUDISH_TIMEOUT` | `45` | LLM client timeout for the **display** hook (seconds). Keep it below that hook's `timeout` (60s). |
  531. | `CLAUDISH_MD_TIMEOUT` | `150` | LLM client timeout for the **Markdown file** hook and for `claudish-md.sh` (seconds). Higher on purpose — a large model rewriting a long doc is slow. Keep it below the `PostToolUse` hook `timeout` (180s). |
  532. | `CLAUDISH_DEBUG` | `0` | `1` = write a debug log to `$TMPDIR/claudish-to-english/`. |
  533. | `CLAUDISH_NOTICE` | `1` | `1` = show a one-time, once-per-session notice when a rewrite is skipped because the provider is unreachable, the call timed out, a key is missing, or the model isn't available (display hook appends it on screen; Markdown hook uses a `systemMessage`). Also gates the `SessionStart` notice that announces leftover `/claudish` overrides. `0` = stay fully silent (pure fail-open). |
  534. | `CLAUDISH_MD_DIR` | *(unset)* | **Markdown hook opt-in.** Only `*.md` under this directory is rewritten. Unset = the Markdown hook does nothing. |
  535. | `CLAUDISH_MD_MODE` | `sibling` | `sibling` (`NAME.plain.md`) or `overwrite` (in place). |
  536. | `CLAUDISH_MD_FETCH_TIMEOUT` | `30` | Download timeout (seconds) when `claudish-md.sh` or `/claudish file` is given a URL. Capped at 20 under `/claudish file`. |
  537. | `CLAUDISH_MD_MAX_BYTES` | `1048576` | Largest document `claudish-md.sh` will download from a URL; anything bigger is refused. |
  538. | `CLAUDISH_MD_SUFFIX` | `plain` | Sibling infix: `NAME.<suffix>.md` (Markdown hook, `claudish-md.sh --sibling`, `/claudish file`). |
  539. | `CLAUDISH_MD_PROMPT_FILE` | *(unset)* | Path to a file whose contents replace the Markdown system prompt (whole prompt, not merged), for both the hook and `claudish-md.sh`. Empty/unreadable falls back to the built-in default. |
  540. In `hooks/hooks.json` the display hook (`MessageDisplay`) has a 60s `timeout` and
  541. the Markdown hook (`PostToolUse`) has a 180s `timeout` — the file hook is higher
  542. because a large model rewriting a long document can take a couple of minutes.
  543. `CLAUDISH_TIMEOUT` and `CLAUDISH_MD_TIMEOUT` keep the LLM call itself bounded
  544. below those ceilings, so it fails open cleanly instead of being killed mid-write.
  545. **Quick kill switch:** set `CLAUDISH_ENABLED=0` or disable the plugin (both apply
  546. only from the next session start), or `touch ~/.claude/claudish-off` to pause a
  547. session that's already running — see [Toggling mid-session](#toggling-mid-session)
  548. below.
  549. ### Toggling mid-session
  550. `CLAUDISH_ENABLED` and the other env vars are read once, when a session launches,
  551. so they can't pause rewrites in a session that's already running. For that, both
  552. hooks also check a **flag file** on every invocation — each fire is a fresh
  553. process, so the check is always live:
  554. ```bash
  555. touch ~/.claude/claudish-off # pause rewrites, effective on the next message
  556. rm ~/.claude/claudish-off # resume
  557. ```
  558. You create and remove this file yourself; nothing creates it on install, and its
  559. absence is the normal "on" state. While it exists, `ENABLED` is forced to `0` and
  560. the fail-open path leaves Claude's original text untouched. Point a hotkey at a
  561. two-line toggle script to flip rewrites from the keyboard across all running
  562. sessions at once. Override the path with `CLAUDISH_OFF_FILE`. `/claudish`
  563. ([Controlling it live](#controlling-it-live-claudish)) is the friendly front-end
  564. for this, writing the same kind of flag files for mode, language, and model too.
  565. ### Reasoning models
  566. The ollama request sends `"think": false`, and openai-provider requests to
  567. api.openai.com send `reasoning_effort: "none"`. Models with a hidden reasoning
  568. phase otherwise spend most of their time generating reasoning tokens you never
  569. see — much slower for identical output quality on this simple task. Keep it off.
  570. ---
  571. ## Privacy / egress
  572. With the default provider the rewriter runs **entirely locally** against
  573. ollama, so **no conversation content leaves your machine**. Setting
  574. `CLAUDISH_PROVIDER` to `anthropic` or `openai` changes that deliberately: every
  575. rewritten assistant message (and, with the Markdown hook enabled or when you
  576. run `claudish-md.sh` / `/claudish file`, file contents) is sent to that API.
  577. Giving `claudish-md.sh` a URL also makes a plain download request to that host,
  578. whatever the provider. The same applies to pointing `CLAUDISH_OLLAMA`
  579. or `CLAUDISH_OPENAI_URL` at a remote/hosted endpoint. Don't switch away from
  580. local unless you understand and accept it.
  581. ---
  582. ## Layout
  583. ```
  584. claudish-to-english/
  585. ├── .claude-plugin/
  586. │ ├── plugin.json # plugin manifest
  587. │ └── marketplace.json # so the repo can be added as a marketplace directly
  588. ├── commands/
  589. │ └── claudish.md # /claudish slash command (runtime on/off, mode, language, model, last, file)
  590. ├── hooks/
  591. │ └── hooks.json # SessionStart -> session-notice.sh ; MessageDisplay -> rewrite.sh ; PostToolUse -> rewrite-md.sh
  592. ├── rewrite.sh # display-rewrite hook
  593. ├── rewrite-md.sh # markdown-file rewrite hook (opt-in)
  594. ├── claudish-md.sh # on-demand rewrite of a file or stdin (CLI; backs /claudish file)
  595. ├── md-core.sh # Markdown frontmatter split + prompt, shared by rewrite-md.sh and claudish-md.sh
  596. ├── claudish-ctl.sh # runtime state switcher + dashboard backing /claudish (writes the flag files)
  597. ├── session-notice.sh # SessionStart hook: announces leftover /claudish overrides on a new session
  598. ├── providers.sh # provider layer (ollama/anthropic/openai), sourced by both hooks
  599. ├── lang.sh # output-language resolver (env + .claude/settings*.json), sourced by both hooks
  600. ├── CHANGELOG.md # notable changes per version (Keep a Changelog)
  601. ├── LICENSE
  602. └── README.md
  603. ```
  604. ## Contributing
  605. Bug reports and PRs welcome. See **[CONTRIBUTING.md](CONTRIBUTING.md)** for how
  606. to set up a working copy, how to test a change without a provider
  607. (`CLAUDISH_STUB=1`), the one rule that outranks everything (every hook must
  608. **fail open**), and the traps that have bitten before — a new style preset
  609. touches four files, and on-screen text must never use ANSI colour codes.
  610. Add your changelog entry under `## [Unreleased]`; the maintainer cuts releases.
  611. ## License
  612. MIT — see [LICENSE](./LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.