Polyprompt

<div align="center">

<img src="./assets/banner.svg" width="100%" alt="Polyprompt — code with Claude, Codex or Gemini in your native language while learning a new one" />

<br/>

<p align="center"> <img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-22c55e?style=flat-square"> <img alt="Node >= 18.18" src="https://img.shields.io/badge/Node-%E2%89%A5%2018.18-339933?style=flat-square&logo=nodedotjs&logoColor=white"> <img alt="TypeScript 5.7" src="https://img.shields.io/badge/TypeScript-5.7-3178c6?style=flat-square&logo=typescript&logoColor=white"> <img alt="MCP server" src="https://img.shields.io/badge/MCP-server-a78bfa?style=flat-square"> <img alt="Tests: 175 passing" src="https://img.shields.io/badge/tests-175%20passing-22c55e?style=flat-square"> <img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-2dd4bf?style=flat-square"> </p> <p align="center"> <img alt="Works with Claude, Codex and Gemini" src="https://img.shields.io/badge/works%20with-Claude%20%C2%B7%20Codex%20%C2%B7%20Gemini-60a5fa?style=flat-square"> <img alt="Engine: MCP sampling" src="https://img.shields.io/badge/engine-MCP%20sampling%20(no%20extra%20key)-f59e0b?style=flat-square"> </p>

Code with Claude, Codex or Gemini in your own language — and learn a new one while you build.

</div>

---

Polyprompt is an MCP server. You write your coding prompts in your native language (say, Italian); Polyprompt translates them into the language you want to learn (say, English), the AI agent does the work in that language, and every useful new word is saved and resurfaced with spaced repetition.

You learn a language passively, in the flow of real work, using the AI subscription you already pay for — no extra API key required.

You:   "crea un endpoint REST per gli utenti"
         ↓  translate tool
Polyprompt: Italian → English
        "create a REST endpoint for users"
        endpoint — punto di accesso (noun) · users — utenti (noun)
         ↓
Agent builds the feature in English; the new words enter your review deck.

---

Two ways to learn

Polyprompt works in both directions — corrections one way, immersion the other — right inside your editor while you ship.

Mode	You write in…	Polyprompt gives you…
Immersion	your native language (Italian)	the target translation (English) + a glossary, so you learn by osmosis
Tutor	the target language (English)	your mistakes corrected, each explained in your native language, plus an improved version

Tutor mode — you try to write in English:

You:        "add validate to the form and create a users"
            ↓  correct tool
Polyprompt: "add validation to the form and create a user"
            "add validate" → "add validation" — 'validate' è un verbo; serve il sostantivo
               "create a users" → "create a user" — dopo "a" va il singolare
            ↓
Agent builds the feature; you just learned two fixes — in Italian.

The agent picks the direction automatically from the language you wrote in (or pin one with mode: immersion | tutor).

---

Why

Most developers learn technical English by osmosis — badly, slowly, and with gaps. Polyprompt turns the thousands of prompts you already write into deliberate, spaced language practice, without adding a separate study habit. Native in, target out, vocabulary remembered.

• Immersion, not friction — think in your language, ship in the one you're learning.
• Uses your subscription — translation runs on the host model via MCP sampling, so there's nothing extra to pay for or configure (API keys are optional fallbacks).
• Works everywhere MCP does — Claude Code, Codex CLI, Gemini CLI, and any other MCP client.
• Real spaced repetition — an SM-2 scheduler turns sightings into durable memory.

---

Quick start

One command installs Polyprompt, picks your languages, and connects it to every AI client it finds (Claude Code, Codex, Gemini) — all in one step:

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/DisSa12/polyprompt/main/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/DisSa12/polyprompt/main/install.ps1 | iex

Target a single client with --client claude (sh) or -Client claude (PowerShell).

Prefer to do it by hand? It's still two small steps:

npm install -g polyprompt     # 1. install (Node 18+); "npx -y polyprompt <cmd>" also works
polyprompt setup              # 2. pick languages + connect your AI client(s) automatically
# polyprompt init --native it --target en   # language setup only, no client wiring

Then just code. When you write in Italian, the agent calls translate, works in English, and shows you what you said in English plus the new words.

Tip: ask your agent once — "use Polyprompt immersion mode" — or load the immersion prompt the server exposes, so it consistently translates your prompts.

---

First run

The first time you run polyprompt init in a terminal, it walks you through a quick language picker — choose the language you think in and the one you want to learn (press Enter for the default, or type ? to list all 30+). Already know what you want, or scripting it? Pass --native/--target and the prompts are skipped entirely.

<div align="center"> <img src="./assets/setup.svg" width="82%" alt="polyprompt init — interactive first-run language picker asking for your native and target language" /> </div>

---

Levels that adapt to you

Polyprompt meets you where you are and grows with you. Each time you write in the language you're learning, tutor mode grades how clean it was; write well consistently and Polyprompt raises your CEFR level on its own. As your level climbs, it gradually shifts the language of its explanations from your native one toward the one you're learning:

Your level	Explanations are written in…
A1 – A2	your native language
B1	your native language, key terms kept in the target
B2	a roughly even mix of both
C1	mostly the target language
C2	entirely the target language

So a beginner is coached gently in their own language, while an advanced learner is fully immersed. Turn it off with POLYPROMPT_NO_AUTO_LEVEL=1, or pin a level any time with polyprompt config --level B1.

---

Staying up to date

Polyprompt keeps itself current. Everyday commands run a quiet, throttled check (at most once a day) and update in the background when a newer version is published — whether you installed it globally via npm or from a git clone. Force an update now with polyprompt update, or switch the automatic check off with POLYPROMPT_NO_UPDATE=1 (it never runs in CI, or while the MCP server is serving a client).

