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

Native Desktop App with Setup Wizard

• 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

MCP Server Improvements

• 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

CLI Changes

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

Installation

Option 1: Claude CLI (Recommended)

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

Option 2: Desktop App

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

Or build from source:

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

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

License

MIT