294 lines
11 KiB
Markdown
294 lines
11 KiB
Markdown
# ⚡ Immerse
|
|
|
|
A powerful task management and focus timer plugin for [Obsidian](https://obsidian.md), heavily inspired by [Blitzit](https://www.blitzit.app/).
|
|
|
|
|
|
|
|
|
|
|
|
## 🎯 Overview
|
|
|
|
Immerse 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 Immerse?
|
|
|
|
- **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
|
|
- **Daily Note Logging**: Automatically log completed tasks to your daily notes with timestamps and performance metrics
|
|
|
|
### 📈 Reporting & Analytics (New in v1.1.0!)
|
|
- **Comprehensive Reports**: View detailed productivity reports with date range filtering
|
|
- **Key Metrics Dashboard**: Track tasks done, tasks per day, hours per day, minutes per task, and day streaks
|
|
- **Visual Analytics**: Pie charts showing task distribution and time allocation
|
|
- **Time by List**: See how much time you spend on different task categories
|
|
- **Productivity Insights**: Discover your most productive hour, day, and month
|
|
- **Daily Breakdown**: Visual bar charts showing last 10 days of activity
|
|
- **Quick Filters**: Today, Last 7/30/90 days for easy report generation
|
|
|
|
### 🗓️ Task Scheduling & Reminders (New in v1.1.0!)
|
|
- **Schedule Tasks**: Set specific date and time for tasks
|
|
- **Smart Reminders**: Get notifications before task is due (5/10/15/30/60 minute options)
|
|
- **Overdue Detection**: Visual indicators (⚠️ red badge) for past-due tasks
|
|
- **Startup Checks**: Alerts when opening Obsidian if tasks are overdue
|
|
- **Background Monitoring**: Automatic 30-second checks for due tasks
|
|
- **Sound Alerts**: Optional audio notifications for reminders
|
|
|
|
### 📱 Mobile Optimized (New in v1.1.0!)
|
|
- **Responsive Design**: Fully optimized for mobile screens (tablets and phones)
|
|
- **Touch-Friendly**: Larger buttons and tap targets (44px minimum)
|
|
- **Adaptive Layouts**: Charts and visualizations scale appropriately
|
|
- **Mobile Testing**: Works great on Obsidian mobile app
|
|
|
|
### 🎨 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 "Immerse"
|
|
4. Click Install, then Enable
|
|
|
|
### Manual Installation
|
|
1. Download the latest release from the [releases page](https://git.cribdev.com/crib/immerse/releases)
|
|
2. Extract the files to your vault's `.obsidian/plugins/immerse/` folder
|
|
3. **⚠️ IMPORTANT**: When updating, do NOT replace or delete the existing `data.json` file - this contains all your tasks, settings, and progress!
|
|
4. Reload Obsidian
|
|
5. Enable the plugin in Settings → Community Plugins
|
|
|
|
> **Note**: Only copy the three plugin files (`main.js`, `manifest.json`, `styles.css`) when updating. Your `data.json` file stores all your tasks and settings and should never be replaced.
|
|
|
|
### Building from Source
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://git.cribdev.com/crib/immerse.git
|
|
cd immerse
|
|
|
|
# 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/immerse/
|
|
```
|
|
|
|
## 📖 Usage
|
|
|
|
### Getting Started
|
|
|
|
1. **Open Immerse**: Click the ⚡ icon in the ribbon or use the command palette (`Ctrl/Cmd + P` → "Open Immerse 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 Immerse 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 | On |
|
|
|
|
### 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 |
|
|
|
|
### Daily Note Integration
|
|
|
|
| Setting | Description | Default |
|
|
|---------|-------------|---------|
|
|
| Log to Daily Note | Automatically log completed tasks to your daily note | Off |
|
|
|
|
When enabled, completed tasks are automatically appended to your daily note with:
|
|
|
|
- Task name and list category
|
|
- Time spent vs. estimated time
|
|
- Completion timestamp
|
|
- Performance indicator (under/over/on target)
|
|
|
|
**Example entry:**
|
|
|
|
```
|
|
- [x] Write project proposal | 💼 Work | ⏱️ 45min / 30min (15min over estimate) | ✅ 14:30
|
|
```
|
|
|
|
**Requirements:** The core "Daily Notes" plugin must be enabled in Obsidian settings. Immerse respects your Daily Notes configuration (folder, date format, and template).
|
|
|
|
### 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 → Immerse → Lists
|
|
2. Click "+ Add List"
|
|
3. Set the name, emoji, and color
|
|
4. Click Save
|
|
|
|
### Theming
|
|
Immerse respects your Obsidian theme and adapts to both light and dark modes automatically.
|
|
|
|
## 📁 Project Structure
|
|
|
|
```
|
|
immerse/
|
|
├── 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](https://www.blitzit.app/)**, 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. Immerse 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](https://www.blitzit.app/)!**
|
|
|
|
## 🤝 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
|
|
|
|
```bash
|
|
# Clone the repo
|
|
git clone https://git.cribdev.com/crib/immerse.git
|
|
cd immerse
|
|
|
|
# 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/immerse
|
|
```
|
|
|
|
## 📜 License
|
|
|
|
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
|
|
|
## 🔗 Links
|
|
|
|
- **Repository**: [https://git.cribdev.com/crib/immerse](https://git.cribdev.com/crib/immerse)
|
|
- **Issues**: [https://git.cribdev.com/crib/immerse/issues](https://git.cribdev.com/crib/immerse/issues)
|
|
- **Inspiration**: [Blitzit App](https://www.blitzit.app/)
|
|
|
|
---
|
|
|
|
<p align="center">
|
|
Made with ❤️ for the Obsidian community
|
|
<br>
|
|
Inspired by <a href="https://www.blitzit.app/">Blitzit</a> ⚡
|
|
<br><br>
|
|
<em>✨ Vibe coded with assistance from <a href="https://claude.ai">Claude.ai</a></em>
|
|
</p>
|