From 264441f83b6537ecb9ccc2562d07548766de9956 Mon Sep 17 00:00:00 2001 From: crib Date: Tue, 25 Nov 2025 17:27:27 +0100 Subject: [PATCH] Updated README.md --- README.md | 260 ++++++++---------------------------------------------- 1 file changed, 39 insertions(+), 221 deletions(-) diff --git a/README.md b/README.md index 0512604..77bb2eb 100644 --- a/README.md +++ b/README.md @@ -8,75 +8,31 @@ A powerful task management and focus timer plugin for [Obsidian](https://obsidia ## 🎯 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 -- **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 +**📋 Task Management** +- Create tasks with time estimates and organize into customizable lists +- Filter by list, status, or date +- Schedule tasks with reminders (5/10/15/30/60 min before due) +- 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 -- 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 +**📊 Analytics & Reports** +- View productivity metrics (tasks/day, hours/day, streaks) +- Pie charts and bar graphs showing activity breakdown +- Time tracking by list category +- Insights on most productive hours, days, and months -### ⏱️ 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 +**🎨 Polish** +- Status bar timer, celebration messages, sound alerts +- Keyboard shortcuts, dark mode support +- Overdue task detection with visual indicators +- Works on desktop and mobile ## 🚀 Installation @@ -111,183 +67,45 @@ npm run build 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: - - Task description - - Time estimate - - List category +All settings available in Settings → Immerse: +- Pomodoro durations (work: 25min, short break: 5min, long break: 15min) +- Default time estimates, sounds, celebrations +- 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! - -### 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/)!** +Heavily inspired by [Blitzit](https://www.blitzit.app/) - a fantastic productivity app. Immerse brings that experience into Obsidian. ## 🤝 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 +Contributions welcome! Fork, create a feature branch, and open a PR. +**Dev 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/) +MIT License - see [LICENSE](LICENSE) file. --- +**Links:** [Repository](https://git.cribdev.com/crib/immerse) • [Issues](https://git.cribdev.com/crib/immerse/issues) • [Blitzit](https://www.blitzit.app/) +

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

- ✨ Vibe coded with assistance from Claude.ai + Made with ❤️ for the Obsidian community • Inspired by Blitzit ⚡