Metadata-Version: 2.4
Name: taskcheck
Version: 1.6.0
Summary: Automatic scheduler for taskwarrior
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: appdirs>=1.4.4
Requires-Dist: google-api-python-client>=2.198.0
Requires-Dist: google-auth>=2.56.2
Requires-Dist: google-auth-oauthlib>=1.2.2
Requires-Dist: icalendar>=6.0.1
Requires-Dist: random-unicode-emoji>=2.8
Requires-Dist: requests>=2.32.3
Requires-Dist: rich>=13.9.4

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

> [!IMPORTANT]
> This repo is actively maintained again

## 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](docs/images/dry-run-report.png)

![Daily timeline](docs/images/timeline-day.png)

## 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

## 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](#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:

```toml
[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.

```bash
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](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.
