Shiori V1

栞 Shiori

The AI-powered study companion for serious students.

[](https://github.com/kaorii-ako/Shiori-v1/stargazers) [](LICENSE) [](https://shiori-v1.vercel.app) [](https://github.com/kaorii-ako/Shiori-v1/actions)

🎮 Try Demo · [📖 Docs](#-quick-start) · 🐛 Report Bug · 💡 Request Feature

---

What is Shiori?

Shiori (栞, bookmark in Japanese) is an open-source AI study companion built for students who take their grades seriously. It combines AI-powered study tools, gamification, and productivity features into one beautiful dark-mode app.

No subscription required for core features. Bring your own free Gemini API key. Self-hostable in 5 minutes.

> 🎮 Try the live demo — no account, no API key needed.

---

✨ Features

| Feature | Description | |---------|-------------| | 🤖 AI Quiz Generator | Generate MCQ quizzes from your notes with Gemini AI | | 🃏 AI Flashcards | Auto-generate spaced repetition flashcard decks | | 📊 Grade Tracker | Weighted grade calculator with GPA predictor | | 📅 Assignment Manager | Due dates, priorities, completion tracking | | 📝 Markdown Notes | Two-panel editor with live preview | | 🎯 Focus Mode | Pomodoro timer with task linking | | 🏆 Leaderboard | Compare XP and streaks with friends | | 📈 Analytics | Study time, grade trends, completion rates | | 🌱 Habit Tracker | Daily habit streaks with completion heatmap | | 🗓 Study Plans | AI-generated day-by-day study schedules | | 📚 Syllabus Import | Parse syllabi to auto-create assignments | | ⌨️ Keyboard Shortcuts | Power-user navigation (gh, ga, gn, gq...) | | 🎮 Gamification | XP system, levels (Freshman → Graduate), achievements |

---

🚀 Quick Start

Option 1: Live demo (no setup)

👉 shiori-v1.vercel.app/demo

No account. No API key. Full experience.

Option 2: Deploy to Vercel (1 click)

[](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fkaorii-ako%2FShiori-v1&env=VITESUPABASEURL,VITESUPABASEANON_KEY&envDescription=Required%20for%20user%20accounts&project-name=shiori&repository-name=Shiori-v1)

Option 3: Self-host locally

Prerequisites: Node.js 18+, free Supabase account, free Gemini API key

# Clone
git clone https://github.com/kaorii-ako/Shiori-v1.git
cd Shiori-v1

# Configure
cp .env.example .env
# Edit .env with your Supabase URL + anon key

# Run Supabase schema
# → Open supabase/schema.sql in your Supabase SQL Editor and run it

# Install + start
npm install
npm run dev

Open http://localhost:5173 → click Try Demo or sign up.

Environment Variables

| Variable | Required | Where to get | |----------|----------|--------------| | VITE_SUPABASE_URL | ✅ Yes | supabase.com → Settings → API | | VITE_SUPABASE_ANON_KEY | ✅ Yes | supabase.com → Settings → API | | VITE_GEMINI_API_KEY | Optional | aistudio.google.com/apikey (free) |

---

🏗 Tech Stack

Frontend:   React 18 + Vite + Zustand
Database:   Supabase (PostgreSQL + Auth)
AI:         Google Gemini 1.5 Flash (client-side, BYOK)
Deployment: Vercel

---

⌨️ Keyboard Shortcuts

| Shortcut | Action | |----------|--------| | g h | Go to Home | | g a | Go to Assignments | | g n | Go to Notes | | g f | Go to Flashcards | | g q | Go to Quiz | | g g | Go to Grades | | ? | Show all shortcuts |

---

📁 Project Structure

Shiori-v1/
├── client/               # React + Vite frontend
│   └── src/
│       ├── pages/        # 16 pages (Home, Assignments, Grades, Notes...)
│       ├── components/   # Shared components (Sidebar, GlassCard, AIChat...)
│       ├── stores/       # Zustand state management
│       ├── utils/        # theme.js, gemini.js, demoData.js
│       └── lib/          # supabase.js, db.js
├── server/               # Express.js backend (optional, for Stripe webhooks)
├── extension/            # Chrome MV3 extension
├── supabase/             # Database schema + setup guide
└── docs/                 # Screenshots, specs

---

🤝 Contributing

Contributions are welcome! Shiori is built by students for students.

1. Check good first issues
2. Read [CONTRIBUTING.md](CONTRIBUTING.md)
3. Fork → branch → PR

---

📄 License

[MIT](LICENSE) — free for personal and commercial use.

---

Made with ❤️ by Tawin Tangsukson

If Shiori helps you study better, please consider giving it a ⭐ — it means a lot!

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kaorii-ako
• Source: kaorii-ako/Shiori-v1
• License: MIT
• Homepage: https://shiori-v1.vercel.app

Install and usage instructions live in the source repository linked above.