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](https://modelcontextprotocol.io) 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**. ```text 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 | ```text 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: ```bash # 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: ```bash 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 ```mermaid 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: ```bash 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** ```bash claude mcp add polyprompt -- polyprompt mcp ``` **Codex CLI** — `~/.codex/config.toml` ```toml [mcp_servers.polyprompt] command = "polyprompt" args = ["mcp"] ``` **Gemini CLI** — `~/.gemini/settings.json` ```json { "mcpServers": { "polyprompt": { "command": "polyprompt", "args": ["mcp"] } } } ``` See [`examples/`](./examples) for ready-made files, including a Claude Code skill that turns on immersion behaviour automatically. --- ## Uninstalling ```bash # 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 ```bash 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](./LICENSE).