taskgun 0.8.1

A rusty gun for our taskwarrior - bulk task generation and smart scheduling
taskgun-0.8.1 is not a library.

taskgun — A rusty gun for our taskwarrior

A rusty gun for our taskwarrior - bulk task generation, smart scheduling, and deadline-driven productivity.

Why do you need taskgun?

Ever found a YouTube lecture series you want to complete but never quite finish? Started reading a technical book but lost momentum halfway through? The problem is simple: no deadlines.

Large sequential projects need structure and accountability. taskgun lets you break down big goals into smaller tasks with automatic deadlines, creating the external pressure you need to maintain momentum.

Real-world Examples

1. YouTube Lecture Series — 10 lectures, one per day

You discover a 10-part lecture series on Machine Learning. Schedule one lecture per day starting in 2 days:

taskgun create "ML Course" -p 10 -u Lecture --offset 2d --interval 1d

Creates:

  • Lecture 1 (due in 2 days)
  • Lecture 2 (due in 3 days)
  • Lecture 3 (due in 4 days)
  • ... and so on

2. Technical Book — 12 chapters, one per week

Reading "Introduction to Algorithms" with 12 chapters. Schedule one chapter per week starting next week:

taskgun create CLRS -p 12 -u Chapter --offset 7d --interval 7d --skip weekend

Creates:

  • Chapter 1 (due in 7 days, skips weekends)
  • Chapter 2 (due in 14 days, skips weekends)
  • Chapter 3 (due in 21 days, skips weekends)
  • ... completing in 12 weeks

3. Book with Large Chapters — Breaking down into sections

Reading "Design Patterns" with 3 chapters, but each chapter is too long. Chapter 1 has 3 sections, Chapter 2 has 4 sections, Chapter 3 has 2 sections. Schedule one section every 3 days:

taskgun create "Design Patterns" -p 3,4,2 -u Section --offset 3d --interval 3d

Creates:

  • Section 1.1 (due in 3 days)
  • Section 1.2 (due in 6 days)
  • Section 1.3 (due in 9 days)
  • Section 2.1 (due in 12 days)
  • Section 2.2 (due in 15 days)
  • Section 2.3 (due in 18 days)
  • Section 2.4 (due in 21 days)
  • Section 3.1 (due in 24 days)
  • Section 3.2 (due in 27 days)

4. Quick Revision — 30 lectures in 2 days

You have an exam in 2 days and need to revise 30 lectures quickly. Schedule one lecture every 2 hours, skipping bedtime:

taskgun create "Exam Prep" -p 30 -u Lecture --offset 2h --interval 2h --skip bedtime

Creates 30 lectures scheduled every 2 hours starting in 2 hours, automatically skipping 22:00-06:00 (bedtime). With ~16 waking hours per day, you'll complete all 30 lectures in approximately 2 days.

5. Rapid Practice — 20 exercises with minute-level precision

You want to practice 20 short coding exercises, dedicating 30 minutes to each, with 15-minute breaks:

taskgun create "Coding Practice" -p 20 -u Exercise --offset 30m --interval 45min --skip bedtime

Creates 20 exercises scheduled every 45 minutes (30 min work + 15 min break), starting in 30 minutes, automatically skipping bedtime hours.

Result: What seemed like an overwhelming task is now a structured schedule you can follow.

Features

  • Link management — Add tasks with URLs/links from clipboard and open them in your browser
  • Bulk task generation — Create numbered task series with a single command
  • Instant keyword search — Search tasks by typing taskgun keyword (searches projects and descriptions)
  • Flexible skip system — Skip time windows and days using presets or custom rules
  • Smart scheduling — Day-based, hour-based, or minute-based scheduling with mixed unit support
  • Hierarchical tasks — Support for subsections (e.g., Part 1.1, 1.2, 2.1)
  • Configurable presets — Define custom skip windows in .taskrc
  • Zero runtime dependencies — Only requires Taskwarrior itself

Installation

From crates.io

cargo install taskgun

From source

git clone https://github.com/hamzamohdzubair/taskgun
cd taskgun
cargo install --path .

Requirements

  • Taskwarrior 2.6.0 or later
  • Rust 1.70+ (for building from source)

Configure taskgun (Optional)

taskgun comes with built-in presets (bedtime and weekend), but you can customize them or add your own in ~/.taskrc:

# Add this to your ~/.taskrc file

# === taskgun Configuration ===

# Customize bedtime hours (default: 2200-0600)
taskgun.skip.bedtime=2100-0500

# Customize weekend (default: Saturday, Sunday)
taskgun.skip.weekend=sat,sun

# Add custom skip windows
taskgun.skip.lunch=1200-1400
taskgun.skip.meetings=0900-1000,1400-1500
taskgun.skip.longweekend=fri,sat,sun

After adding these to your .taskrc, use them with the --skip option:

taskgun create Project --offset 2h --interval 3h --skip lunch --skip bedtime

Note: If you don't add anything to .taskrc, the built-in defaults work perfectly:

  • bedtime: 22:00-06:00
  • weekend: Saturday and Sunday

Usage

Add task with link from clipboard

Quickly add a task and attach a URL from your clipboard:

