Your guide for right now.
Ima is an personal guidance app built for people with ADHD and anyone who struggles with consistency across multiple goals. Unlike passive habit trackers that wait for you to open them, Ima actively plans your day, nudges you at the right moments, adapts when plans change, and never makes you feel guilty for being human.
The name comes from the Japanese word 今 (いま), meaning "now." Because the only question that matters is: what should I do right now?
Every productivity app assumes you have consistent willpower, predictable energy, and the ability to just "do the thing." For ADHD brains, that's not how it works. You know what you need to do, you just can't start. And when you miss a day, the guilt spiral makes it worse.
Ima flips the model:
- The app comes to you — morning plans, smart nudges, reaching out to you when you go quiet
- No guilt — missed a day? "That's fine. Here's what we can still do today."
- Just the next thing — not a wall of 15 tasks, just the ONE thing to do right now and what it takes to complete it.
- Adapts in real-time — low energy? Lighter plan. Raining? Home workout instead.
- Remembers everything — after 30 days, it knows your patterns, weak spots, and peak hours.
- AI Onboarding Interview — detailed conversation, not a generic form
- Timetable Generation — AI creates phased roadmaps with milestones for each goal
- Daily Planning — context based plans based on energy, weather, schedule, and history
- Dashboard — today's tasks grouped by goal with tips and time estimates
- "I'm Stuck" Mode — breaks tasks into absurdly small micro-steps for task paralysis
- Push Notifications — proper guiding, not generic app alerts
- 7-Day History — visual progress tracking with streak counter
- Weekly Review — AI-generated summary with pattern detection and suggestions
- Energy-Aware Scheduling — plans adjust based on how you're feeling today
| Layer | Technology |
|---|---|
| Frontend | React (TypeScript) + Vite + Tailwind CSS |
| Backend | Django 5.x + Django REST Framework + Django Channels |
| Database | PostgreSQL 16 |
| Task Queue | Celery + Redis |
| AI | Anthropic Claude API (provider-agnostic abstraction) |
| Notifications | Web Push (VAPID), with FCM/APNs abstraction for future native apps |
| Testing | pytest + Playwright + Vitest + React Testing Library |
| CI/CD | GitHub Actions |
┌──────────────────────────────────────────┐
│ CLIENT (PWA) │
│ React (TS) + Vite + Tailwind │
│ Installable on any device │
└─────────────┬──────────┬────────────────┘
│ REST │ WebSocket
▼ ▼
┌──────────────────────────────────────────┐
│ BACKEND (Django) │
│ REST API (/api/v1/) + Channels (WS) │
│ Coaching Engine + AI Abstraction │
└──────┬──────────┬──────────┬────────────┘
▼ ▼ ▼
PostgreSQL Redis AI Provider
(Claude/GPT/Local)
The backend is fully frontend-agnostic — it serves JSON only, uses JWT auth, and supports API versioning. This means the same backend can power a PWA, React Native app, Flutter app, or any future client without changes.
For full architecture details, see ARCHITECTURE.md.
- Python 3.12+
- Node.js 20+
- PostgreSQL 16+
- Redis 7+
- Docker & Docker Compose (recommended for local services)
# Clone the repo
git clone https://github.com/YOUR_USERNAME/ima.git
cd ima
# Start database and cache
docker compose up -d
# Backend setup
cd backend
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env # Edit with your API keys
python manage.py migrate
python manage.py createsuperuser
python manage.py runserver
# Frontend setup (new terminal)
cd frontend
npm install
npm run devThe app will be available at http://localhost:5173 (frontend) and http://localhost:8000 (API).
Copy .env.example to .env and fill in:
# Required
SECRET_KEY=your-secret-key
DATABASE_URL=postgres://user:pass@localhost:5432/ima
REDIS_URL=redis://localhost:6379/0
ANTHROPIC_API_KEY=your-api-key
# Optional
OPENWEATHER_API_KEY=your-key
VAPID_PRIVATE_KEY=generated-key
VAPID_PUBLIC_KEY=generated-keyThis project follows strict TDD based on "Test-Driven Development with Python" by Harry Percival. The cycle is:
1. RED — Write a failing test
2. GREEN — Write minimum code to pass
3. REFACTOR — Clean up, keep tests green
4. COMMIT — Every green state gets a commit
No implementation code is written without a failing test first. See CLAUDE.md for the complete TDD workflow.
# Backend — all tests
cd backend && pytest
# Backend — with coverage
pytest --cov=. --cov-report=html
# Backend — specific app
pytest accounts/tests/
# Frontend — unit tests
cd frontend && npm run test
# Frontend — E2E tests
npx playwright testThis project uses Claude Code custom commands as specialized development agents:
| Command | Role | What It Does |
|---|---|---|
/plan |
Planner | Creates step-by-step TDD implementation plan |
/dev |
Engineer | Writes tests + code following TDD cycle |
/commit |
Committer | Runs tests, stages, commits with proper messages |
/review |
Reviewer | Reviews code for quality, security, TDD compliance |
/qa |
QA Engineer | Finds missing tests, edge cases, coverage gaps |
/architect |
Architect | Checks codebase against ARCHITECTURE.md |
/code-review |
Multi-Agent | Runs 4 parallel review subagents before merge |
Development cycle: /plan → /dev → /commit (repeat) → /review → /qa → /code-review → merge
# Never commit directly to main
git checkout -b feat/feature-name # Create feature branch
# ... TDD cycle with commits ...
git push origin feat/feature-name # Push branch
gh pr create # Create PR
# After review + CI passes:
gh pr merge --squash # Merge to mainBranch naming: feat/, fix/, chore/, docs/
Commit format: type(scope): description (Conventional Commits)
ima/
├── .claude/commands/ # Claude Code agent commands
├── .github/workflows/ # CI/CD (GitHub Actions)
│
├── backend/
│ ├── accounts/ # User auth + profiles
│ ├── goals/ # Goals, timetables, daily actions
│ ├── guidance/ # AI guidance engine, chat, check-ins
│ ├── ai/ # AI provider abstraction
│ ├── notifications/ # Push notifications (multi-platform)
│ ├── analytics/ # History, patterns, weekly reviews
│ ├── functional_tests/ # User story tests
│ └── conftest.py # Shared test fixtures
│
├── frontend/
│ ├── src/
│ │ ├── pages/ # Login, Onboarding, Home, Settings
│ │ ├── components/ # Chat, Dashboard, shared UI
│ │ ├── api/ # API client layer
│ │ ├── stores/ # Zustand state management
│ │ └── hooks/ # Custom React hooks
│ └── e2e/ # Playwright E2E tests
│
├── CLAUDE.md # Project guide (AI agent instructions)
├── PRD.md # Product requirements
├── ARCHITECTURE.md # Technical architecture
└── docker-compose.yml # Local dev services
| Document | Contents |
|---|---|
| CLAUDE.md | Project conventions, TDD rules, implementation phases, agent workflow, git workflow — the source of truth for development |
| PRD.md | Product requirements, feature specs, user stories, design principles, monetization architecture |
| ARCHITECTURE.md | Data models, API specs, AI prompt templates, notification system, deployment config, security checklist |
| Phase | Feature | Status |
|---|---|---|
| 0 | Project scaffolding + CI | |
| 1 | Auth + User model | |
| 2 | Goals + Timetable engine | |
| 3 | Onboarding flow | |
| 4 | Daily guidance engine | |
| 5 | Frontend (Chat + Dashboard) | |
| 6 | Push notifications | |
| 7 | Analytics + Patterns |
- The app comes to you — users never need to remember to open the app
- No guilt, ever — missed tasks are met with understanding, not shame
- Just the next thing — show ONE action, not a wall of tasks
- Adaptive, not rigid — plans flex with energy, weather, and life
- The guide knows you — every interaction builds context over time
- Security first — encrypted data, provider-agnostic AI, local-first option
今 — What should I do right now?