88 lines
4.3 KiB
Markdown
88 lines
4.3 KiB
Markdown
# 🧠 Mindlist — Free & Open-Source ADHD Task Breaker
|
|
|
|
A free and open-source alternative to [Neurolist](https://neurolist.app): an AI-assisted planner built as a **cognitive prosthetic** for ADHD executive dysfunction — task-initiation paralysis, overwhelming to-dos, and time blindness.
|
|
|
|
You bring the task. Mindlist breaks it into calm, timed micro-steps and walks you through them **one at a time** with a focus playlist timer. **BYOK**: your own OpenRouter key, your data stays on your device.
|
|
|
|
|
|
|
|
## ✨ Features
|
|
|
|
| Area | What it does |
|
|
|---|---|
|
|
| **Magic Subtasks** | Any daunting task → sequenced micro-step checklist with per-step minutes, in **Easy / Medium / Hard** granularity (Hard = hyper-granular, zero-implicit-knowledge physical moves) |
|
|
| **Life Context** | Persistent constraints (small apartment, low energy, distractions…) shape every AI breakdown |
|
|
| **AI Edit** | Conversational patching — *"no vacuum, shorter phases", "expand step 4"* — full plan recalculated |
|
|
| **Brain Dump import** | Paste chaos → AI extracts distinct tasks and breaks each down |
|
|
| **Focus playlist** | Single-task card (future steps hidden), countdown ring, pause / +1 min / skip / complete, Wake Lock |
|
|
| **Voice + recalibration** | Spoken step transitions (Web Speech), dynamic projected end-time |
|
|
| **Library** | One-tap reuse of tuned breakdowns (morning routine, cleaning, …) |
|
|
| **Calendar export** | `.ics` with alarms, based on live remaining time |
|
|
| **Offline fallback** | No key / offline / API error → built-in heuristic breakdowns, timer keeps working |
|
|
| **Local-first** | Dexie (IndexedDB) persistence, no backend, no tracking, dark mode, PWA installable |
|
|
|
|
## 🔑 BYOK setup (2 minutes)
|
|
|
|
1. Get an OpenRouter key: <https://openrouter.ai/keys> (default model `deepseek/deepseek-v4.1-flash` costs a fraction of a cent per breakdown)
|
|
2. Open the app → ⚙️ Settings → paste the key, confirm the model
|
|
3. The key lives in `localStorage` (`mindlist.or.key`) on your device only and is sent straight to `https://openrouter.ai/api/v1/chat/completions`. It is **never** committed — `.gitignore` blocks key files.
|
|
|
|
## 🛠️ Development
|
|
|
|
```bash
|
|
npm install
|
|
npm run dev # http://localhost:5173
|
|
npm test # vitest
|
|
npm run build # PWA output in dist/
|
|
```
|
|
|
|
Deploy the PWA anywhere static: `dist/` → GitHub Pages / Netlify / Vercel. On Android: browser → *Add to Home screen*, or build the native wrapper below.
|
|
|
|
## 🤖 Android app (Capacitor)
|
|
|
|
Prerequisites (macOS): JDK 21 (`brew install openjdk@21`), Android SDK platform + build-tools 36 (`sdkmanager`), `ANDROID_HOME` set, `sdk.dir` in `android/local.properties` (untracked).
|
|
|
|
```bash
|
|
npm run build
|
|
npx cap sync android
|
|
cd android
|
|
export JAVA_HOME=/opt/homebrew/opt/openjdk@21
|
|
./gradlew assembleDebug # quick on-device test
|
|
./gradlew assembleRelease # signed, needs keystore (below)
|
|
adb install -r app/build/outputs/apk/release/app-release.apk
|
|
```
|
|
|
|
**Signing:** release builds need `android/mindlist-release.keystore` + `android/keystore.properties` (both git-ignored — **back them up**: password manager + offline copy. Lose them and no future update can ship under the same signature).
|
|
|
|
```bash
|
|
# one-time: create key
|
|
keytool -genkeypair -keystore android/mindlist-release.keystore \
|
|
-alias mindlist -keyalg RSA -keysize 2048 -validity 10000
|
|
# then create android/keystore.properties:
|
|
# storeFile=../mindlist-release.keystore
|
|
# storePassword=…
|
|
# keyAlias=mindlist
|
|
# keyPassword=…
|
|
```
|
|
|
|
## 🗂️ Project structure
|
|
|
|
```
|
|
src/
|
|
App.tsx # all views: Today, Composer, Focus, Dump, Library, Settings
|
|
lib/openrouter.ts # BYOK client (default: deepseek/deepseek-v4.1-flash)
|
|
lib/prompts.ts # Easy/Med/Hard + BrainDump + AI-Edit system prompts
|
|
lib/fallback.ts # offline heuristic plans + speech/beep
|
|
lib/store.ts # Dexie schema, prefs, .ics export
|
|
app.test.ts # vitest suite
|
|
logo/ # logo sources (v3 = final) + Android foreground asset
|
|
public/ # favicon, PWA icons (192/512), apple-touch-icon
|
|
android/ # Capacitor native project (icons, signing config)
|
|
```
|
|
|
|
See [AGENTS.md](AGENTS.md) if you (or an AI agent) want to contribute.
|
|
|
|
## 📄 License
|
|
|
|
MIT — free for personal and commercial use. See [LICENSE](LICENSE).
|