# Copy a URL to clipboard first, then:
taskgun add -l 'Read this article' due:tomorrow +reading

# Add a task without a link
taskgun add 'Buy groceries' due:today +shopping

# Add with multiple taskwarrior attributes
taskgun add 'Fix login bug' project:webapp due:10d priority:H +urgent

The -l (or --link) flag reads your clipboard content and attaches it as a link UDA to the task. It also prepends a 🔗 emoji to the task description for easy visual identification in your task list. Later, open the link in your browser:

# If the task above was created with ID 45:
taskgun open 45

This opens the link in your default browser.

Keyword search

Search for tasks by keyword — searches in both project names and descriptions:

# Case-insensitive search (default)
taskgun search learning
taskgun search VIDEO          # Finds "Video 1", "Video 2", etc.

# Search by project name
taskgun search "Deep Learning"

# Shorthand syntax (same as above)
taskgun learning
taskgun "Deep Learning"

Regex search

Use the -r or --regex flag for case-sensitive regex search:

# Find tasks matching regex pattern
taskgun search 'sec [0-9]' -r
taskgun search 'lec [0-9]+' --regex

# Match specific chapters/sections
taskgun search 'Video [12]' -r         # Only Video 1 and Video 2

# Shorthand syntax also works
taskgun 'sec [0-9]' -r

Note: Regex mode is case-sensitive by default. Use standard regex patterns supported by Taskwarrior.

Basic task generation

Create 5 tasks without due dates:

taskgun create "Deep Learning" -p 5

Creates:

  • Part 1
  • Part 2
  • Part 3
  • Part 4
  • Part 5

Day-based scheduling

Create 5 tasks with the first due in 5 days, then every 7 days:

taskgun create "Deep Learning" -p 5 --offset 5d --interval 7d

Creates tasks due on:

  • today+5d
  • today+12d
  • today+19d
  • today+26d
  • today+33d

Hour-based scheduling

Create 5 tasks with the first due in 2 hours, then every 6 hours:

taskgun create "Deep Learning" -p 5 --offset 2h --interval 6h

Minute-based scheduling

Create 10 tasks with the first due in 30 minutes, then every 45 minutes:

taskgun create "Practice" -p 10 --offset 30m --interval 45min

Both m and min suffixes are supported for minutes.

Mixed unit scheduling

Mix any time units — taskgun automatically handles the conversion:

# Offset in hours, interval in minutes
taskgun create "Sprint Tasks" -p 10 --offset 2h --interval 30m

# Offset in days, interval in hours
taskgun create "Daily Reviews" -p 10 --offset 1d --interval 6h

# Any combination works!
taskgun create "Mixed" -p 5 --offset 3d --interval 90min

Skip windows (bedtime, weekends, custom)

Skip specific time windows or days using the --skip option (can be used multiple times):

# Skip bedtime (22:00-06:00 by default)
taskgun create "Deep Learning" -p 5 --offset 2h --interval 6h --skip bedtime

# Skip weekends (Saturday and Sunday)
taskgun create "Deep Learning" -p 5 --offset 1d --interval 1d --skip weekend

# Skip custom time range
taskgun create "Deep Learning" -p 5 --offset 2h --interval 3h --skip 2100-0600

# Skip specific days
taskgun create "Deep Learning" -p 5 --offset 1d --interval 1d --skip fri,sat,sun

# Combine multiple skip rules
taskgun create "Deep Learning" -p 5 --offset 2h --interval 4h --skip bedtime --skip weekend

Skip behavior:

  • Tasks landing in skip windows are pushed forward to the next valid time
  • In hour/minute mode, subsequent tasks chain from the pushed time (maintains intervals)
  • In day mode, each task is calculated independently from the base time

Built-in presets:

  • bedtime: 22:00-06:00 (nighttime hours)
  • weekend: Saturday and Sunday

Hierarchical tasks with subsections

Create tasks with subsections (2 sections in chapter 1, 3 in chapter 2, 1 in chapter 3):

taskgun create "Deep Learning" -p 2,3,1 --offset 5d --interval 7d

Creates:

  • Part 1.1 (today+5d)
  • Part 1.2 (today+12d)
  • Part 2.1 (today+19d)
  • Part 2.2 (today+26d)
  • Part 2.3 (today+33d)
  • Part 3.1 (today+40d)

Custom unit names

Use a different prefix instead of Part:

taskgun create "Deep Learning" -p 2,3,2 -u Lecture --offset 3d --interval 4d

Creates:

  • Lecture 1.1, Lecture 1.2, Lecture 2.1, etc.

Custom skip windows in .taskrc

Define your own skip windows in ~/.taskrc:

# Define a lunch break
taskgun.skip.lunch=1200-1400

# Define a long weekend
taskgun.skip.longweekend=fri,sat,sun

# Override the bedtime preset
taskgun.skip.bedtime=2100-0500

Then use them:

taskgun create "Deep Learning" --offset 2h --interval 3h --skip lunch --skip bedtime

Command Reference

taskgun add

Add a single task with optional link from clipboard.

Syntax:

taskgun add [OPTIONS] <TASK_PARTS>...

Arguments:

