claudish-to-english

A Claude Code plugin that shows a plain-English rewrite of each assistant message, produced by a local LLM via ollama (default), the codex CLI, the Anthropic API, or any OpenAI-compatible API. It is display-only: Claude's own reasoning and the saved transcript keep the original text — only what you read on screen changes.

If your session speaks something other than English, so does the rewrite: it follows the message's own language, or the language setting Claude Code already answers in. See Output language.

An optional second hook rewrites Markdown files into plain language when they are written or edited (opt-in, off by default).

Status: working prototype. Every hook fails open — if anything goes wrong (provider down, timeout, missing key or dependency), you simply see Claude's original text. The plugin can never swallow or corrupt an answer.

Requirements (read this first)

With the default ollama provider this plugin shells out to a local model, and nothing works until these are in place. (With CLAUDISH_PROVIDER=anthropic or openai you need only jq, curl, and an API key — see Providers.)

ollama run gemma4:26b-mlx "hi"

ollama run gemma4:26b "hi"

$env:CLAUDISH_MODEL = "gemma4:26b"; claude

New-Item -ItemType File $HOME\.claude\claudish-off   # pause rewrites
Remove-Item $HOME\.claude\claudish-off               # resume

Install

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

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

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.

Configuring the plugin

There are two ways to control claudish, and they complement each other:

• /claudish — a slash command for live, day-to-day toggles: on/off, display mode, language, and model. Changes take effect immediately, mid-session. This is what most people reach for. See Controlling it live.
• CLAUDISH_* environment variables — your durable defaults, and the only way to set everything /claudish doesn't cover (provider, API keys, base URLs, the Markdown hook, timeouts). Full list in Configuration below.

Set the durable ones in Claude Code's env block in settings.json — do not edit the plugin's own hooks/hooks.json, which lives in the read-only plugin cache (~/.claude/plugins/cache/…) and is overwritten on every update.

For a personal, all-projects setup, use ~/.claude/settings.json:

{
  "env": {
    "CLAUDISH_MODEL": "gemma4:26b-mlx",
    "CLAUDISH_MODE": "append"
  }
}

The hooks are subprocesses Claude Code spawns, so they inherit these. A few things to know:

• Restart Claude Code after editing env. The value is captured at launch, so a running session keeps the old one.
• env does not merge across scopes. The highest-precedence settings file that defines env supplies the entire block — it isn't combined with lower scopes. Precedence: managed → local → project → user. Keep all your CLAUDISH_* vars in whichever file wins.
• Scopes: ~/.claude/settings.json (all your projects) · .claude/settings.json (shared with a repo, checked in) · .claude/settings.local.json (just you, just this repo).

Quick one-off without editing a file — hooks inherit the launching shell:

CLAUDISH_MODEL=llama3.2:3b claude

To confirm the hook is firing, set CLAUDISH_DEBUG=1 and watch "$TMPDIR"/claudish-to-english/debug.log.

Controlling it live: /claudish

/claudish is the interactive front-end for the four most-used settings — on/off, display mode, language, and model. Changes take effect on the next assistant message, mid-session, with nothing to relaunch:

