# claudish-to-english

> A Claude Code plugin that rewrites each assistant message into plain English using a local LLM via ollama, the Anthropic API, or any OpenAI-compatible API.

claudish-to-english is an open-source Claude Code plugin created by Mike Gvozdev (gvzdv on GitHub) that intercepts assistant messages and displays a plain-English rewrite alongside or in place of the original. It is display-only by design — Claude's own reasoning and the saved transcript keep the original text unchanged. The project is licensed under MIT and described by its author as a "working prototype" with 1,192 stars on GitHub as of mid-August 2026.

## What It Is

claudish-to-english is a Claude Code plugin that hooks into the `MessageDisplay` event to rewrite verbose, jargon-heavy assistant output ("Claudish") into plain English. It uses a configurable LLM backend — defaulting to a local ollama model so nothing leaves your machine — and supports the Anthropic API and any OpenAI-compatible endpoint as alternatives. An optional second hook (`rewrite-md.sh`) can also rewrite Markdown files on disk when they are written or edited, though this is opt-in and off by default.

## How the Hooks Work

The plugin registers two hooks in `hooks/hooks.json`:

- **Display hook (`rewrite.sh`):** Fires on every `MessageDisplay` event. Because Claude Code fires this once per streamed chunk, the hook buffers each delta to a temp file and only calls the LLM on the final chunk, once the full message is assembled. It also reads the original user question from the transcript and passes it as context so the rewrite stays on-topic.
- **Markdown hook (`rewrite-md.sh`):** A `PostToolUse` hook that rewrites `*.md` files in a user-specified directory. It supports a non-destructive `sibling` mode (writes `NAME.plain.md` next to the original) and an `overwrite` mode that replaces the file in place with an idempotency marker.

Both hooks are fail-open: if the provider is down, times out, or a key is missing, the original text is shown unchanged.

## Display Modes and Configuration

The plugin is controlled entirely through `CLAUDISH_*` environment variables set in Claude Code's `settings.json` `env` block:

- **`CLAUDISH_MODE`**: `append` (default, safest — appends a `💬 In plain English:` block after the original) or `replace` (experimental — suppresses streaming and shows only the rewrite).
- **`CLAUDISH_PROVIDER`**: `ollama` (default, local), `anthropic`, or `openai`.
- **`CLAUDISH_MODEL`**: Overrides the provider's default model. The default `gemma4:26b-mlx` is Apple-silicon (MLX) only; Windows users must set a non-MLX tag.
- **`CLAUDISH_MD_DIR`**: Opt-in directory for the Markdown hook; unset means the hook does nothing.
- A runtime kill switch (`touch ~/.claude/claudish-off`) pauses rewrites mid-session without restarting Claude Code.

Custom rewrite prompts can be supplied via `CLAUDISH_PROMPT_FILE` and `CLAUDISH_MD_PROMPT_FILE`, replacing the built-in system prompt entirely.

## Provider Architecture and Privacy

With the default `ollama` provider, all rewriting happens locally and no conversation content leaves the machine. Switching to `anthropic` or `openai` deliberately sends each assistant message (and, with the Markdown hook, file contents) to an external API. The README includes an explicit caution that ambient `OPENAI_API_KEY` or `ANTHROPIC_API_KEY` environment variables are picked up automatically, so setting `CLAUDISH_PROVIDER=openai` is the consent switch. Dedicated per-plugin keys (`CLAUDISH_ANTHROPIC_KEY`, `CLAUDISH_OPENAI_KEY`) are supported to isolate usage from other tools.

## Platform Support and Setup

The hooks are bash scripts. On macOS, requirements are ollama, a pulled model, `jq`, and `curl`. On Windows, Claude Code runs the hooks through Git Bash, and users must override the default model to a non-MLX tag. The plugin can be installed directly from the repository via `/plugin marketplace add gvzdv/claudish-to-english` and `/plugin install claudish-to-english@gvzdv-plugins`, or loaded for a single session with `claude --plugin-dir`.

## Current Status

The repository was created on August 10, 2026 and last pushed on August 13, 2026, with 1,192 stars and 78 forks. The author describes it as a "working prototype." A `CHANGELOG.md` is included in the repository layout. The latest GitHub release is tagged `assets` (README assets, published August 11, 2026), indicating the project is in early active development.

## Features
- Plain-English rewrite of Claude assistant messages via MessageDisplay hook
- Local LLM rewriting via ollama (default, no data leaves machine)
- Anthropic API and OpenAI-compatible API provider support
- Append mode (shows rewrite after original) and replace mode (shows only rewrite)
- Optional Markdown file rewrite hook (PostToolUse, opt-in by directory)
- Sibling mode writes NAME.plain.md non-destructively; overwrite mode replaces in place
- Fail-open design: provider failures always show original text unchanged
- Configurable via CLAUDISH_* environment variables in settings.json
- Custom rewrite prompt via CLAUDISH_PROMPT_FILE
- Mid-session kill switch via flag file (~/.claude/claudish-off)
- Per-message buffering to handle streamed chunks correctly
- Reasoning model optimization (think:false for ollama, reasoning_effort:none for OpenAI)
- Debug logging via CLAUDISH_DEBUG=1
- macOS and Windows (Git Bash) support

## Integrations
Claude Code, ollama, Anthropic API, OpenAI API, LM Studio, llama.cpp server, vLLM, OpenRouter, Git Bash (Windows)

## Platforms
WINDOWS, MACOS, API, CLI

## Pricing
Open Source

## Version
assets

## Links
- Website: https://github.com/gvzdv/claudish-to-english
- Repository: https://github.com/gvzdv/claudish-to-english
- EveryDev.ai: https://www.everydev.ai/tools/claudish-to-english