immerse/README.md

⚡ Focus Task

A powerful task management and focus timer plugin for Obsidian, heavily inspired by Blitzit.

🎯 Overview

Focus Task brings the power of time-boxed task management directly into your Obsidian vault. Plan your day, track time with the Pomodoro technique, and crush your tasks with satisfying checkoffs - all without leaving your notes.

Why Focus Task?

• Stay in Flow: No need to switch between apps - manage tasks where you take notes
• Time Awareness: Know exactly how long tasks take vs. your estimates
• Pomodoro Built-in: Work in focused sprints with automatic break reminders
• Satisfying Feedback: Celebratory messages and sounds when you complete tasks
• Visual Progress: See your daily progress with stats and streaks

✨ Features

📋 Task Management

• Create tasks with time estimates
• Organize tasks into customizable lists (Work, Personal, Learning, etc.)
• Add notes and details to tasks
• Filter tasks by list, today's tasks, or completed items
• Drag-and-drop task reordering

⏱️ Dual Timer Modes

Pomodoro Timer

• Configurable work sessions (default: 25 minutes)
• Short breaks (default: 5 minutes)
• Long breaks after a set number of pomodoros (default: 15 minutes every 4 pomodoros)
• Auto-start break option
• Visual countdown with progress bar

Stopwatch Mode

• Free-form time tracking
• Alerts when you exceed your estimate
• Track actual time vs. estimated time

📊 Progress Tracking

• Daily Stats: See tasks completed, focus time, and more
• Streak Counter: Build momentum with consecutive productive days
• Time Comparison: Compare estimated vs. actual time to improve planning
• Pomodoro Count: Track total pomodoros completed

🎨 User Experience

• Status Bar Timer: timer that stays visible while you work
• Celebration Messages: Fun, randomized messages when you complete tasks
• Sound Notifications: Audio alerts for timer completion and task completion
• Keyboard Shortcuts: Quick access to common actions
• Responsive Design: Works great in any panel size

🚀 Installation

From Obsidian Community Plugins (Coming Soon)

1. Open Obsidian Settings
2. Go to Community Plugins
3. Search for "Focus Task"
4. Click Install, then Enable

Manual Installation

1. Download the latest release from the releases page
2. Extract the files to your vault's .obsidian/plugins/focus-task/ folder
3. Reload Obsidian
4. Enable the plugin in Settings → Community Plugins

Building from Source

# Clone the repository
git clone https://git.cribdev.com/crib/focus-task.git
cd focus-task

# Install dependencies
npm install

# Build the plugin
npm run build

# Copy to your vault
cp main.js manifest.json styles.css /path/to/your/vault/.obsidian/plugins/focus-task/

📖 Usage

Getting Started

1. Open Focus Task: Click the ⚡ icon in the ribbon or use the command palette (Ctrl/Cmd + P → "Open Focus Task Panel")

2. Add a Task: Click "+ Add Task" and fill in:

   • Task description
   • Time estimate
   • List category

3. Start Focusing: Click ▶ on any task to start a Pomodoro session, or ⏱ for stopwatch mode

4. Complete Tasks: Check off tasks when done and enjoy the celebration!

Keyboard Shortcuts

Action	Command
Open Panel	Ctrl/Cmd + P → "Open Focus Task Panel"
Quick Add Task	Ctrl/Cmd + P → "Quick Add Task"
Toggle Timer	Ctrl/Cmd + P → "Toggle Timer"
Complete Task	Ctrl/Cmd + P → "Complete Current Task"
Start Focus	Ctrl/Cmd + P → "Start Focus Mode on Next Task"

Timer Modes Explained

🍅 Pomodoro Mode (▶ button)

Best for: Maintaining focus on challenging tasks

1. Timer counts down from your configured work duration
2. When time's up, you'll get a notification
3. Take a break (short or long, based on your settings)
4. Repeat until the task is complete

⏱️ Stopwatch Mode (⏱ button)

Best for: Tracking time on open-ended tasks

1. Timer counts up from zero
2. Get alerted when you exceed your estimate
3. Stop whenever the task is complete
4. See exactly how long the task took

⚙️ Settings

Pomodoro Timer

Setting	Description	Default
Work Duration	Length of each work session	25 min
Short Break	Length of short breaks	5 min
Long Break	Length of long breaks	15 min
Long Break Interval	Pomodoros before a long break	4
Auto-start Breaks	Automatically start break timer	Off

General

Setting	Description	Default
Default Time Estimate	Default estimate for new tasks	30 min
Enable Sounds	Play completion/alert sounds	On
Enable Celebrations	Show celebration messages	On
Show Floating Timer	Display draggable timer widget	On

Lists

Customize your task lists with:

• Custom names
• Emoji icons
• Color coding

Default lists: Work 💼, Personal 🏠, Learning 📚

🎨 Customization

Adding Custom Lists

1. Go to Settings → Focus Task → Lists
2. Click "+ Add List"
3. Set the name, emoji, and color
4. Click Save

Theming

Focus Task respects your Obsidian theme and adapts to both light and dark modes automatically.

📁 Project Structure

focus-task/
├── src/
│   ├── main.ts        # Main plugin class
│   ├── types.ts       # TypeScript interfaces
│   ├── view.ts        # Main UI view
│   └── modals.ts      # Task modals
├── styles.css         # Plugin styles
├── manifest.json      # Obsidian plugin manifest
├── package.json       # npm configuration
├── tsconfig.json      # TypeScript config
├── esbuild.config.mjs # Build configuration
└── README.md          # This file

🙏 Inspiration & Credits

This plugin is heavily inspired by Blitzit, a fantastic standalone productivity app that combines task management with focused time tracking.

Blitzit's approach to productivity resonated with me:

• Simple, focused interface
• Time estimation and tracking
• Pomodoro technique integration
• Satisfying task completion experience
• Progress insights

I wanted to bring this experience directly into Obsidian, where I already manage my notes and knowledge. Focus Task is my attempt to capture the essence of what makes Blitzit great while leveraging Obsidian's powerful ecosystem.

If you're looking for a dedicated productivity app, I highly recommend checking out Blitzit!

🤝 Contributing

Contributions are welcome! Feel free to:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Setup

# Clone the repo
git clone https://git.cribdev.com/crib/focus-task.git
cd focus-task

# Install dependencies
npm install

# Start development build (watches for changes)
npm run dev

# Create symlink to your test vault
ln -s $(pwd) /path/to/vault/.obsidian/plugins/focus-task

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

• Repository: https://git.cribdev.com/crib/focus-task
• Issues: https://git.cribdev.com/crib/focus-task/issues
• Inspiration: Blitzit App

---

Made with ❤️ for the Obsidian community
Inspired by Blitzit ⚡