{"id":47251227,"url":"https://github.com/georgiosnikitas/brain-break","last_synced_at":"2026-05-10T01:28:55.522Z","repository":{"id":341367332,"uuid":"1169854697","full_name":"georgiosnikitas/brain-break","owner":"georgiosnikitas","description":"🧠🔨 Brain Break is an AI-powered terminal quiz app.","archived":false,"fork":false,"pushed_at":"2026-03-29T00:13:33.000Z","size":736,"stargazers_count":9,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-29T01:43:50.480Z","etag":null,"topics":["ai","cli","github-copilot","nodejs","quiz","terminal","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/georgiosnikitas.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-01T10:24:09.000Z","updated_at":"2026-03-29T00:13:37.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/georgiosnikitas/brain-break","commit_stats":null,"previous_names":["georgiosnikitas/brain-break"],"tags_count":33,"template":false,"template_full_name":null,"purl":"pkg:github/georgiosnikitas/brain-break","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/georgiosnikitas%2Fbrain-break","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/georgiosnikitas%2Fbrain-break/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/georgiosnikitas%2Fbrain-break/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/georgiosnikitas%2Fbrain-break/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/georgiosnikitas","download_url":"https://codeload.github.com/georgiosnikitas/brain-break/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/georgiosnikitas%2Fbrain-break/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31290742,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","cli","github-copilot","nodejs","quiz","terminal","typescript"],"created_at":"2026-03-14T14:29:44.969Z","updated_at":"2026-04-01T22:34:13.920Z","avatar_url":"https://github.com/georgiosnikitas.png","language":"TypeScript","funding_links":["https://www.buymeacoffee.com/georgiosnikitas"],"categories":[],"sub_categories":[],"readme":"\n# 🧠🔨 Brain Break\n\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=georgiosnikitas_brain-break\u0026metric=alert_status)](https://sonarcloud.io/summary/overall?id=georgiosnikitas_brain-break)\n[![CI](https://github.com/georgiosnikitas/brain-break/actions/workflows/ci.yml/badge.svg)](https://github.com/georgiosnikitas/brain-break/actions/workflows/ci.yml)\n[![Release](https://github.com/georgiosnikitas/brain-break/actions/workflows/release.yml/badge.svg?event=push)](https://github.com/georgiosnikitas/brain-break/actions/workflows/release.yml)\n[![npm](https://img.shields.io/npm/v/brain-break)](https://www.npmjs.com/package/brain-break)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue?logo=typescript)](https://www.typescriptlang.org/)\n[![License](https://img.shields.io/github/license/georgiosnikitas/brain-break)](LICENSE)\n[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-ffdd00?style=flat\u0026logo=buy-me-a-coffee\u0026logoColor=black)](https://www.buymeacoffee.com/georgiosnikitas)\n\nBrain Break is an AI-powered terminal quiz app built with TypeScript. Define quiz domains, answer AI-generated questions, and review your score progression and history — all from a CLI interface. Choose from multiple AI providers including Anthropic, OpenAI, Google Gemini, GitHub Copilot and Ollama for local models.\n\n```\n  🧠🔨\n   ____            _          ____                 _\n  | __ ) _ __ __ _(_)_ __    | __ ) _ __ ___  __ _| | __\n  |  _ \\| '__/ _` | | '_ \\   |  _ \\| '__/ _ \\/ _` | |/ /\n  | |_) | | | (_| | | | | |  | |_) | | |  __/ (_| |   \u003c\n  |____/|_|  \\__,_|_|_| |_|  |____/|_|  \\___|\\__,_|_|\\_\\\n\n  \u003e Train your brain, one question at a time_\n```\n\n## ✨ Features\n\n- **Multiple AI providers** — Anthropic, OpenAI, Google Gemini, GitHub Copilot, and Ollama (local LLMs)\n- **Domain-based quiz sessions** — create any topic like `java-programming`, `greek-mythology`, or `thai-cuisine`\n- **AI-generated questions** — multiple-choice questions with automatic deduplication\n- **Explain answer** — ask the AI to explain why the correct answer is right after any question\n- **Teach me more** — drill deeper with AI-generated micro-lessons after viewing an explanation\n- **Question bookmarking** — bookmark any answered question from the quiz or history for later revisiting via a dedicated bookmarks view\n- **Adaptive difficulty** — scoring and difficulty progression based on correctness and response speed\n- **Configurable language and tone** — language selection for questions and explanations, plus 7 tone options including humorous, sarcastic, and pirate\n- **Domain sub-menu** — play, history, bookmarks, stats, archive, and delete per domain\n- **Stats dashboard** — per-domain score trend, accuracy, and return streak\n- **Settings screen** — change provider, model, language, tone, and welcome screen at any time\n\n## 📋 Requirements\n\n- Node.js `\u003e= 22.0.0`\n- An AI provider configured through the in-app settings:\n  - **Anthropic** — `ANTHROPIC_API_KEY` environment variable and a model name configured in setup/settings (default: `claude-sonnet-4-20250514`)\n  - **OpenAI** — `OPENAI_API_KEY` environment variable and a model name configured in setup/settings (default: `gpt-4o-mini`)\n  - **Google Gemini** — `GOOGLE_GENERATIVE_AI_API_KEY` environment variable and a model name configured in setup/settings (default: `gemini-2.0-flash`)\n  - **GitHub Copilot** — a GitHub account with an active Copilot subscription and Copilot authentication in the environment\n  - **Ollama** — a running Ollama instance with endpoint and model configured in setup/settings (defaults: `http://localhost:11434`, `llama3`)\n\n## 🚀 Installation\n\n### 🍺 Homebrew (macOS)\n\n```bash\nbrew tap georgiosnikitas/brain-break\nbrew install brain-break\n```\n\n### 📦 From npm\n\n```bash\nnpm install -g brain-break\n```\n\n### 📦 From GitHub Packages\n\n```bash\nnpm install -g @georgiosnikitas/brain-break --registry=https://npm.pkg.github.com\n```\n\n\u003e **Note:** GitHub Packages requires authentication even for public packages. Add a [personal access token](https://github.com/settings/tokens) with `read:packages` scope to your `~/.npmrc`:\n\u003e\n\u003e ```\n\u003e //npm.pkg.github.com/:_authToken=YOUR_TOKEN\n\u003e ```\n\nAfter installing via Homebrew, npm, or GitHub Packages, run it from anywhere:\n\n```bash\nbrain-break\n```\n\n### 🛠️ From Source\n\n```bash\ngit clone https://github.com/georgiosnikitas/brain-break.git\ncd brain-break\nnpm install\nnpm run dev\n```\n\n## 📜 Available Scripts\n\n```bash\nnpm run dev         # run from source with tsx\nnpm run build       # compile TypeScript to dist/\nnpm start           # run the compiled CLI\nnpm run typecheck   # run TypeScript type checking without emitting\nnpm test            # run the Vitest test suite once\nnpm run test:watch  # run Vitest in watch mode\n```\n\n## ⚙️ How It Works\n\nOn first launch, Brain Break prompts you to select and configure an AI provider. From the home screen you can create quiz domains, play sessions, review history and stats, or change settings. During a quiz, the app generates questions via your chosen provider, times your answers, and updates your score and difficulty level automatically.\n\n## 📝 Notes\n\n- For cloud providers (OpenAI, Anthropic, Gemini), set the corresponding API key environment variable before running the app.\n- For Ollama, ensure the Ollama server is running and the chosen model is pulled locally.\n- All quiz data and settings are stored locally under `~/.brain-break/`.\n\n## 🤝 Contributing\n\nContributions are welcome. The project uses TypeScript with Vitest for testing — run `npm test` before submitting a pull request.\n\nFor context on the product goals and feature decisions, see the planning artifacts in [`docs/planning-artifacts/`](docs/planning-artifacts/):\n\n- [Product Brief](docs/planning-artifacts/product-brief.md) — vision, problem statement, and success metrics\n- [PRD](docs/planning-artifacts/prd.md) — detailed feature specifications and acceptance criteria\n- [Architecture](docs/planning-artifacts/architecture.md) — technical design decisions\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeorgiosnikitas%2Fbrain-break","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgeorgiosnikitas%2Fbrain-break","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeorgiosnikitas%2Fbrain-break/lists"}