Avaia

Proactive AI Programming Teacher

Avaia is an MCP server that transforms Claude into a pedagogically-informed programming tutor. It uses spaced repetition (FSRS-5), designed productive failure, and adaptive scaffolding to create lasting learning.

Features

- 53 Pedagogical Tools — Complete MCP server with session, content, verification, SRS, sandbox, and track management
- 7 Learning Tracks — JavaScript Web, Python Data, C Systems, DSA, CS Theory, ML Engineering, and more
- Invisible Spaced Repetition — FSRS-5 algorithm fights the forgetting curve without flashcard fatigue
- Designed Productive Failure — Sandbox problems force failure before instruction
- Dynamic Content Generation — AI-generated questions, hints, and exercises based on learner's actual code
- Diagnostic Assessment — Code prediction tasks that reveal specific misconceptions
- Confidence Tracking — Leverage the hypercorrection effect for stubborn bugs
- Adaptive Scaffolding — Progressive hint reduction as competence grows
- Emotional State Inference — Detect frustration and disengagement from timing patterns
- Complete Chat History — Auto-logged conversations for debugging and session continuity
- Semantic Trigger Phrases — Natural language cues automatically invoke appropriate tools

What's New in v1.3.0

$3

- One-click installer — Native app bundle with embedded WebKit (PyWebView)
- Setup Wizard — Guided onboarding that handles:
- Claude CLI installation
- Authentication (BYOK API key or Claude login)
- MCP server configuration
- Database initialization
- Dashboard pages — Track progress, reviews, projects, and learning stats
- Fresh environment support — Works correctly even when ~/.local/bin isn't in PATH

$3

- 53 tools — Up from 42, with new Track management tools
- Correct bin entry — npx @newdara/avaia now runs the MCP server
- Learning Tracks — New registerTrackTools() for curriculum progression
- Auto-migrations — Database schema updates automatically on server start
- Performance optimizations — Cached preflight checks, SQLite WAL mode

$3

- npx @newdara/avaia — Run MCP server (for claude mcp add)
- npx @newdara/avaia-teach — CLI wrapper with timing injection (optional enhanced experience)

Installation

$3

``bash


1. Install Claude CLI

curl -fsSL https://claude.ai/install.sh | bash

2. Add Avaia MCP to Claude

claude mcp add avaia -- npx @newdara/avaia

3. Authenticate (choose one)

claude login # Use Claude account

OR

export ANTHROPIC_API_KEY="sk-..." # Use API key

4. Start learning

claude
`

The database is created automatically on first run.

$3

Download Avaia.app from the releases page and drag to Applications. The setup wizard will guide you through configuration.

Or build from source:

`bash
cd gui
pip install -r requirements.txt
python server_webview.py # Run in dev mode


OR


./build_webview.sh # Build native app → dist/Avaia.app
`

Usage

Once configured, Claude Code will have access to 53 pedagogical tools including:

- start_session / end_session — Session lifecycle management
- get_next_step — Weakness-aware next action
- trigger_sandbox — Designed failure exercises
- get_diagnostic_question — Code prediction tasks
- infer_emotional_state — Timing-based emotional detection
- get_hint — Independence-based scaffolding
- log_review — FSRS spaced repetition
- select_track — Change learning track

GUI Features

The desktop app includes:

- Setup Wizard — Guided onboarding for new users
- Dashboard — Stats overview with time, concepts, streak tracking
- My Learning — Mastered vs learning concepts, vocabulary
- Projects — Track progress through milestones
- Reviews — Interactive SRS cards with code snippets
- Chat Interface — Real-time streaming with syntax highlighting

Learning Tracks

Avaia includes 7 pre-seeded learning tracks:

| Track | Language | Focus |
|-------|----------|-------|
| JavaScript Web Development | JavaScript | DOM, events, async, full-stack |
| Python Data Science | Python | pandas, numpy, visualization |
| C Systems Programming | C | Memory, pointers, systems |
| Data Structures & Algorithms | Language-agnostic | Core CS fundamentals |
| CS Theory | Theory | Complexity, automata, proofs |
| ML Engineering | Python | PyTorch, training, deployment |
| Avaia Core | JavaScript | The default beginner track |

How It Works

1. You build real projects (Memory Game → Task Tracker → Weather Dashboard → ...)
2. Concepts are taught just-in-time when your project needs them
3. You fail productively through sandbox exercises before complex topics
4. Your understanding is verified through code prediction, not self-assessment
5. Knowledge is retained through invisible spaced repetition

Philosophy

Traditional tutorials teach concepts first, then apply them. Avaia inverts this:

> The project IS the curriculum. Concepts are discovered through necessity.

Based on research in:
- Situated Cognition (Lave & Wenger)
- Productive Failure (Manu Kapur)
- Desirable Difficulties (Bjork)
- Spaced Repetition (FSRS-5)

Development

`bash
git clone https://github.com/NewDara-Star/avaia
cd avaia
npm install
npm run build
npm run db:seed
``

License

MIT