---

How it works

flowchart LR
  U["You"] -->|"write in Italian (native)"| H["Claude / Codex / Gemini"]
  U -->|"write in English (target)"| H
  H -->|"translate  ·  immersion"| T["Polyprompt MCP server"]
  H -->|"correct  ·  tutor"| T
  T -->|"sampling · your subscription"| H
  T -->|"English text / corrections + glossary"| H
  H -->|"builds the feature"| U
  T -. saves vocabulary .-> G[("glossary.json · SM-2 deck")]

1. The host AI calls the translate tool with your native-language prompt.
2. Polyprompt translates it — by default via MCP sampling, i.e. by asking the host AI itself to translate (your subscription, no extra key). If sampling isn't available and no API key is set — or a configured engine fails at call time — it returns instruct-mode guidance so the agent translates the prompt itself and logs it via record_translation. The learning loop never breaks.
3. New vocabulary is saved to ~/.polyprompt/glossary.json and scheduled for review.
4. The agent carries out your request using the translated text.

---

Tools

Tool	What it does
translate	Immersion — translate a native-language prompt; save new words.
correct	Tutor — correct target-language writing; explain each mistake in your native language.
record_translation	Log a translation the agent made itself (instruct-mode / manual).
explain	Explain a word or phrase in your native language, with examples.
review	List vocabulary due for spaced-repetition review.
record_review	Grade recall (0–5) and reschedule a card.
stats	Show progress: words collected, mastered, due, streak.
config	View or change language pair, level, mode, and engine.

It also exposes immersion and tutor prompts with behaviour instructions for the host AI.

---

CLI

The same engine is available from your terminal:

polyprompt translate "aggiungi validazione al form" --provider mock   # immersion
polyprompt correct "add validate to the form" --provider mock          # tutor
polyprompt explain "endpoint"
polyprompt review --limit 10
polyprompt grade "endpoint" 4                 # grade recall (0-5) and reschedule
polyprompt stats
polyprompt config --mode tutor --level B1     # switch mode / level
polyprompt languages                          # list supported languages
polyprompt setup --client claude              # connect Polyprompt to your AI client(s)
polyprompt update                             # update to the latest version right now
polyprompt uninstall --purge                  # disconnect from clients + delete your data

mock is a built-in offline engine — handy for trying Polyprompt without any model. It only translates between Italian and English; for other languages use sampling or an API-key engine.

---

Configuration

Stored at ~/.polyprompt/config.json (override the directory with POLYPROMPT_HOME):

Field	Meaning	Default
nativeLang	The language you think in (ISO 639-1)	it
targetLang	The language you're learning	en
level	Your CEFR level A1–C2 (tunes difficulty)	A2
mode	Default direction: immersion or tutor	immersion
provider	Translation engine (see below)	auto

Engines

provider	Source	Needs
auto (default)	Best available, in order: sampling → anthropic → openai → gemini (first ready wins; mock is never auto-selected)	—
sampling	The host AI via MCP sampling	An MCP client that supports sampling
anthropic	Anthropic API	ANTHROPIC_API_KEY
openai	OpenAI (or compatible) API	OPENAI_API_KEY (POLYPROMPT_OPENAI_BASE_URL optional)
gemini	Google Gemini API	GEMINI_API_KEY
mock	Offline dictionary (Italian and English only)	— (demo/testing)

Model overrides: POLYPROMPT_MODEL, or per-engine POLYPROMPT_ANTHROPIC_MODEL / POLYPROMPT_OPENAI_MODEL / POLYPROMPT_GEMINI_MODEL.

Behaviour switches: POLYPROMPT_NO_AUTO_LEVEL=1 disables the automatic level-ups; POLYPROMPT_NO_UPDATE=1 disables the background self-update.

---

Client setup

Run polyprompt install <client> for copy-paste config. In short:

Claude Code

claude mcp add polyprompt -- polyprompt mcp

Codex CLI — ~/.codex/config.toml

[mcp_servers.polyprompt]
command = "polyprompt"
args = ["mcp"]

Gemini CLI — ~/.gemini/settings.json

{ "mcpServers": { "polyprompt": { "command": "polyprompt", "args": ["mcp"] } } }

See examples/ for ready-made files, including a Claude Code skill that turns on immersion behaviour automatically.

---

Uninstalling

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/DisSa12/polyprompt/main/uninstall.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/DisSa12/polyprompt/main/uninstall.ps1 | iex

# or by hand:
polyprompt uninstall --purge   # disconnect from every client (+ delete local data)
npm uninstall -g polyprompt

uninstall removes Polyprompt from your MCP clients (Claude Code, Codex, Gemini); --purge also deletes your local config and glossary.

---

Development

npm install
npm run build       # compile to dist/
npm test            # vitest (unit + in-memory MCP integration + a real stdio handshake)
npm run typecheck   # tsc --noEmit
npm run dev -- translate "ciao" --provider mock   # run the CLI from source

The codebase is small and layered: pure SRS/store logic (src/glossary), engine-agnostic providers (src/providers), a runtime that ties them together (src/runtime.ts), and a thin MCP/CLI surface (src/server, src/cli.ts).

Built and hardened across two adversarial multi-agent review passes — every confirmed finding applied, with 175 tests green.

---

Roadmap

• A mistakes deck — spaced repetition for the corrections tutor mode finds, not just vocabulary.
• Richer review UX (cloze, listening) and export to Anki.
• Per-project glossaries.

License

MIT — see LICENSE.