npm package: @newdara/avaia
Description: Proactive AI Programming Teacher - MCP server for Claude Code
Latest version: 1.3.0

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

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

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

```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