FocusQuest

ADHD-friendly focus helper: Pomodoro + Quests + Gamified XP. All local. No cloud. No PII.

What

VS Code extension providing a status-bar Pomodoro timer, a quest/task tree, XP and badges to reinforce focus behavior—all offline.

Features

• Pomodoro Timer: Customizable work/break cycles with automatic long breaks
  • Work sessions (default 25 min)
  • Short breaks (default 5 min)
  • Long breaks (default 15 min) automatically triggered after completing multiple work sessions
  • Configurable threshold for long break (default: every 4 work sessions)
  • Timer display shows HH:MM:SS with second-level updates (configurable)
  • Pause/Resume support for interruptions
• Quest System: Add tasks with offline AI-powered breakdown
  • Create tasks and epics (parent tasks)
  • Archive/restore tasks for better organization
  • Edit and delete tasks
  • Right-click context menu actions
• XP & Gamification: Earn XP for completed quests and Pomodoro sessions
• Focus Mode: Toggle distraction-free layout (experimental)
• Dashboard: Visual webview showing stats and progress
• Streak Tracking: Monitor consecutive daily focus sessions
• Walkthrough: Built-in onboarding guide

Badges

Stable badges (always on):

• First Quest: Complete your first quest (first_quest)
• Three Focus Sessions: Complete 3 focus sessions (three_focus_sessions)
• Two-Day Streak: Maintain a 2 day streak (two_day_streak)

Optional experimental badges (enable setting focusquest.experimentalBadges):

• Five-Day Streak (five_day_streak)
• Pomodoro Master: 10 focus sessions (pomodoromaster)
• Distraction Slayer: 3+ day streak & 5 focus sessions (distractionslayer)
• First AI Breakdown (first_ai_breakdown)
• AI Apprentice: 20+ AI subtasks generated (ai_apprentice)
• First Streamed Breakdown (first_streamed_breakdown)
• Multi Queue: Queued multiple AI breakdowns (first_multi_queue)
• Bounce Back: Successful breakdown after an empty one (first_non_empty_after_empty)

Badge unlock events appear via status updates; only newly achieved badges are emitted.

Commands

Core commands available via Command Palette (Ctrl+Shift+P / Cmd+Shift+P):

• FocusQuest: Start Pomodoro - Begin a focus session
• FocusQuest: Cancel Pomodoro - Stop the current timer
• FocusQuest: Add Quest - Create a new task
• FocusQuest: Complete Quest - Mark a task as done and earn XP
• FocusQuest: Edit Task - Rename an existing task
• FocusQuest: Delete Task - Remove a task
• FocusQuest: Archive Task - Hide completed tasks from view
• FocusQuest: Restore Task - Bring back archived tasks
• FocusQuest: Convert to Epic - Convert task to parent epic
• FocusQuest: Show Focus Stats - View XP, level, streak, badges
• FocusQuest: Break Down Task with AI - AI-powered subtask generation
• FocusQuest: AI: Break Down This Task - Context menu AI breakdown
• FocusQuest: Cancel AI Breakdown - Stop active AI generation
• FocusQuest: Check Ollama Status - Verify AI setup
• FocusQuest: Select AI Model - Choose or enter custom Ollama model
• FocusQuest: Toggle Focus Mode - Enable/disable distraction-free layout
• FocusQuest: Reset FocusQuest Data - Clear all data (with confirmation)

Configuration

FocusQuest uses the standard Pomodoro technique with automatic long breaks:

How Long Breaks Work: After completing the configured number of focus sessions (default: 4), FocusQuest automatically starts a long break instead of a short break. The session counter resets after the long break, starting a new cycle. This follows the traditional Pomodoro technique to provide extended rest periods.

Example with defaults:

1. Focus (25 min) → Short break (5 min)
2. Focus (25 min) → Short break (5 min)
3. Focus (25 min) → Short break (5 min)
4. Focus (25 min) → Long break (15 min) ← Counter resets
5. Cycle repeats...

Privacy & Telemetry

No network requests; no custom telemetry. Telemetry currently unused; would respect env.isTelemetryEnabled if added.

Streaks

Each completed work session increments streak; streak resets when a long break starts (new cycle). Canceling a session before completion prevents increment.

Note: The session counter for long breaks persists across VS Code restarts. If you completed 2 focus sessions, closed VS Code, and reopened it, the next 2 completed sessions will trigger a long break.

Stats Command

Run FocusQuest: Show Focus Stats to view current XP, level, streak count, and earned badges.

Installation

Install FocusQuest from the Visual Studio Code Marketplace.

1. Open VS Code
2. Open Extensions view (Ctrl+Shift+X or Cmd+Shift+X)
3. Search for "FocusQuest"
4. Click Install

Getting Started

After installation, use the Command Palette (Ctrl+Shift+P or Cmd+Shift+P) to access FocusQuest commands:

• FocusQuest: Start Pomodoro - Begin a focus session
• FocusQuest: Add Quest - Create a new task
• FocusQuest: Complete Quest - Mark a task as done and earn XP
• FocusQuest: Show Focus Stats - View your progress

See the Quickstart Guide for detailed usage instructions.

Optional: AI-Powered Task Breakdown

FocusQuest can break down tasks into smaller steps using a local AI model. This requires:

1. Installing Ollama (free, open-source)
2. Pulling a model (e.g., ollama pull elyor/gpt-oss or ollama pull tinyllama)
3. Running the FocusQuest: Break Down Task with AI command

Supported Models: elyor/gpt-oss (default), llama3, llama3.2, llama3.1, tinyllama, mistral, phi3, gemma, qwen. Choose your preferred model in VS Code settings (focusquest.ai.model).

See Ollama Setup Guide for complete instructions.

Release Status

Current Version: 1.1.0 (Stable) Stability: First stable release. Core features stable; refining post-1.0 enhancements. Versioning: Follows Semantic Versioning. Breaking changes only on MAJOR. Supported VS Code: 1.105.0+

Privacy & Security

• Zero Telemetry: No analytics or tracking. Respects env.isTelemetryEnabled if future telemetry added.
• Local-First AI: All AI inference runs on your machine via Ollama. No data sent to external servers.
• Network Scope: Extension only connects to configured focusquest.ai.baseUrl (default: localhost:11434).
• Data Storage: All state (tasks, XP, badges) persists locally in VS Code's globalState.

Support & Feedback

Report issues or request features on GitHub Issues.

Roadmap (Post-1.0)

Planned enhancements after 1.0 stable release:

• Enhanced Focus Mode: Advanced layout minimization and distraction controls
• Drag-and-Drop Reordering: Rearrange tasks within tree view
• Enhanced Motivational Messaging: Adaptive encouragement tone variants
• Badge Visualization: Animations & progress bars in webview dashboard
• Enhanced Dashboard: Rich statistics and historical views

See PRD.md for detailed feature planning.

License

MIT