EchoWise

Just talk.

An open-source, cross-platform desktop AI companion for English speaking & listening practice. Have natural conversations with an AI that grows with you — no lessons, no drills, no tests.

English ｜ 简体中文

---

Philosophy

Stop studying English. Start using English.

Most English-learning apps teach you English. EchoWise helps you use it.

We don't drill vocabulary, hand out exercises, or assign grades. We let you build real communication ability by having ordinary daily conversations with an AI companion who becomes increasingly familiar over time.

• Communication before perfection — Imperfect English that connects beats perfect grammar that stays silent
• Relationship before knowledge — A polite stranger on Day 1, an easy old friend by Day 180
• Gentle nudges, never interruptions — No lectures mid-sentence; one-glance hints when something's worth a tweak
• Local-first — All data lives on your machine, nothing leaves it

---

Features

🗣️ A companion that grows	One companion you name, style (avatar / voice / persona) and shape. Day-count + a 5-tier relationship arc (stranger → old friend) that the AI's tone naturally follows.
🎙️ Voice-first conversation	Speak via mic or type — both work. Voice-message-style bubbles: tap the waveform to play; transcript is one click away.
💡 Non-intrusive coaching	The AI never lectures mid-reply. A 1–100 score chip in 5 colors (Try again / Getting there / Clear / Natural / Native-like) sits quietly on your bubble.
📈 Growth that actually means something	Confidence trend (5-sentence rolling average, updates as you talk) · 5-band distribution · auto-picked "best so far" + "worth revisiting".
🎨 Full appearance customization	Theme (system / light / dark), 4 fonts, 4 sizes, 6 preset gradient backgrounds or upload your own.
🔌 Multi-provider	OpenAI / Azure OpenAI with one click. Defaults: gpt-5 + gpt-4o-transcribe + gpt-4o-mini-tts (voice instructions adapt to your companion's persona).
🔄 Auto-update	Signed in-app updater. Background check at launch; one-click install when a new version is published.
💾 Fully local	SQLite + filesystem. Every conversation, recording, and AI voice clip stays on your machine forever.

---

Screenshots

---

Quick Start

1. Prerequisites

Tool	Why	Install
Node.js ≥ 18	Frontend bundler	https://nodejs.org
Rust (stable)	Tauri backend	curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
Platform SDK	Native toolchain	macOS: xcode-select --install Windows: VS Build Tools Linux: webkit2gtk

Verify:

node -v && rustc -V && cargo -V

2. Run (dev)

git clone https://github.com/hujiulin/EchoWise.git
cd EchoWise
npm install
npm run dev

Vite starts, Rust compiles, the native desktop window pops open (~2–3 min the first time, incremental builds in seconds after).

macOS devs: after the first launch, open a separate terminal and run npm run sign:dev to inject the microphone entitlement into the dev binary — otherwise macOS denies getUserMedia. See scripts/tauri-dev.sh for the full story.

3. Build a release

# One-time: generate platform icons
npx @tauri-apps/cli icon src-tauri/icons/icon.svg

npm run build

Installers land in src-tauri/target/release/bundle/:

• macOS → .dmg / .app
• Windows → .msi / .exe
• Linux → .AppImage / .deb

4. First-run configuration

Launch and open Settings → AI provider:

Field	Default
Provider	OpenAI
Base URL	https://api.openai.com/v1
LLM model	gpt-5
ASR model	gpt-4o-transcribe
TTS model	gpt-4o-mini-tts
TTS voice	nova

Paste your API key → Test connection → Save.

Azure OpenAI also works: flip the preset at the top, fill in endpoint + api-version + three deployment names.

---

First launch on macOS

The first time you open EchoWise from a downloaded .dmg, macOS will show:

"Apple could not verify 'EchoWise.app' is free of malware that may harm your Mac…"

This is expected — EchoWise is ad-hoc signed but not notarized (Apple notarization needs a paid Developer ID). To open it:

1. System Settings → Privacy & Security — scroll to the bottom.
2. You'll see "EchoWise was blocked to protect your Mac." Click Open Anyway.
3. Double-click EchoWise again → Open in the confirmation dialog.

After that, EchoWise opens with a regular double-click forever.

---

Where data lives

Everything stays on your machine — nothing is uploaded.

Platform	Path
macOS	~/Library/Application Support/com.echowise.app/
Windows	%APPDATA%\com.echowise.app\
Linux	~/.local/share/com.echowise.app/

com.echowise.app/
├── echowise.db        # SQLite — companion, conversations, turns, stats, prefs
├── audio/<convId>/    # Your recordings (webm) + AI TTS playback (mp3)
├── avatars/           # Uploaded companion avatars
└── backgrounds/       # Uploaded background images

Uninstalling the app doesn't auto-delete this folder. Remove it manually for a clean wipe.

---

Tech stack

• Desktop shell: Tauri 2 (Rust)
• Frontend: React 18 + TypeScript + Vite
• UI: Tailwind CSS + custom shadcn-style primitives
• State: Zustand
• Database: SQLite via tauri-plugin-sql
• Icons: lucide-react
• Tests: Vitest + Testing Library

---

Project layout

EchoWise/
├── src/                        # React frontend
│   ├── App.tsx
│   ├── store.ts                # Zustand state + idle auto-end
│   ├── db.ts                   # Typed SQLite query layer
│   ├── providers.ts            # OpenAI / Azure adapters + coaching fns
│   ├── storage.ts              # Audio / avatar / background file IO
│   ├── audio.ts                # MediaRecorder + AudioContext live waveform
│   ├── scoring.ts              # 5-band scoring system
│   ├── appearance.ts           # Appearance presets
│   ├── companions.ts           # Companion defaults + topic pools
│   └── components/
│       ├── Conversation.tsx    # Main chat screen (Empty / History / Recap)
│       ├── Growth.tsx          # Growth dashboard
│       ├── Companions.tsx      # Companion editor
│       ├── Settings.tsx        # Settings (Appearance / Provider / About tabs)
│       └── ui/                 # Button / Card / Badge / Input / Separator
├── src-tauri/                  # Rust desktop shell
│   ├── src/main.rs             # SQLite migrations + Tauri plugins
│   ├── tauri.conf.json
│   ├── capabilities/
│   └── icons/
├── tests/                      # Vitest unit tests (256 tests, 94% coverage)
├── .github/workflows/
│   ├── ci.yml                  # PR / push: tests + build
│   └── release.yml             # tag v* → dmg / msi / appimage
└── scripts/
    └── tauri-dev.sh            # Auto-codesign in macOS dev

---

Testing

npm test               # one-shot
npm run test:watch     # watch mode
npm run test:ui        # browser UI
npm run test:coverage  # write HTML report to coverage/

Current coverage: 256 tests / 30 files / 94.5% lines / 82% branches / 87% funcs.

Module	Line coverage
src/lib/, src/components/ui/	100%
appearance / companions / scoring / types	100%
db / audio / storage / providers	97–100%
store	93.5%
Conversation (recording / TTS / history / recap)	91.6%

---

License

MIT © EchoWise contributors

---

_{Learn English by talking. No tests. No drills.}