Harvest your time, grain by grain
A Pomodoro timer plugin for Obsidian that integrates deeply with your notes. Track time on tasks, log how you feel, and gain insights into your productivity patterns—all within your vault.
Unlike standalone timer apps, Timegrain lives inside Obsidian and connects directly to your notes:
- Your tasks are your notes — No separate task database. Any markdown file can be a task.
- Sessions are searchable — Every work session is saved as a markdown file you can query, link, and review.
- Energy awareness — Track how you feel after each session to discover your peak productivity hours.
- Visual history — See your work patterns on a calendar heat map with timeline visualization.
- Start/pause/resume/cancel/complete timer sessions
- Pomodoro tracking with configurable duration (default 25 min)
- Audio notification on pomodoro completion
- Status bar integration showing current task and time
- Automatic session recovery on startup (never lose a session)
- Create tasks with title, status, estimation, expected energy, and category
- Plan your day: Batch-select tasks to move to "Today" status
- Fuzzy search to quickly find and start any task
- Auto-rollover of stale "Today" tasks to "This Week"
- Supports multiple task statuses: today, in progress, this week, this month, backlog, done, and more
- Rate how you feel (5 levels) and perceived effort (0-10) after each session
- Tracks hour-of-day and day-of-week patterns
- Analyzes your peak productivity times
- Helps you schedule demanding work when you're at your best
- Interactive calendar with activity heat map
- Timeline visualization of work sessions
- Color-coded by task for quick pattern recognition
- Navigate to any date to review your history
- Track daily goals and streaks
- Open Obsidian Settings
- Go to Community plugins and disable Restricted mode
- Click Browse and search for "Timegrain"
- Click Install, then Enable
- Download
main.js,manifest.json, andstyles.cssfrom the latest release - Create folder:
<YourVault>/.obsidian/plugins/timegrain/ - Copy the downloaded files into that folder
- Restart Obsidian
- Enable "Timegrain" in Settings → Community plugins
Run the command Timegrain: Create new task (Ctrl/Cmd + P) and fill in:
- Title: What you're working on
- Status: Set to "today" to work on it now
- Estimation: How many pomodoros you think it'll take
- Expected Energy: How demanding is this task? (Any/Low/Normal/High)
This creates a markdown file like:
---
title: Write documentation
status: today
estimation: 3
expected energy: 3
category: writing
creation date: 2024-01-15 10:00
---
# Write documentation
Notes about this task...- Run Timegrain: Open timer panel to see the timer in your sidebar
- Click on a task to start, or run Timegrain: Start timer with current note
- The timer begins tracking your session
When you're done (or want a break):
- Click Complete or run Timegrain: Complete timer session
- Rate how you feel and your perceived effort
- Your session is saved automatically
Run Timegrain: Open daily log to see:
- Calendar heat map of your activity
- Timeline of today's sessions
- Which tasks you worked on
Access via Command Palette (Ctrl/Cmd + P):
| Command | Description |
|---|---|
| Start timer with current note | Start timing the currently active file |
| Start timer: Select task... | Fuzzy search to pick any task |
| Pause/resume timer | Toggle timer pause state |
| Complete timer session | Finish session and log how you feel |
| Cancel timer | Cancel without completing (abandons session) |
| Open timer panel | Show timer in sidebar |
| Open daily log | Open calendar and timeline view |
| Create new task | Open task creation form |
| Plan your day | Batch-select tasks for today |
Timegrain stores everything as plain markdown with YAML frontmatter. Your data is always accessible, searchable, and portable.
Any markdown file matching */tasks/*.md is recognized as a task. Example:
---
title: Implement user authentication
status: in progress
estimation: 5
expected energy: 5
category: backend
scope: v2.0
tags:
- security
- priority
creation date: 2024-01-15 10:00
modification date: 2024-01-16 14:30
due to: 2024-01-20
depends on: "[[Setup database]]"
---Status options:
today— Planned for todayin progress— Currently working onthis week— Planned for this weekthis month— Planned for this monthbacklog— Future workdone— Completedarchived— No longer relevanton hold— Pausedneeds review— Awaiting review
Sessions are stored in timer_sessions/ as markdown files:
---
started: 2024-01-15T10:00:00
ended: 2024-01-15T10:25:00
task: "[[Implement user authentication]]"
feeling: strong
perceived_effort: 4
hour_of_day: 10
day_of_week: monday
status: completed
---Each session links to its task, making it easy to see all sessions for a given task using Obsidian's backlinks.
Go to Settings → Timegrain to customize:
| Setting | Description | Default |
|---|---|---|
| Timer sessions directory | Where session files are saved | timer_sessions |
| Default task directory | Where new tasks are created | tasks |
| Setting | Description | Default |
|---|---|---|
| Cycle duration | Pomodoro length in minutes | 25 |
| Play sound | Audio notification on pomodoro completion | true |
| Daily goal | Target pomodoros per day | 8 |
| Setting | Description | Default |
|---|---|---|
| Show status bar | Display timer in Obsidian status bar | true |
| Status bar click action | What happens when clicking status bar | open-timer |
| Setting | Description | Default |
|---|---|---|
| Rollover stale tasks | Auto-move old "Today" tasks to "This Week" | true |
Create a template file and use Obsidian's Templates plugin to quickly create new tasks with consistent frontmatter.
Since sessions are markdown files with dates, you can query them in your daily notes using Dataview:
TABLE started, task, feeling, perceived_effort
FROM "timer_sessions"
WHERE file.day = this.file.day
SORT started ASC
Set up hotkeys in Settings → Hotkeys for quick access:
Ctrl+Shift+S— Start/select taskCtrl+Shift+P— Pause/resumeCtrl+Shift+C— Complete session
Use a consistent naming pattern for tasks to make searching easier:
[PROJECT] Task nameCategory - Task name
All data is stored in your vault as plain markdown files:
- Tasks: Any file matching
*/tasks/*.md - Sessions: Files in
timer_sessions/folder
Yes! They're just markdown files. Edit the YAML frontmatter or note content as needed.
Timegrain saves timer state every 5 seconds. On next startup, you'll be prompted to resume or abandon the unfinished session.
Yes, Timegrain is fully compatible with Obsidian Mobile.
Yes, as long as your files are in a */tasks/*.md path and have a status field in frontmatter, Timegrain will recognize them.
Contributions are welcome! Here's how you can help:
- Report bugs — Open an issue with steps to reproduce
- Suggest features — Open an issue describing your idea
- Submit PRs — Fork, create a branch, make changes, submit a pull request
# Clone the repo
git clone https://github.com/linconvidal/timegrain-obsidian-plugin.git
cd timegrain-obsidian-plugin
# Install dependencies
npm install
# Development with watch mode
npm run dev
# Run tests
npm test
# Production build
npm run buildsrc/
├── main.ts # Plugin entry point
├── types.ts # TypeScript interfaces
├── components/ # React UI components
├── hooks/ # React hooks
├── modals/ # Obsidian modals
├── services/ # Timer service
├── data/ # Repositories
└── utils/ # Utilities
tests/ # Vitest tests
- Issues: GitHub Issues
- Discussions: GitHub Discussions
If you find Timegrain useful, consider:
- Starring the repo on GitHub
- Sharing it with others
- Contributing improvements
MIT © Lincon Vidal
Harvest your time, grain by grain.