README file from
GithubDepthinker Timer
A Pomodoro and stopwatch timer for Obsidian with a calendar-style focus log that lives inside your vault — so disabling or uninstalling the plugin never erases your history, and your data syncs across devices with whatever sync method you already use.
Works on desktop and mobile (Android / iOS).
Features
- Pomodoro timer with custom focus / short-break / long-break lengths and an adjustable long-break interval.
- Stopwatch mode for open-ended focus sessions.
- Auto-cycle that rolls from focus → break → focus automatically (toggleable).
- Calendar view with a monthly heatmap of focus time, daily totals, and a streak counter.
- Edit / delete / manually add any session from the calendar.
- Finish cues: a short chime, vibration, and an in-app notice. All optional.
- Accurate timing on mobile: elapsed time is derived from wall-clock timestamps, not tick counts, so backgrounding or locking the screen never slows the clock.
- Crash recovery: an in-progress timer is restored when Obsidian reopens.
- Bilingual UI: follows Obsidian's interface language (English / 中文).
Installation
From the community browser (once published)
- In Obsidian, open Settings → Community plugins and turn off Restricted mode if needed.
- Browse and search for Depthinker Timer, then click Install and Enable.
From a release (manual)
Download main.js, manifest.json, and styles.css from the latest GitHub release and place
them in <your vault>/.obsidian/plugins/depthinker-timer/. Then enable the plugin.
Build from source
npm install
npm run build # outputs dist/main.js, manifest.json, styles.css
npm run deploy # copies the build into a local vault for testing
Settings
| Setting | What it does |
|---|---|
| Focus length | Minutes per Pomodoro. |
| Short break / Long break | Rest minutes after a Pomodoro / after a full cycle. |
| Long break after | Number of Pomodoros before a long break. |
| Auto cycle | Start the next phase automatically when one ends. |
| Default mode | Timer shown when the panel opens (Pomodoro or Stopwatch). |
| Minimum session length | Shorter runs are discarded instead of stored (0 = keep everything). |
| Daily goal | Minutes; drives the calendar colour scale and the daily hint. |
| Sound / Vibrate / Notice on finish | End-of-phase cues. |
| Data folder | Vault folder for the daily log notes. |
| Week starts on | Sunday or Monday. |
Where your data lives
Every day's focus log is written as a plain Markdown note:
<Data folder>/<Year>/<YYYY-MM-DD>.md
Example: FocusLog/2026/2026-08-17.md. The note holds a frontmatter block plus a json code
block listing that day's sessions. Because these are ordinary vault notes:
- They survive disabling or uninstalling the plugin.
- They sync with your vault through Obsidian Sync, iCloud, Git, etc.
- They're protected by Obsidian's file history and can be opened or edited by hand.
To keep these notes out of global search and the graph, add -path:FocusLog (or your chosen
folder name) to a search filter or to a folder exclusion.
To erase your history entirely, delete the data folder.
Known limitations
- Cross-device edit conflicts. If the same session is edited on two devices before they
sync, the later write wins (sessions are keyed by id; the newer
updatedAtwins). Different sessions written on different devices merge cleanly. Use Obsidian's version history to recover an overwritten edit. - Mobile background audio. iOS and some Android setups mute or block audio while the app is in the background; the in-app notice and vibration still fire where supported. The timer itself keeps accurate time regardless.
- Cross-midnight sessions. A session is filed under the calendar day its start time belongs to, even if it runs past midnight.
Development
npm install
npm run dev # watch build that writes straight into a vault plugin folder
npm run check # type-check only
npm run build # production bundle to dist/
The plugin targets Obsidian 1.7.2+ and sets isDesktopOnly: false.