Taskwarrior & Timewarrior Scripts

A collection of shell aliases and functions for taskwarrior, timewarrior, and vit to supercharge your CLI productivity workflow.

Installation

# Clone or extract the archive
git clone https://github.com/kapott/time-system.git
cd time-system

# Run the install script
./install.sh

# Reload shell
source ~/.zshrc

Uninstallation

# Run the uninstall script
./uninstall.sh

# Then remove the source line from your shell config manually

Dependencies

• taskwarrior - Task management
• timewarrior - Time tracking
• vit - Vim interface for taskwarrior
• fzf - Fuzzy finder (for interactive functions)
• jq - JSON processor (for some functions)

Commands Reference

Basic Task Aliases

Command	Expands To	Description
t	task	Taskwarrior shortcut
ta	task add	Add a task
tl	task list	List pending tasks
tn	task next	Show next tasks (smart sort)
td	task done	Mark task as done
te	task edit	Edit task in $EDITOR
ti	task info	Show task details

Task View Aliases

Command	Expands To	Description
tall	task all	Show all tasks (including completed)
tcomp	task completed	Show completed tasks
tblock	task blocked	Show blocked tasks
tunblock	task unblocked	Show unblocked tasks
tover	task overdue	Show overdue tasks
tready	task ready	Show tasks ready to work on
twait	task waiting	Show waiting tasks

Task Action Aliases

Command	Expands To	Description
tstart	task start	Start working on a task
tstop	task stop	Stop working on a task
tmod	task modify	Modify a task
tdel	task delete	Delete a task
tundo	task undo	Undo last action

Task Filter Aliases

Command	Expands To	Description
turgent	task +urgent	Show urgent tasks
tnext	task +next	Show tasks tagged +next
tinbox	task +inbox	Show inbox tasks
ttoday	task due:today	Show tasks due today
tweek	task due.before:sunday	Show tasks due this week

Timewarrior Aliases

Command	Expands To	Description
tw	timew	Timewarrior shortcut
tws	timew summary	Show time summary
twst	timew start	Start time tracking
twsp	timew stop	Stop time tracking
twday	timew summary :day	Today's time summary
twweek	timew summary :week	This week's time summary
twmonth	timew summary :month	This month's time summary
twtags	timew tags	Show all time tags
twids	timew summary :ids	Show summary with IDs

Context & Project Aliases

Command	Expands To	Description
v	vit	Launch vit TUI
tctx	task context	Context management
tctxs	task context show	Show current context
tctxn	task context none	Clear context
tproj	task projects	List all projects

Interactive Functions (fzf-powered)

Command	Arguments	Description
p	-	Select project (client/project), cd to dir, set scope
tstart	[task_id]	Start task (interactive if no ID)
tstop	-	Stop current task and time tracking
tdone	[task_id]	Complete task (interactive if no ID)
tmodf	-	Modify task (interactive selection)
tdelf	-	Delete task (interactive selection)
taddp	<description>	Add task with project selection

Review Functions

Command	Description
weekstart	Weekly review: overdue, due this week, blocked, time tracked
dayreview	Daily review: today's tasks, active, time today
dayend	End of day: completed today, time tracked, still active

Time Tracking Functions

Command	Arguments	Description
twcurrent	-	Show current tracking and active task
twproj	[project]	Start tracking a project (interactive if no arg)
twlog	<duration> <tags...>	Log past work (e.g., twlog 2h coding)
twback	[minutes]	Adjust current tracking start time back
twsumproj	[project]	Show time summary for project

Utility Functions

Command	Arguments	Description
tadd	<description>	Add task to current project (or inbox if no scope)
tbackup	[directory]	Backup tasks to JSON
tsync	-	Sync with taskd server

Usage Examples

# Morning routine
weekstart                    # Review the week
p                            # Select project to focus on

# During work
tadd "Fix login bug"         # Quick capture to inbox
tstart 5                     # Start task 5 with time tracking
# ... work ...
tstop                        # Stop when done
tdone 5                      # Mark complete

# Interactive workflow
tstart                       # Pick task with fzf
tmodf                        # Modify task with fzf
taddp "New feature"          # Add with project selection

# Time tracking
twproj                       # Track time on a project
twback 15                    # Oops, started 15 min ago
twcurrent                    # What am I tracking?

# End of day
dayend                       # Summary of the day
tbackup                      # Backup tasks

Configuration

Set these environment variables before sourcing task-functions.sh:

# Base directory containing client/project folders (default: ~/Documents/Git)
export TASKFUNC_PROJECTS_DIR="$HOME/Projects"

source ~/.local/share/taskwarrior-scripts/task-functions.sh

Project Structure

The scripts expect a two-level directory structure:

$TASKFUNC_PROJECTS_DIR/
├── clientA/
│   ├── project1/
│   └── project2/
├── clientB/
│   └── projectX/

When you select a project with p, it:

1. Changes to the project directory
2. Sets a taskwarrior context filtering to project:clientA.project1
3. Shows only tasks for that project
4. tadd will add tasks to that project automatically

Use tctxn to clear the scope and see all tasks again.

Customization

Edit task-functions.sh to:

• Add more aliases
• Modify fzf options (height, preview, etc.)
• Add project-specific shortcuts
• Integrate with other tools

Related Posts

• Taskwarrior, Timewarrior and Vit Tutorial
• Working with an AuDHD Brain