A kind, locally-run AI companion for children aged 6–17 — runs on your computer, with parents in control.
Aria is a desktop AI conversational app designed for children. It speaks, listens, shows planets, continents, and a chalkboard for math. The local mode runs entirely on your computer (no data leaves your machine). The cloud mode is opt-in and uses your own Anthropic API key.
This is a hand-built solo project, released as a gift to the community. Use it, fork it, learn from it. No support guaranteed — see Contributing.
There is no shortage of AI chatbots. Aria is different on four axes:
- Designed for children, not adults retro-fitted. Tone, scope, refusal patterns, and the avatar are tuned for ages 6–17. A safety layer filters inappropriate output before it reaches the TTS.
- Local-first. Local mode (Ollama + Qwen 2.5 7B) requires no API key and sends nothing to the cloud. Cloud mode (Anthropic Claude) is opt-in and uses your own key — Aria never holds it for you.
- Parents see everything. Every fact Aria remembers about a child is visible and deletable. The "Settings" drawer is gated behind a parent password.
- No tracking, no telemetry, no account. No analytics, no remote sync. The app runs on
127.0.0.1.
It is not perfect, and the local model has real limits (see Limitations).
Requirements: Windows or Linux, Python 3.11+, ~3 GB free disk (for Piper voices + Whisper STT model + Ollama).
# 1. Clone
git clone https://github.com/quang101182/aria-ai.git
cd aria-ai
# 2. Python deps (creates a local venv)
python -m venv .venv
.venv\Scripts\activate # Windows
# source .venv/bin/activate # Linux/Mac
pip install -r requirements.txt
# 3. Piper TTS voices (downloads FR/EN/ES/PT/DE/IT into vendor/piper-voices/)
python scripts/_download_piper_voices.py
# 4. Local LLM (one-time, optional but recommended)
# Install Ollama from https://ollama.com, then:
ollama pull qwen2.5:7b-instruct-q4_K_M
# 5. Run
python scripts/serve.pyOpen your browser at http://127.0.0.1:9100/src/index.html.
The first launch shows a short onboarding (language, child profile, optional parent password).
- 🌍 Cosmos & geography scenes — Aria can show planets, continents, and zoom in when asked
- 📐 Chalkboard for math — Aria writes simple exercises and corrects step by step
- 🗣 Voice in / voice out — Whisper STT + Piper TTS, both local
- 👤 3D avatar with emotions — based on TalkingHead.js (MIT)
- 🌐 6 languages — French, English, Spanish, Portuguese, German, Italian
- 🧠 Memory layer — Aria remembers per-profile facts ("I have a cat named Felix"). All visible & deletable by the parent.
- 🛡 Safety layer — system prompt + output regex banlist + age-aware token caps + meta-router for "how do I use the app?" questions
- 🔒 Parent lock — drawer + settings + memory editing all gated behind a parent password
- 📊 Cloud budget tracker — opt-in daily/weekly/monthly USD limit when using Anthropic mode
- ♿ Accessibility hooks — TSA mode (mute emotions, no 2D bubbles, sensory-load reduction)
- Open the Settings drawer (gear icon top-right, ask for parent password if set)
- Paste your Anthropic API key (
sk-ant-...) into the Cloud API key field - Pick a budget cap (default: $5 / day) — Aria refuses to call the API past this
- The pastille top-left turns ✨ Magic mode when cloud is active
Your key is stored in localStorage on this machine only. It is never sent anywhere except api.anthropic.com. If you want it encrypted, see Advanced security.
If ollama is running on localhost:11434 and qwen2.5:7b-instruct-q4_K_M is pulled, Aria uses it automatically when no cloud key is set, or when cloud fails. You can switch models via env var:
OLLAMA_MODEL=llama3.2:8b python scripts/serve.pyVoices live in vendor/piper-voices/. Override with PIPER_MODELS_DIR=.... If Piper is not on your PATH, override the executable with PIPER_EXE=....
PIPER_EXE=/usr/local/bin/piper python scripts/serve.pyDefault 9100. Override with PROJETEDUC_PORT=8080 python scripts/serve.py.
Honest disclosure — Aria is not magic:
- Local Qwen 7B Q4 is limited. It hallucinates, sometimes refuses to use tools, can answer in English when asked in French. Cloud Claude is markedly better but costs a few cents per session.
- No real moderation model. The safety layer is regex + system prompt + age cap. It is not a classifier. If a child asks the right wrong question, Aria will refuse politely, but no system is perfect.
- Not a tutor. Aria does not teach a curriculum. It answers questions, shows scenes, helps with simple math. For structured learning, look at Khan Academy Kids or Khanmigo.
- Windows-first. It runs on Linux but the avatar + Edge
--apppolish is Windows-tuned for now. - No multi-user. One installation = one family. No accounts, no cloud sync.
┌─ src/ Frontend (vanilla JS, no framework)
│ ├─ index.html App shell + entry point
│ ├─ lib/ Modules (cloud_keys, scene_manager, parent_lock, ...)
│ ├─ scenes/ cosmos.html, world.html, chalkboard.js
│ ├─ i18n/ 6 language bundles (~205 keys each)
│ └─ sw.js Service worker (cache-bust on version change)
│
├─ scripts/
│ ├─ serve.py HTTP server on :9100 (static + /api/* endpoints)
│ ├─ safety.py System prompt + output filter + tool call extractor
│ ├─ meta_router.py Short-circuits "how do I use the app?" questions
│ ├─ memory_facts.py Per-profile remembered facts
│ ├─ age_bands.py Age-aware adaptation (vocabulary, response length)
│ ├─ session_log.py Per-session NDJSON history
│ ├─ cloud_stats.py Cloud usage counters
│ ├─ cloud_budget.py Budget caps (daily/weekly/monthly USD)
│ └─ llm/ Provider abstraction (Ollama, Anthropic, OpenAI, Mistral)
│
├─ assets/ VRM avatars, audio cues
└─ vendor/ Vendored 3rd-party (TalkingHead.js)
The server is intentionally simple Python http.server + SSE. No FastAPI, no framework. Boot in ~3 seconds.
- The Anthropic API key is stored in
localStoragein cleartext. This is a deliberate trade-off for local-first ergonomics. If you want it encrypted at rest, fork and re-enable the AES-GCM/PBKDF2 path that was removed in v0.8.8 (seesrc/lib/cloud_keys.jshistory). - The parent password is hashed (PBKDF2) and gates only the UI drawer. It does not encrypt anything.
- Memory facts are stored in plain NDJSON under
data/memory/. Wipedata/to fully reset. - The app binds to
127.0.0.1only. It is not designed to be exposed to a LAN or the public internet.
I welcome contributions but do not promise rapid merges or replies.
- Bug reports: open a GitHub issue with reproduction steps. I read them, I do not always answer.
- Pull requests: small focused PRs accepted. Large refactors: open an issue first.
- Forks: encouraged. The codebase is yours to bend.
- No support 1:1. Please use Discussions — the community helps community. Email goes to
/dev/null.
By submitting a PR you agree the contribution is licensed under AGPL-3.0.
AGPL-3.0. See LICENSE.
In plain English: you can use, modify, distribute Aria freely, including commercially. But if you run a modified version as a network-accessible service, you must publish your source code modifications under AGPL-3.0 too.
Aria stands on the shoulders of:
- Piper — neural TTS, MIT
- faster-whisper — speech-to-text, MIT
- Ollama — local LLM runtime, MIT
- TalkingHead.js — 3D avatar, MIT
- Three.js — 3D rendering, MIT
- Qwen 2.5 — local LLM weights, Apache 2.0
- Anthropic Claude — cloud LLM (opt-in, BYOK)
Inspired by the work of children's media that respects children — Mister Rogers, Studio Ghibli, the BBC's Teletubbies dignity — and by every parent who has ever asked "is this AI safe for my kid?"
Made by Bruce Li. Find me on TikTok @se7en.ai for behind-the-scenes of solo dev life.
If Aria is useful to you, a star ⭐ on the repo costs nothing and helps others find it. If you want to support the project financially, GitHub Sponsors is open — every coffee buys another evening of code.