Mathiz

AI powered math playground in the terminal. Mathiz helps kids (grades 2-5) build math mastery through adaptive practice, spaced repetition, and LLM generated questions. Mathiz is backed by a static skill graph, rule based adaptive learning and positive reinforcement to make it explainable, constrained, and fun.

Built with Claude Code using a spec driven development approach. See specs and author notes for details.

curl -fsSL https://raw.githubusercontent.com/abhisek/mathiz/main/install.sh | sh

Or download a binary manually from GitHub Releases.

Mathiz requires an LLM API key. It automatically discovers keys from standard environment variables (checked in this order):

If you already have one of these set, Mathiz will just work. To override the auto-detected provider or use a custom model:

export MATHIZ_LLM_PROVIDER=gemini              # force a specific provider
export MATHIZ_GEMINI_MODEL=gemini-2.0-pro      # override default model
export MATHIZ_OPENROUTER_MODEL=anthropic/claude-3-haiku  # override OpenRouter model

mathiz          # launch the TUI (welcome → home → session)
mathiz play     # jump straight into a practice session
mathiz stats    # view learning stats
mathiz llm      # inspect LLM usage
mathiz update   # update to the latest version
mathiz reset    # reset all progress

Mathiz can also run as a multi-tenant server: parents sign up (Supabase), create a Family Space, add children, and share a join code. Children open the web app, enter the code, pick their profile, and play the treasure map: the skill graph rendered as islands, where solving AI-generated math digs up treasure, collects gems, and lifts the fog on new territory — no email, no install.

make dev-up          # self-contained: Postgres + stub LLM + server on :8080

Or host-native:

make dev-db          # local PostgreSQL (docker compose)
cp .env.example .env # configure database + Supabase + LLM key
make web && make mathiz
./bin/mathiz serve

See the SaaS guide and spec.

All progress is stored in a single SQLite file. Use the --db flag to maintain separate profiles for different learners:

mathiz --db ~/mathiz-alice.db       # Alice's profile
mathiz --db ~/mathiz-bob.db         # Bob's profile
mathiz stats --db ~/mathiz-alice.db # Alice's stats

You can also set the MATHIZ_DB environment variable instead. The --db flag takes priority over the env var.

The current skill graph is based on Common Core standard. But the system is designed to support multiple standards and curriculum.

• Personas & Supported Flows — who Mathiz serves and everything each persona can do
• Development Guide — zero to running locally (CLI, hosted mode, web, tests)
• SaaS / Hosted Mode — architecture and deployment of mathiz serve
• Skill Preview — browse skills and test LLM-generated questions without a database
• LLM Usage Auditing — inspect LLM requests, responses, and token usage

Requires Go 1.25+ (and Node 20+ for the hosted-mode web app).

git clone https://github.com/abhisek/mathiz.git
cd mathiz
make

See the Development Guide for the full local setup, including hosted mode without any external services.

• Windows self-update using mathiz update fails due to platform restrictions.

MIT