Time Blocks

A drag-and-drop weekly planner for Obsidian. Turn your vault tasks into a visual schedule — drag any task onto the calendar grid, resize it to set duration, and optionally push everything to Google Calendar with two-way sync.

Why Time Blocks?

Most task plugins show you what to do. Time Blocks shows you when.

• No YAML editing. Drag-and-drop from your task backlog straight onto the calendar.
• Works with tasks you already have. Reads the Obsidian Tasks emoji format — no migration needed.
• True two-way Google Calendar sync with conflict resolution — not just a read-only ICS overlay.
• Day view in the right sidebar for focused single-day planning.
• AI-agent friendly. An AGENTS.md guide lets AI tools read your backlog and schedule blocks directly via data.json.

Features

Weekly calendar grid

A 7-day, hour-by-hour canvas with configurable workday bounds (default 8 am–6 pm), sticky day headers, and a live current-time indicator.

• Drag any task from the backlog and drop it on a time slot — the block snaps to 15-minute increments.
• Drag a block to move it to a different day or time.
• Drag the bottom edge of a block to resize it.
• Click × to remove a block from the schedule.

Task backlog sidebar

Automatically scans your entire vault for tasks written in Obsidian Tasks emoji format (- [ ] task text 📅 2025-07-15 ⏫) and displays them in a resizable sidebar. Tasks already scheduled for the current week are hidden.

• Sorted by priority then due date.
• Tag chips — click to filter the backlog to a specific tag.
• Overdue tasks pinned to the top with a red indicator and a one-click Clear action.
• Filter by text, tag, or completion status directly in the sidebar (no settings round-trip).

Block resize

Day view

A single-day sidebar view for focused planning. Navigate between days with arrow buttons. Supports the same drag-and-drop, resize, completion toggle, and delete actions as the weekly grid.

Google Calendar integration

Two layers of calendar integration:

1. ICS overlay (read-only) — Paste one or more private ICS feed URLs from Google Calendar. Events appear as read-only blocks on the grid, colour-coded separately from task blocks.
2. Two-way sync (OAuth 2.0) — Push scheduled blocks to Google Calendar and pull remote changes back. Includes conflict resolution, rate-limit handling, and writable-calendar permissions.

Custom query backlog

Switch from "show all" to a custom multi-line query using the Obsidian Tasks query syntax. 16 rule types: status, due/path/tag/priority filters, sort, and limit.

not done
tag includes #work
priority above low
due before 2025-09-01
sort by priority
limit to 20 tasks

Quick start

1. Install — see Installation below.
2. Open the view — click the 📅 calendar icon in the ribbon, or run the command Open weekly time-block view.
3. Browse your backlog — the left sidebar lists all incomplete tasks from your vault.
4. Schedule a task — drag a task from the backlog and drop it on a day/time slot. A block is created at the default duration (30 min, configurable).
5. Adjust blocks — drag to move, drag bottom edge to resize, click × to remove.
6. Navigate weeks — use the ‹ / › arrows in the header, or click Today to return to the current week.

Installation

This plugin is currently in pre-release. Choose the option that fits you:

Option A — BRAT (easiest, recommended)

1. Install the BRAT community plugin.
2. Open Settings → BRAT → Add beta plugin.
3. Enter: https://github.com/jonmccon/obsidian-time-blocks
4. Click Add plugin, then enable Time Blocks in Settings → Community plugins.

BRAT keeps the plugin updated automatically when new releases are published.

Option B — Download a release

1. Go to the Releases page and download the latest main.js, styles.css, and manifest.json.
2. Copy them into your vault:

   <vault>/.obsidian/plugins/time-blocks/
   

3. Enable Time Blocks in Settings → Community plugins.

Option C — Build from source

git clone https://github.com/jonmccon/obsidian-time-blocks.git
cd obsidian-time-blocks
npm install
npm run build
# Copy main.js, styles.css, manifest.json → <vault>/.obsidian/plugins/time-blocks/

Settings reference

Custom query syntax

One filter rule per line. Rules are ANDed together. Lines starting with # are comments.

Two-way Google Calendar sync

Two-way sync pushes your scheduled blocks to Google Calendar and pulls remote changes back. It uses OAuth 2.0 with PKCE — no client secret is required.

Setup

1. Enable Two-way sync in Settings → Time Blocks.
2. Create a free OAuth client ID in the Google Cloud Console:
   • Enable the Google Calendar API.
   • Create an OAuth client ID (Desktop app).
   • Add http://127.0.0.1 as an Authorized redirect URI.
3. Paste the client ID into settings and click Authorize.
4. Complete the Google sign-in flow in your browser.
5. Click ⇄ sync in the week header, or run Sync calendar events.

Security note

⚠️ data.json stores your live OAuth refresh token. Do not commit .obsidian/plugins/time-blocks/data.json to a public repository. To revoke access, click Sign out in settings or visit Google Account permissions.

Conflict resolution

Known issues

• Recurring calendar events — The ICS parser does not expand RRULE recurrence rules; recurring events only appear for their original date.
• ICS timezone offsets — Events with TZID parameters are treated as local time rather than converted from the specified timezone.
• Custom query unknown rules — Unrecognised query lines are silently skipped. Check spelling if a filter doesn't work.

Live demo

The GitHub Pages preview at jonmccon.github.io/obsidian-time-blocks lets you try the full interface — drag-and-drop, week navigation, task search — without installing anything. No vault or Obsidian required.

Vault task format

Tasks must follow the Obsidian Tasks emoji format:

- [ ] Task title
- [ ] Task with due date 📅 2025-07-15
- [ ] High-priority task ⏫ 📅 2025-07-10
- [x] Completed task
- [ ] Tagged task #work #q3
- [ ] Scheduled to work on it ⏰ 2025-07-11

Priority emojis (highest → lowest): 🔺 ⏫ 🔼 🔽 ⏬

Agent / automation support

Time Blocks ships an AGENTS.md guide for AI tools and automation scripts. It documents:

• The full ScheduledBlock data model
• How to read and write data.json directly to schedule tasks
• Batch scheduling recipes in Python and TypeScript

This means tools like Hermes, Claude, or custom scripts can read your backlog and populate your weekly schedule programmatically.

Development

npm install          # install dependencies
npm run build        # type-check + bundle
npm run dev          # watch mode
npm run lint         # ESLint
npm test             # Vitest unit tests (173+ tests, no Obsidian install needed)
npm run test:watch   # test watch mode

Tests cover: weekUtils, icsParser, queryFilter, taskQuery, gcal/*.

See CHANGELOG.md for the full version history.

License

MIT © Jonny McConnell