🏃 SPEEDRUN — CAT Mental Math Trainer

A terminal-based mental math trainer built for CAT prep. Text-only, fast, and designed to be finished in 15-20 minutes so it doesn't eat into your syllabus/mock time — it's a daily habit, not a study block.

Free, open source, zero dependencies (pure Python standard library).

---

Install

Requires Python 3.8+. Pick whichever feels easiest:

Option 1 — one-line install (recommended, no git needed)

Mac/Linux:

curl -fsSL https://raw.githubusercontent.com/YOUR_USERNAME/speedrun/main/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/YOUR_USERNAME/speedrun/main/install.ps1 | iex

This sets up pipx (an isolated, standard way to install Python CLI tools) and installs SPEEDRUN through it. Open a new terminal afterwards and just run:

speedrun

That's it — the speedrun command now works from anywhere, no cd, no python prefix needed.

Option 2 — pip/pipx directly

If you already have pipx or pip:

pipx install speedrun-cat     # recommended
# or
pip install --user speedrun-cat

Then run speedrun from anywhere.

Option 3 — clone the repo, no install at all

git clone https://github.com/YOUR_USERNAME/speedrun.git
cd speedrun
python3 speedrun.py

or double-click run.sh (Mac/Linux) / run.bat (Windows) inside the folder.

Uninstalling

pipx uninstall speedrun-cat
# or, if you used plain pip:
pip uninstall speedrun-cat

---

First launch

It asks one question: where to save your daily reports. Point it at your Obsidian vault (or any folder) — that's the entire setup.

---

How a session works

1. Pick categories — auto-continue the weekly rotation, choose your own, or skip and let the app decide (default: 5/day, cycling through all 19 over about a week so nothing goes stale).

2. Pick a difficulty:

   • Tutorial — warm up the basics (~0-35% CAT difficulty)
   • Main Quest — real CAT-pace calculations (~35-70%)
   • Boss Fight — full CAT-level speed & shortcuts (~70-100%)

   Difficulty ramps up as you move through each category's questions — you're never stuck grinding the same difficulty for 15 minutes, and never thrown into the deep end on question one.

3. Work through each category, then a final Mixed Practice round pulling randomly from everything you just covered.

While answering: type a number + Enter. Blank + Enter skips a question. q + Enter ends the session early — whatever you completed still gets saved and logged.

Session length is adjustable in Settings:

• Quick (~10 min): 4 categories × 4 Qs + 6 mixed
• Standard (~15-20 min, default): 5 categories × 6 Qs + 10 mixed
• Deep (~25-30 min): 6 categories × 8 Qs + 14 mixed

---

The 19 categories

Addition, Subtraction, Multiplication, Division, Tables, Fractions, Percentages, Ratios, Averages, Squares, Cubes, Square Roots, Cube Roots, Decimals, BODMAS, Mixed Arithmetic, Approximation, Number Properties, and CAT-Style Calculation (a grab-bag of classic CAT shortcuts — ×99/999, a²−b² tricks, compound %, etc).

Questions lean on real CAT-style shapes (35% of 840 + 48, 999 × 27, 48² − 47²) rather than flat arithmetic — see src/speedrun_cat/categories.py.

---

The fun layer

• XP — every correct answer earns XP (harder/faster = more). Shown live in the main menu next to your rank.
• Ranks — Rookie Recruit → Numbers Cadet → Sharp Shooter → Speedrunner → Calc Assassin → Mental Math Elite → CAT Crusher → 99.99%iler, based on lifetime XP.
• Combos — 🔥 shows up once you chain 3+ correct answers in a row.
• Streaks — consecutive practice days, tracked on the dashboard.

None of this affects question difficulty or scoring fairness — it's motivation on top, not a mechanic you need to think about.

---

Markdown reports (Obsidian-ready)

One file per day: 2026-07-27 - Speedrun.md, saved into the folder you chose at setup. Multiple sessions the same day append to the same file instead of creating new ones.

Deliberately short — a score line, a category breakdown, and a short "missed" list for spaced review. No walls of stats you'll never reread.

## Session 1 — 09:14 · Main Quest

**19/24** (79%) · ⏱ 1m 54s · ⚡ 366 XP · 🔥 best combo x4

Categories: Percentages, Squares, BODMAS, Division

By category: Percentages 67% (6) · Squares 83% (6) · BODMAS 83% (6) · Division 83% (6)

**Missed (worth another look):**
- 40% of 224 → you said **1089.6**, correct **89.6**
- 84² → you said **8056**, correct **7056**

**Slowest correct answer:** 76² (5.5s)

Analytics dashboard (in-app)

Accessible from the main menu — no need to open any files: total sessions/questions, overall accuracy, average response time, current/longest streak, strongest & weakest category, most/least practiced category, and last-7/30-day summaries.

---

Where your data lives

• ~/.speedrun/config.json — remembers which folder you chose.
• <your folder>/.speedrun-data/analytics.json — all your stats, streaks, and rotation state. Hidden so your Obsidian vault only shows clean .md files.
• <your folder>/*.md — your daily reports.

Delete ~/.speedrun/config.json any time to re-run first-time setup (your reports/analytics are untouched).

---

Contributing / extending it

Everything is modular by design — see src/speedrun_cat/:

File	Responsibility
main.py	Menus, dashboard, settings, orchestration
session.py	Runs one practice session
categories.py	All 19 question generators — add a new category here
gamification.py	Difficulty tiers, XP formula, rank ladder
stats.py	Long-term analytics
markdown_report.py	Daily .md report generation
storage.py / config.py	Persistence
ui.py	Terminal colors/menus/formatting

To add a category: write one gen_<name>(t) function in categories.py returning a Question, then add it to CATEGORY_GENERATORS. It's automatically included in rotation, manual picking, and stats — nothing else needs to change.

PRs welcome. This project is MIT-licensed — free to use, modify, and redistribute.

For maintainers: releasing a new version

1. Bump the version in pyproject.toml and src/speedrun_cat/__init__.py.
2. Push a Git tag / create a GitHub Release.
3. .github/workflows/publish.yml builds and publishes to PyPI automatically via PyPI Trusted Publishing (configure once in your PyPI project settings → no API tokens to manage).