english-exam-coach

English Exam Coach turns Claude Code
into your personal English exam tutor. It generates original practice tasks
in the exact format of your exam, grades your answers with feedback that
actually tells you what to fix, and keeps a practice log on your own disk —
so every session shows you your trend, your weakest task type, and the one
thing to drill next.

[!IMPORTANT]
Indicative, not official. All scores and level estimates are
self-practice feedback — they are not official results and do not predict
them. This project is not affiliated with, endorsed by, or connected to
IELTS, ETS/TOEFL, Cambridge English, or any exam board; exam names are
used nominatively to describe compatibility.

🧡 What you can do

• 📝 Writing — paste your essay, email, or report; get a band range, a
  CEFR level, and rewrites built from your own sentences
• 🗣️ Speaking — exam-format prompts with real timings; feedback on a
  transcript or recording description
• 📖 Reading & Use of English — cloze, key word transformations,
  matching, True/False/Not Given… scored objectively, every answer explained
• 🎧 Listening — generated scripts with exam-style questions (spoken
  aloud on macOS, read-along elsewhere)
• 🧠 Vocabulary — leveled word sets with spaced repetition that
  remembers what you keep forgetting
• 🗓️ Study plan — tell it your exam date; get a week-by-week plan it
  checks you against
• 📈 Progress — every attempt logged locally; reports show trends and
  pick your next drill

🚀 Get started in 2 minutes

You need Claude Code and Python 3
(preinstalled on macOS and most Linux; Windows: python.org).

1. Open a terminal and start Claude Code:

claude

(New to Claude Code? Install it first,
then run claude from any folder.)

2. Inside Claude Code, add the marketplace and install the plugin:

/plugin marketplace add OleksiiDotsenko/english-exam-coach
/plugin install english-exam-coach@english-exam-coach

Using the desktop or web app — or seeing "/plugin isn't available
in this environment"? Skip step 1 and run both commands from a plain
terminal instead, prefixed with claude:

claude plugin marketplace add OleksiiDotsenko/english-exam-coach
claude plugin install english-exam-coach@english-exam-coach

3. Restart Claude Code (type /exit, then claude again — or just
open a new session in the app) and type:

/start-prep

That's it — it asks which exam you're preparing for, finds your level, and
starts your first task. Prefer talking? Just say "help me prepare for
TOEFL" or "here's my IELTS essay: …" — the right skill fires on its own.

🕹️ Example session

You:    /start-prep
Claude: Which exam are you preparing for? (IELTS Academic / IELTS General /
        TOEFL iBT / CEFR B1–C2)
You:    TOEFL, writing
Claude: TOEFL iBT Writing has three task types: Build a Sentence,
        Write an Email (7 min), Academic Discussion (10 min).
        Practice a new task, or get feedback on something you wrote?
You:    new email task
Claude: [original Write-an-Email task: scenario + 3 required content
        points, 7-minute timer starts when you say go]
You:    [your email]
Claude: Band estimate: 4.5–5.0 / 6 (≈ B2, borderline C1).
        All 3 content points covered; register consistent.
        Priority fixes: (1) …, (2) …, (3) … — each shown as a rewrite
        of your own sentences. Attempt logged.
You:    /session-report
Claude: [table of today's attempts, time on task, weakest task type,
        one recommended next drill]

📚 Supported exams

Format facts (task types, item counts, timings, word counts, scales) live in
data/exam-formats/ and were
verified against official sources in July 2026 — including the redesigned
TOEFL iBT (adaptive sections, 1–6 band scale). Formats change occasionally;
confirm details with the exam provider before test day.

📈 Your progress, on your disk

Two layers, both plain files in your own workspace (never inside the plugin):

• attempts.jsonl — append-only log, one line per scored attempt.
  Source of truth. The tooling only ever appends; "clearing progress"
  is a deliberate manual action (delete the file yourself), never a side
  effect.
• reports/*.md — session reports and an all-time overview, regenerable
  at any time.

Cross-exam trends are normalized to CEFR — an IELTS band and a TOEFL score
are never merged into one number.

Where the files live (first match wins): the --base flag →
EXAM_COACH_HOME env var → ~/english-exam-coach/ (created on first use).

[!TIP]
Obsidian user? Point EXAM_COACH_HOME at a folder inside your vault
and the reports' YAML frontmatter (type, date, session, tasks,
minutes, exams) makes Dataview tables and trend views work with no
extra code.

❓ FAQ

No separate account, API key, or subscription — it runs inside your
existing Claude Code session.

Nowhere. The plugin makes zero network calls and sends no telemetry. Your
practice log is a local file in a folder you choose.

No — and be suspicious of anything that claims to. Estimates are honest
ranges tied to public CEFR descriptors: good enough to steer your practice,
not an official measurement.

Start a new Claude Code session (or restart the app) — plugins load at
session start.

The /plugin dialog only exists in the terminal version of
Claude Code. In the desktop or web app, run the equivalent commands from
any terminal: claude plugin marketplace add
OleksiiDotsenko/english-exam-coach, then claude plugin
install english-exam-coach@english-exam-coach. The plugin then
works in every Claude Code surface on that machine.

On macOS it speaks scripts aloud via the built-in say command.
Elsewhere, listening drills degrade gracefully to read-once scripts —
or bring your own audio/podcast and it builds questions for that.

Update: /plugin marketplace update english-exam-coach, then
/plugin update english-exam-coach@english-exam-coach (the full
name@marketplace form is required here). Uninstall:
/plugin uninstall english-exam-coach. Your progress files are
yours and are never touched by either.

🔒 Security & privacy

• No network access. No network calls, no telemetry; everything runs
  locally in your Claude session.
• No MCP servers, no hooks, no background processes — only Markdown
  skills/commands and two Python scripts invoked explicitly.
• Writes only to your progress directory — nothing else on disk is
  touched, and the attempt log is opened in append mode only.
• Standard library only. The scripts import nothing outside Python's
  stdlib, so there is no supply-chain surface.

🧩 What's inside

• 8 skills, organized by macro-skill, not by exam (exam differences are
  reference data, not code): exam-router, writing-evaluator,
  speaking-coach, reading-use-of-english, listening-trainer,
  vocabulary-builder, study-planner, progress-tracker.
• 6 commands: /start-prep, /mock-exam, /daily-drill,
  /assess-level, /session-report, /progress.
• Data: exam format facts, paraphrased public CEFR descriptors, and a
  small bank of original seed items used as format references.
• Scripts: log_attempt.py and build_report.py — Python 3 standard
  library only.

⚖️ Content and IP policy

• No official exam content. No past papers, official item banks, or
  official mark schemes anywhere in this repository. All practice items are
  original, generated to match public format facts (task types, counts,
  timings, scales — facts are not copyrightable).
• Public descriptors only. Evaluation anchors are paraphrased from the
  public CEFR framework (Council of Europe); criterion names are used
  nominatively.
• Brand-neutral naming. Files and identifiers are named by CEFR level
  where possible; trademarks appear only nominatively, with no claim of
  affiliation or endorsement.

If you believe any content in this repository crosses these lines, please
open an issue — it will be treated as a bug.

🛠️ Development

python3 -m unittest discover -s tests      # from the repo root
claude plugin validate . --strict
python3 tools/make_banner.py               # regenerate assets/banner.svg

Design notes: skills are procedures, exam differences are reference data
loaded on demand; the progress log is append-only and reports are derived.
See CHANGELOG.md for release history.

License

MIT © 2026 Oleksii Dotsenko