crib/immerse
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 15 Wiki Activity

Updated README.md

Browse Source
This commit is contained in:
crib
2025-11-25 17:27:27 +01:00
parent c218162edf
commit 264441f83b
1 changed files with 39 additions and 221 deletions
Download Patch File Download Diff File Expand all files Collapse all files

260
README.md
View File

@@ -8,75 +8,31 @@ A powerful task management and focus timer plugin for [Obsidian](https://obsidia
## 🎯 Overview ## 🎯 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. Task management and focus timer for Obsidian. Plan your day, track time with Pomodoro technique, and manage tasks without leaving your vault.
### Why Immerse? ## ✨ Key Features
- **Stay in Flow**: No need to switch between apps - manage tasks where you take notes **📋 Task Management**
- **Time Awareness**: Know exactly how long tasks take vs. your estimates - Create tasks with time estimates and organize into customizable lists
- **Pomodoro Built-in**: Work in focused sprints with automatic break reminders - Filter by list, status, or date
- **Satisfying Feedback**: Celebratory messages and sounds when you complete tasks - Schedule tasks with reminders (5/10/15/30/60 min before due)
- **Visual Progress**: See your daily progress with stats and streaks - Daily note integration with automatic task logging
## ✨ Features **⏱️ Dual Timer Modes**
- **Pomodoro**: Configurable work sessions with automatic breaks
- **Stopwatch**: Free-form time tracking with estimate alerts
### 📋 Task Management **📊 Analytics & Reports**
- Create tasks with time estimates - View productivity metrics (tasks/day, hours/day, streaks)
- Organize tasks into customizable lists (Work, Personal, Learning, etc.) - Pie charts and bar graphs showing activity breakdown
- Add notes and details to tasks - Time tracking by list category
- Filter tasks by list, today's tasks, or completed items - Insights on most productive hours, days, and months
- Drag-and-drop task reordering
### ⏱️ Dual Timer Modes **🎨 Polish**
- Status bar timer, celebration messages, sound alerts
#### Pomodoro Timer - Keyboard shortcuts, dark mode support
- Configurable work sessions (default: 25 minutes) - Overdue task detection with visual indicators
- Short breaks (default: 5 minutes) - Works on desktop and mobile
- 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 ## 🚀 Installation
@@ -111,183 +67,45 @@ npm run build
cp main.js manifest.json styles.css /path/to/your/vault/.obsidian/plugins/immerse/ cp main.js manifest.json styles.css /path/to/your/vault/.obsidian/plugins/immerse/
``` ```
## 📖 Usage ## 📖 Quick Start
### Getting Started 1. Click ⚡ icon in ribbon or use command palette (`Ctrl/Cmd + P` → "Open Immerse Panel")
2. Add a task with "+ Add Task" (description, time estimate, list)
3. Start timer: ▶ for Pomodoro or ⏱ for stopwatch
4. Complete and enjoy the celebration!
1. **Open Immerse**: Click the ⚡ icon in the ribbon or use the command palette (`Ctrl/Cmd + P` → "Open Immerse Panel") ## ⚙️ Configuration
2. **Add a Task**: Click "+ Add Task" and fill in: All settings available in Settings → Immerse:
- Task description - Pomodoro durations (work: 25min, short break: 5min, long break: 15min)
- Time estimate - Default time estimates, sounds, celebrations
- List category - Daily note integration (auto-log completed tasks)
- Custom lists with names, emojis, and colors
3. **Start Focusing**: Click ▶ on any task to start a Pomodoro session, or ⏱ for stopwatch mode ## 🙏 Credits
4. **Complete Tasks**: Check off tasks when done and enjoy the celebration! Heavily inspired by [Blitzit](https://www.blitzit.app/) - a fantastic productivity app. Immerse brings that experience into Obsidian.
### 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 ## 🤝 Contributing
Contributions are welcome! Feel free to: Contributions welcome! Fork, create a feature branch, and open a PR.
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
**Dev Setup:**
```bash ```bash
# Clone the repo
git clone https://git.cribdev.com/crib/immerse.git git clone https://git.cribdev.com/crib/immerse.git
cd immerse cd immerse
# Install dependencies
npm install npm install
# Start development build (watches for changes)
npm run dev npm run dev
# Create symlink to your test vault
ln -s $(pwd) /path/to/vault/.obsidian/plugins/immerse
``` ```
## 📜 License ## 📜 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. MIT License - see [LICENSE](LICENSE) file.
## 🔗 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/)
--- ---
**Links:** [Repository](https://git.cribdev.com/crib/immerse) • [Issues](https://git.cribdev.com/crib/immerse/issues) • [Blitzit](https://www.blitzit.app/)
<p align="center"> <p align="center">
Made with ❤️ for the Obsidian community <em>Made with ❤️ for the Obsidian community • Inspired by Blitzit ⚡</em>
<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> </p>