Argument Type Description
<TASK_PARTS>... String Task description and optional taskwarrior arguments (required)

Options:

Flag Short Description
--link -l Attach clipboard content as link/url UDA to task

Examples:

# Simple task without link
taskgun add 'Buy milk'

# Task with due date and tags
taskgun add 'Review PR' due:tomorrow +work

# Task with link from clipboard
taskgun add -l 'Read article' due:7d +reading

# Complex task with project and priority
taskgun add 'Fix authentication' project:webapp due:today priority:H +urgent

Notes:

  • With -l flag: reads clipboard and stores content as a link UDA, and prepends 🔗 emoji to description
  • Supports all standard Taskwarrior arguments (due, project, priority, tags, etc.)
  • Use taskgun open <id> to open the attached link later

taskgun open

Open the link/url from a task in your default browser.

Syntax:

taskgun open <ID>

Arguments:

Argument Type Description
<ID> Number Task ID with link to open (required)

Examples:

# Open link from task 45
taskgun open 45

Notes:

  • Opens the link UDA value in your system's default browser
  • Fails gracefully if the task has no link attached
  • Works with any URL format (http, https, file, etc.)

taskgun create

Generate a series of numbered Taskwarrior tasks.

Syntax:

taskgun create <PROJECT> [OPTIONS]

Arguments:

Argument Type Description
<PROJECT> String Taskwarrior project name (required, positional)

Options:

Flag Short Type Required Description
--parts -p String Yes Number of tasks (e.g., 10) or subsection structure (e.g., 2,3,1)
--unit -u String No Task name prefix (default: Part)
--offset -o String No Time until first task (e.g., 5d, 2h, 30m, 45min) — units can be mixed with interval
--interval -i String No Time between tasks (e.g., 7d, 6h, 15m, 20min) — units can be mixed with offset
--skip String No Skip window (can be used multiple times)

Parts format:

  • Simple number: 10, 30, 12 (creates numbered tasks: Video 1, Video 2, ...)
  • Subsections: 2,3,1, 3,4,2 (creates hierarchical: Video 1.1, 1.2, 2.1, ...)

Skip values:

  • Named presets: bedtime, weekend, or custom from .taskrc
  • Time ranges: 2200-0600, 21:00-06:00, 1200-1400
  • Day names: sat,sun, friday,saturday,sunday, mon,tue,wed,thu,fri

Time units:

  • Days: d or D (e.g., 5d, 10D)
  • Hours: h or H (e.g., 2h, 24H)
  • Minutes: m, M, min, MIN, or Min (e.g., 30m, 45min, 90MIN)
  • Units can be mixed freely between offset and interval

Notes:

  • --parts is required
  • --offset and --interval must be provided together
  • --skip can be used multiple times

taskgun search

Search tasks by keyword or regex pattern.

Syntax:

taskgun search <KEYWORD> [OPTIONS]
# or shorthand:
taskgun <KEYWORD> [OPTIONS]

Arguments:

Argument Type Description
<KEYWORD> String Search keyword or regex pattern (required)

Options:

Flag Short Description
--regex -r Use regex mode (case-sensitive)

Examples:

# Case-insensitive keyword search
taskgun search learning
taskgun learning                    # shorthand

# Regex search
taskgun search 'lec.*[0-9]+' -r
taskgun 'video [12]' -r            # shorthand

Search behavior:

  • Default mode: case-insensitive search in project names and descriptions
  • Regex mode (-r/--regex): case-sensitive regex matching
  • Searches both project and description fields
  • Uses Taskwarrior's native filtering
  • Color-coded output with alternating row backgrounds
  • Flexible column widths that adapt to terminal width

taskgun completions

Generate shell completion scripts:

# Bash
taskgun completions bash > /usr/local/etc/bash_completion.d/taskgun

# Zsh
taskgun completions zsh > ~/.zfunc/_taskgun

# Fish
taskgun completions fish > ~/.config/fish/completions/taskgun.fish

How It Works

taskgun shells out to Taskwarrior's task add command for each task. It:

  1. Validates that Taskwarrior is installed
  2. Generates task names (simple or hierarchical)
  3. Calculates due dates if scheduling is requested
  4. Creates tasks one by one using task add

All tasks are created in your Taskwarrior database and follow your configured workflows, hooks, and settings.

Development

# Run tests
cargo test

# Run with logging
RUST_LOG=debug cargo run -- create "Test" -n 3

# Check code
cargo clippy -- -D warnings
cargo fmt --check

# Build release
cargo build --release

License

Licensed under either of:

at your option.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Roadmap

  • v0.1.0: Create subcommand with smart scheduling
  • v0.2.0: Skip system with presets and custom rules
  • v0.3.0: Mixed unit support and refined defaults
  • v0.4.0: Keyword search functionality
  • v0.5.0: Sort options and test coverage improvements
  • v0.6.0: Date-based filtering with due command
  • v0.7.0: Task plan sequencing
  • v0.8.0: Done command with plan integration
  • v0.9.0: Link management (add with clipboard, open in browser)
  • v1.0.0: Bulk modify subcommand
  • v1.1.0: Stable release with comprehensive testing

Links