Skip to main content

A Taskwarrior scheduler for people who want a realistic plan, not a manual to-do list. It turns tasks, working hours, and calendar blocks into an actionable schedule — then keeps due dates visible.

Use it if you want to:

  • stop guessing what to do next
  • fit tasks into real availability
  • be sure your long-time plan won't go overdue
  • keep Taskwarrior as the source of truth
  • handle your time across multiple tasks carried on by LLMs

Features

  • ✨ Auto-schedule tasks from working hours + calendar blocks
  • 🧠 Schedule agent-assisted tasks alongside your own, based on how much supervision they need
  • ⏱️ Consider urgency, due dates, and dependencies
  • 🧪 Persisted dry-run previews for reports and timelines
  • ↩️ Undo the latest schedule update
  • 🧠 Auto-adjust urgency when deadlines cannot be met
  • 🔄 Force-refresh iCal calendars
  • 📊 Custom reports for planned and unplanned tasks
  • 🗓️ Project-grouped timelines with day, week, and month views
  • 🎨 Report styling with emoji and extra attributes
  • 🗓️ Block time with iCal or Google Calendar, including all-day events

Dry-run schedule and report

Daily timeline

How it works

Taskcheck reads your pending and waiting tasks, estimates when each one can be worked on, and writes back a schedule. For tasks tagged +agent, it treats estimated as the agent's work time and agent_weight as the percentage of that time needing your attention. It respects:

  • your working hours
  • task duration estimates
  • calendar events and vacations from iCal / Google Calendar
  • task urgency and due dates

It updates Taskwarrior with:

  • scheduled → when work should start
  • completion_date → when work is expected to finish
  • a warning when a task will miss its due date

Taskcheck does not allocate work before a task's wait date. It can allocate work on that date because it plans whole days, not exact start times. Reports and timelines ignore saved work dates before wait, even when you change wait after scheduling. If no work fits within the planning period, the next scheduling run clears the task's old schedule fields.

Quick start

  1. pipx install taskcheck
  2. taskcheck --install ← setup only: registers required Taskwarrior settings inyour taskwarrior config file and offers to create the config file; it does not schedule tasks.
  3. edit ~/.config/task/taskcheck.toml (see Reference)
  4. tune your tasks: add estimated, time_map, agent_weight UDAs and the +agent tag (time_map and agent_weight may use the default value defined in the Taskwarrior settings)
  5. taskcheck --schedule
  6. taskcheck --undo restores the scheduling fields changed by the latest run

Required UDAs

  • estimated: expected duration in hours
  • time_map: which working-hour profile applies to the task, for example work or weekend
  • agent_weight: required for +agent tasks; the percentage (0–100) of agent work time that needs your attention. It defaults to 25 when using taskcheck --install.

Example:

[time_maps.work]
monday = [[9, 12.30], [14, 17]]
tuesday = [[9, 12.30], [14, 17]]

Agent tasks and mixed blocks

Mark a task +agent when a computer helper will do the work, and set agent_weight to show what percentage of its work time needs your attention. For example, 10 means you spend about 10 minutes interacting with the agent for each hour the agent works. Taskcheck can plan several agent jobs at once, fill the time left with your own tasks, and respect waiting dates and dependencies.

task add "Implement API" +agent estimated:5h agent_weight:10
task add "Review results" estimated:1h

Run taskcheck --install to register the agent_weight Taskwarrior UDA.

Reports and timelines

  • taskcheck -r today → tasks planned for today
  • taskcheck -r 1w → tasks planned for the next week
  • taskcheck --timeline 1w → automatic day/week/month timeline for the next week
  • taskcheck --timeline eom --zoom week → weekly timeline through month end

Create a preview with taskcheck --schedule --dry-run. It does not update Taskwarrior; instead, it saves the generated schedule to the Taskwarrior data directory. Reuse it with taskcheck --report today --dry-run or taskcheck --timeline 1w --dry-run.

Timeline rows follow dotted project levels such as work.client. Without --zoom, the most detailed view that fits the terminal width is selected: day, then week, then month. The track uses ▶ for a start, ━ for work, ◀ for an end, and ◆ for a deadline. Thin, heavy, and double rules separate days, weeks, and months. Project colors are deterministic and adapt to light or dark terminals through OSC 11, with config and environment fallbacks.

Reference

📚 Full reference: REFERENCE.md

In short:

  • taskcheck --install is interactive
  • it installs required Taskwarrior settings if you confirm the first prompt
  • it installs optional urgency/report tuning if you confirm the second prompt
  • it can also create the default config file if you confirm the third prompt
  • scheduling happens with taskcheck --schedule
  • all flags/config keys/settings are documented in REFERENCE.md

They say it's an AI

The algorithm simulates a workday one chunk at a time.

For each day starting from today, it sorts tasks by urgency and picks the most urgent task that fits the available time. It assigns a small block of work, then recomputes urgency exactly as Taskwarrior would on that day. If urgency changes, the next task choice can change too.

For today, taskcheck skips past hours.

The default work chunk is 2 hours (or less if the task is shorter); you can tune it with the Taskwarrior UDA min_block.

Before writing a schedule, taskcheck backs up the affected tasks' scheduled, completion_date, and scheduling fields under the Taskwarrior data directory. taskcheck --undo restores and consumes the newest backup. The [scheduler] option n_undos controls retention and defaults to 1; set it to 0 to disable backups.

If a task would finish after its due date, taskcheck retries with a total-urgency override. Each retry moves the task immediately above the task with the smallest greater urgency by adding urgency_epsilon (default: 0.1). At rank 1, it adds epsilon for up to max_top_urgency_rounds retries (default: 10), then tries once at urgency 1000. If the task is still late, taskcheck stops raising it and optimizes the other overdue tasks.

Tips and Tricks

  • You can exclude a task from being scheduled by removing the time_map or estimated attributes.
  • You can see tasks that you can execute now with the task ready report.

See the reference section above for flags, config keys, and installed Taskwarrior settings.

Metadata

Release files for taskcheck 1.6.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for taskcheck 1.6.1
File Size Uploaded Provenance Actions
taskcheck-1.6.1.tar.gz 62.4 kB Without provenance Details for taskcheck-1.6.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for taskcheck 1.6.1
File Interpreter ABI Platform Actions
taskcheck-1.6.1-py3-none-any.whl Python 3 none any Details for taskcheck-1.6.1-py3-none-any.whl

Total release size: 95.0 kB

Release files / taskcheck-1.6.1.tar.gz

Download URL taskcheck-1.6.1.tar.gz
Size 62.4 kB
Tags Source
SHA-256 checksum
How to use checksums
1f7d0512b95f511ff8c10c7220a9c88462632e6fc754906d14f88f47d5597ece
BLAKE2b-256 checksum
How to use checksums
40a777c17611ad56eb9d67c3c204a618716fe772ee51583bc1ac6b96ef43e709
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / taskcheck-1.6.1-py3-none-any.whl

Download URL taskcheck-1.6.1-py3-none-any.whl
Size 32.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
77f20556d056866ca45a9a1c47388355741bd373a1e1bbbd5bfc2017c67f39fd
BLAKE2b-256 checksum
How to use checksums
35b14964d3b716fa7fbe059c7aeb1f0d5592440abd078790508da4dea5b66649
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for taskcheck 1.6.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.6.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page