<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).