/claudish              show the dashboard (current state + where each value comes from)
/claudish on           resume rewrites (keeps the current mode)
/claudish off          pause rewrites (originals only; also pauses the Markdown hook)
/claudish append       show the original, then the rewrite below it
/claudish replace      show only the rewrite
/claudish style tldr   rewrite as a short summary (or "5y" = explain like I'm five)
/claudish style        reset to the default plain-language rewrite
/claudish language fr  rewrite into French (any name, incl. non-Latin like 简体中文)
/claudish language     reset to the session/settings language (see "Output language")
/claudish model X      use model X for whatever provider is configured
/claudish model        reset to the provider default
/claudish last         reprint the ORIGINAL of the last message (handy in replace mode)
/claudish cycle        step off → append → replace → off
/claudish reset        clear ALL overrides — back to your env/settings defaults

Bare /claudish prints a dashboard — each setting, its current value, and where that value comes from (an env var, a /claudish override, your settings.json, or the default):

  claudish · plain-language rewrite of each assistant message

  status    replace          · ⚠ /claudish — rewrite only; beats env, persists across sessions
  style     tldr             · ⚠ /claudish — beats env CLAUDISH_STYLE, persists across sessions
  language  French           · ⚠ /claudish — beats env & settings, persists across sessions
  model     gemma4:26b-mlx   · ollama provider default
  provider  ollama           · default

Each switch writes a small flag file under ~/.claude/ that the hooks re-read every message (the paths and their CLAUDISH_*_FILE overrides are in the env-var table; the underlying mechanism is under Toggling mid-session). A live /claudish switch beats the matching env var — CLAUDISH_MODE, CLAUDISH_LANG, or CLAUDISH_MODEL.

These overrides persist across sessions (like the off-file), until you clear them with the per-setting default form, /claudish on, or /claudish reset. So a /claudish language French set today still applies to a session you open tomorrow. The state is never silent, though: the dashboard flags every persisting override with ⚠, and a SessionStart notice lists any that are active at the top of a new session (CLAUDISH_NOTICE=0 silences it). For a permanent default, set the matching env var in settings.json rather than using /claudish.

/claudish last works because the rewrite is display-only: the transcript always keeps Claude's original text, so the command just reprints it (prefixed with an internal <!-- claudish:original --> marker that tells the display hook not to rewrite that reply, and which is stripped from view).

Output language

The rewrite comes back in the same language as the text it rewrites. An Esperanto answer is simplified into Esperanto, an English one into English; nothing is translated unless you ask for it.

To pin a language, set one. The hooks read the same language key Claude Code itself answers in, in the same order of precedence, so a session that already speaks Esperanto needs no extra configuration:

The first one that is set wins, and the on-screen label then names it: 💬 In plain Esperanto:. CLAUDISH_LANG set but empty ignores the settings key and goes back to following the input's language; set it to English to force English on a non-English session.

A configured language is appended to the built-in prompt. A prompt supplied through CLAUDISH_PROMPT_FILE or CLAUDISH_MD_PROMPT_FILE replaces the whole prompt, language line included — that file is your prompt in full, and it states its own language (see below).

An unreadable, malformed, or non-string setting is ignored the way every other failure here is: rewrites keep working, in the input's language.

One caveat: a rewrite is only as good as the model that writes it, and small local models simplify English noticeably better than they simplify anything else. If non-English results disappoint, try a larger model or a cloud provider (see Providers).

Customizing the rewrite prompt

Each hook ships with a default system prompt that asks the model for plain language while preserving facts, code, and structure.

For a quick change of tone without writing a prompt, the display hook also has two built-in style presets — tldr (a short summary) and 5y (explain like I'm five) — set with /claudish style or CLAUDISH_STYLE. For full control, you can instead replace either prompt with your own to add specific rules or use wording that works better with your model (this wins over a style preset). To do so, point the hook at a file that holds the prompt:

The file's contents replace the built-in prompt, so include every instruction you want the model to follow — otherwise the defaults (keep facts, leave code blocks alone, output only the rewrite) are gone. Keeping the prompt in a file avoids escaping a long, multi-line prompt inside a JSON string. If the variable is unset, or the file is empty or unreadable, the hook falls back to its built-in default, so a bad path never stops rewrites.

{
  "env": {
    "CLAUDISH_PROMPT_FILE": "/ABS/PATH/prompts/plain.txt",
    "CLAUDISH_MD_PROMPT_FILE": "/ABS/PATH/prompts/md-plain.txt"
  }
}

The display hook still appends the original user question to your prompt, as context to keep the rewrite on-topic (see How the display hook works). Your prompt replaces only the base instruction.

How the display hook works

Claude Code fires the MessageDisplay event once per streamed chunk, not once per message. Each fire is a separate process carrying message_id, index, a final flag, and this chunk's delta (a text fragment, not the whole message). So the hook buffers every delta to a temp file (keyed by message_id) and only calls the model on the final chunk, once the whole message is known:

chunk 0 (final:false) ─┐
chunk 1 (final:false) ─┤ append each delta to $TMPDIR/claudish-to-english/<session>/<message>/<index>.part
chunk 2 (final:false) ─┘  → emit nothing (append) or "" (replace)
chunk 3 (final:true)  ──► reconstruct full message → call ollama once → show the rewrite
                          → delete the buffer

On that final chunk it also reads the original user question from the transcript and passes it to the model as context only — to keep the rewrite on-topic. The model is told never to answer or repeat the question; it only rewrites the assistant's message.

Display modes

Markdown file rewrite (optional second hook)

A PostToolUse hook (rewrite-md.sh) rewrites Markdown files into plain language when they are written or edited. Unlike the display hook, this changes bytes on disk.

Opt-in by directory. It does nothing unless CLAUDISH_MD_DIR is set, and it only touches *.md files whose resolved path is inside that directory. Every other README, CLAUDE.md, or doc you edit is left alone.

In both modes: YAML frontmatter is split off and re-attached verbatim, fenced code is left to the model instruction, short files are skipped, and the write is atomic. Fail-open here means the file is left exactly as the agent wrote it.

Large files are slow. gemma4:26b-mlx (the default) rewrites at roughly 60 tokens/s, so a long plan or spec can take 30–120s. This hook allows up to CLAUDISH_MD_TIMEOUT (150s) inside a 180s PostToolUse hook budget; if a rewrite still times out you get the one-time notice above — raise those limits, or set CLAUDISH_MODEL to a smaller model.

Enable it for one directory, in sibling mode (the safe default), the same way as every other setting — the env block of your settings.json:

{
  "env": {
    "CLAUDISH_MD_DIR": "/ABS/PATH/docs/plain",
    "CLAUDISH_MD_MODE": "sibling"
  }
}

In overwrite mode the marker comment is written after any YAML frontmatter, so the frontmatter stays on line 1 where parsers expect it.

Providers

Rewrites go through one of four providers, selected with CLAUDISH_PROVIDER (both hooks share the setting). The default is unchanged from upstream: local ollama, nothing leaves your machine.

codex

CLAUDISH_PROVIDER=codex runs the rewrite through the OpenAI codex CLI (codex exec, read-only sandbox, outside any repo), using the CLI's own login. No API key and no local model server. CLAUDISH_MODEL overrides the CLI's configured model; unset uses the CLI default. CLAUDISH_CODEX_EFFORT overrides the CLI's reasoning effort for the rewrite only (e.g. low keeps a per-message rewrite fast even when the CLI's coding default is a high-effort tier). Requires codex on PATH; fails open like every other provider.

[!CAUTION] The cloud providers pick their key up from the ambient environment (OPENAI_API_KEY / ANTHROPIC_API_KEY), and CLAUDISH_OPENAI_URL defaults to api.openai.com. Anything that puts those variables into the environment Claude Code launches with — an export in your shell profile, a tool like direnv loading a project's .env into your shell, or the env block of a settings file — makes them visible to this plugin. In such an environment, setting the single variable CLAUDISH_PROVIDER=openai starts sending every assistant message (and, with the Markdown hook, file contents) to OpenAI's cloud. Likewise, CLAUDISH_PROVIDER=anthropic will quietly spend the same ANTHROPIC_API_KEY (and share its rate limits) that other tools on your machine may rely on. Selecting a cloud provider IS the consent switch — set it only when you mean it, and use the CLAUDISH_*_KEY variables when you want the plugin on a dedicated key.

# ollama (default) — local, nothing leaves your machine
export CLAUDISH_PROVIDER=ollama
export CLAUDISH_MODEL=gemma4:26b-mlx        # the default; any pulled tag works

# Anthropic — Claude Haiku
export CLAUDISH_PROVIDER=anthropic
export ANTHROPIC_API_KEY=sk-ant-...
export CLAUDISH_MODEL=claude-haiku-4-5      # the default; override to taste

# OpenAI — GPT-5.6 Luna
export CLAUDISH_PROVIDER=openai
export OPENAI_API_KEY=sk-...
export CLAUDISH_MODEL=gpt-5.6-luna          # the default; override to taste

# Any OpenAI-compatible server (LM Studio, llama.cpp server, vLLM, OpenRouter).
# A key is only required for api.openai.com — local servers work keyless.
export CLAUDISH_PROVIDER=openai
export CLAUDISH_OPENAI_URL=http://localhost:1234/v1
export CLAUDISH_MODEL=qwen3-30b

Notes:

• CLAUDISH_MODEL overrides any provider's default model.
• Requests to api.openai.com send reasoning_effort: "none" (GPT-5.6-class models otherwise spend reasoning tokens on a plain rewrite). Custom OpenAI-compatible URLs get no such field, since some local servers reject unknown fields. Force one with CLAUDISH_OPENAI_EFFORT, or set it explicitly empty (CLAUDISH_OPENAI_EFFORT=) to omit the field even for api.openai.com — needed for models that reject reasoning_effort entirely.
• The anthropic provider caps completions at CLAUDISH_MAX_TOKENS (default 4096, since the Messages API requires an explicit cap).
• A rewrite that hits an output-token cap is discarded, not shown — on the ollama, anthropic, and openai providers (ollama's done_reason: "length" included): a half-finished rewrite on screen is confusing, and in the Markdown hook's overwrite mode it would replace your real document. You get the original text plus the once-per-session notice suggesting a higher cap.
• Every provider failure stays fail-open: missing key, bad key, unreachable endpoint, or timeout just leaves the original text (plus the once-per-session notice, unless CLAUDISH_NOTICE=0).

Privacy: the cloud providers send each assistant message (and, for the Markdown hook, file contents) to an external API. Read Privacy / egress before switching away from ollama.

Configuration (env vars)

In hooks/hooks.json the display hook (MessageDisplay) has a 60s timeout and the Markdown hook (PostToolUse) has a 180s timeout — the file hook is higher because a large model rewriting a long document can take a couple of minutes. CLAUDISH_TIMEOUT and CLAUDISH_MD_TIMEOUT keep the LLM call itself bounded below those ceilings, so it fails open cleanly instead of being killed mid-write.

Quick kill switch: set CLAUDISH_ENABLED=0 or disable the plugin (both apply only from the next session start), or touch ~/.claude/claudish-off to pause a session that's already running — see Toggling mid-session below.

Toggling mid-session

CLAUDISH_ENABLED and the other env vars are read once, when a session launches, so they can't pause rewrites in a session that's already running. For that, both hooks also check a flag file on every invocation — each fire is a fresh process, so the check is always live:

touch ~/.claude/claudish-off   # pause rewrites, effective on the next message
rm    ~/.claude/claudish-off   # resume

You create and remove this file yourself; nothing creates it on install, and its absence is the normal "on" state. While it exists, ENABLED is forced to 0 and the fail-open path leaves Claude's original text untouched. Point a hotkey at a two-line toggle script to flip rewrites from the keyboard across all running sessions at once. Override the path with CLAUDISH_OFF_FILE. /claudish (Controlling it live) is the friendly front-end for this, writing the same kind of flag files for mode, language, and model too.

Reasoning models

The ollama request sends "think": false, and openai-provider requests to api.openai.com send reasoning_effort: "none". Models with a hidden reasoning phase otherwise spend most of their time generating reasoning tokens you never see — much slower for identical output quality on this simple task. Keep it off.

Privacy / egress

With the default provider the rewriter runs entirely locally against ollama, so no conversation content leaves your machine. Setting CLAUDISH_PROVIDER to anthropic or openai changes that deliberately: every rewritten assistant message (and, with the Markdown hook enabled, file contents) is sent to that API. The same applies to pointing CLAUDISH_OLLAMA or CLAUDISH_OPENAI_URL at a remote/hosted endpoint. Don't switch away from local unless you understand and accept it.

Layout

claudish-to-english/
├── .claude-plugin/
│   ├── plugin.json         # plugin manifest
│   └── marketplace.json    # so the repo can be added as a marketplace directly
├── commands/
│   └── claudish.md         # /claudish slash command (runtime on/off, mode, language, model, last)
├── hooks/
│   └── hooks.json          # SessionStart -> session-notice.sh ; MessageDisplay -> rewrite.sh ; PostToolUse -> rewrite-md.sh
├── rewrite.sh              # display-rewrite hook
├── rewrite-md.sh           # markdown-file rewrite hook (opt-in)
├── claudish-ctl.sh         # runtime state switcher + dashboard backing /claudish (writes the flag files)
├── session-notice.sh       # SessionStart hook: announces leftover /claudish overrides on a new session
├── providers.sh            # provider layer (ollama/anthropic/openai), sourced by both hooks
├── lang.sh                 # output-language resolver (env + .claude/settings*.json), sourced by both hooks
├── CHANGELOG.md            # notable changes per version (Keep a Changelog)
├── LICENSE
└── README.md

License

MIT — see LICENSE.