I posted about Nautical a while back. Since then it has matured into a reliable recurrence layer for Taskwarrior, so this is a more complete walkthrough.

Nautical is a hook-based system that makes easy to answer this one question:

When I complete this task, when should the next one happen?

Taskwarrior remains the task database. Nautical adds recurrence logic through UDAs and hooks.

Compared with the recurrence RFC

There is a Taskwarrior recurrence RFC here:

https://djmitche.github.io/taskwarrior/rfcs/recurrence.html

The RFC proposes a cleaner native recurrence model with templates, generated instances, instance indexes, and rtype values like periodic and chained.

That would be a strong improvement for Taskwarrior itself.

Nautical goes further in a different direction. It adds calendar expressions, file-backed dates, explicit omitted dates, timelines, batch-safe deferred spawning, and duplicate protection for synced setups.

The model

Nautical has two recurrence engines:

• cp for period chains
• anchor for calendar positions

For anchors, the full model is:

(anchor union anchor_file) minus (omit union omit_file)

That separation is deliberate:

• anchor and anchor_file say when a task can happen
• omit and omit_file say when it must not happen

An algebraic expression like this would be possible:

(w:mon,wed,fri + y:apr) - y:04-28..05-05

But keeping inclusion and exclusion separate makes the system easier to read, validate, preview, and debug. It also matches real workflows better: schedules and blackout dates often come from different sources.

Chains: recurrence by period

Use cp when the next task is based on a duration.

Mow the lawn every 12 days, preserving the due hour:

task add "Mow the lawn" cp:12d

Take a vitamin every 8 hours, using exact completion time:

task add "Take vitamin" cp:8h

Periods under 24 hours use exact completion time. Longer day-based periods preserve the wall-clock routine.

Anchors: recurrence by calendar position

Use anchor when recurrence is about calendar slots.

task add "Workout" project:health anchor:"w:mon,wed,fri"
task add "Date night" project:personal anchor:"m:rand + w:sat"
task add "Anniversary" project:personal anchor:"y:04-12"

Anchors can be weekly, monthly, yearly, combined with +, or joined with |.

Examples:

w:mon,wed,fri              Mondays, Wednesdays, Fridays
m:1                        first day of each month
m:rand + w:sat             random Saturday in the month
y:04-12                    April 12 every year
w:tue,fri | y:05-05        Tuesdays, Fridays, or May 5

rand is deterministic for the chain, so the same logical chain does not keep changing its random date.

File-backed dates

Nautical can use files as recurrence sources.

Configure a trusted directory:

anchor_file_dir = "/home/user/.task/nautical_anchors"

Then use a file:

task add "Company event prep" anchor_file:"2026.csv@-1d@t=12:00,18:00"

The file can contain explicit dates, date ranges, or CSV data with a date column.

@-1d means one day before each file date. @t=12:00,18:00 creates two occurrences on each resulting date.

anchor and anchor_file can also work together:

task add "Hybrid schedule" \
  anchor:"w:tue,fri | y:05-05" \
  anchor_file:"2026.csv@-1d@t=12:00,18:00"

That means:

calendar expression dates union file dates

Omitting dates

Use omit for expression-based exclusions:

task add "Workout" anchor:"w:mon,wed,fri" omit:"w:wed"
task add "Workout" anchor:"w:mon,wed,fri" omit:"y:12-24..12-31"

Use omit_file for file-backed exclusions:

omit_file_dir = "/home/user/.task/nautical_omit"

task add "Date night" anchor:"m:rand + w:sat" omit_file:"2026.csv"

Omitted dates are skipped, not rolled forward or backward. Nautical keeps searching until it finds the next valid occurrence.

In completion timelines, omitted slots remain visible as skipped rows, so you can see what was bypassed.

Limits

Use chainMax to stop after a number of links:

task add "Short experiment" project:testing cp:1d chainMax:3 due:today

Use chainUntil to stop after a date:

task add "Anniversary prep" anchor:"y:04-12" chainUntil:2028-04-12 due:today+10h

These apply to chains and anchors.

Batch completion

Taskwarrior hooks run while Taskwarrior has its own locks. Nautical avoids fighting those locks by deferring spawn work to on-exit.

Nautical records spawn intents during on-modify, then drains them after Taskwarrior releases its lock. On interactive terminals it can show a progress bar during the drain.

Sync and duplicate protection

Nautical uses chain identity, stable child behavior, and equivalent-child checks to avoid duplicate next tasks across synced devices.

Another important detail: Nautical carries forward the task state available at completion time.

There is no hidden recurrence template that overwrites the next task with a separate canonical version. If you annotate or adjust the current task and then complete it, Nautical uses the completed task as the source for the next link.

In a synced setup, that means the next task reflects the data available to the device that performs the completion. If another device adds an annotation after completion has already happened, that later change cannot be carried into a child that was already spawned. Sync order still matters, but the rule is explicit: the completed task state is the source.

Visibility

Nautical tries to explain what it is doing.

Depending on display settings, add and completion feedback can show:

• the next spawned task
• the recurrence pattern
• natural-language explanation
• omitted rules
• file-backed sources
• timelines
• chain-ending information
• diagnostics with NAUTICAL_DIAG=1

The timeline is especially useful for anchors because it shows nearby future slots, skipped slots, and omitted slots.

What Nautical is not

Nautical is not a separate task manager. It does not replace Taskwarrior.

It is a hook layer that makes Taskwarrior recurrence much more capable while keeping generated tasks as normal Taskwarrior tasks.

It may be overkill if all you need is a simple daily or weekly repeat. It is meant for people who want Taskwarrior as a serious task database with an advanced recurrence engine.

The only serious downside I have found so far is that it refuses to spawn tasks after 9999-12-31, so long-term planning still has some unresolved limitations. :)

Links

Repository:

https://github.com/catanadj/taskwarrior-nautical

The manual has the full syntax, UDA setup, config options, and examples.

I would be interested in feedback from other Taskwarrior users, especially around recurrence edge cases, sync behavior, and whether the syntax feels natural in real workflows.

And as always, any support would be greatly appreciated.