Skip to content

Configuration File

TaskRepo configuration is stored as YAML at ~/.TaskRepo/config.

File Location

Default path: ~/.TaskRepo/config

Custom location: Set TASKREPO_CONFIG environment variable

Legacy migration: Old ~/.taskreporc is automatically migrated on first run

Configuration Format

parent_dir: ~/tasks
default_priority: M
default_status: pending
default_assignee: null
default_github_org: null
default_editor: null
sort_by:
  - due
  - priority
cluster_due_dates: false

Configuration Options

parent_dir

Type: Path Required: Yes Default: ~/tasks

Directory where task repositories are stored. Each repository will be created as tasks-{name} subdirectory.

parent_dir: ~/projects/tasks

Tilde expansion: ~ is automatically expanded to home directory

default_priority

Type: String Values: H (High), M (Medium), L (Low) Default: M

Default priority for new tasks when not specified.

default_priority: H

default_status

Type: String Values: pending, in-progress, completed, cancelled Default: pending

Default status for new tasks.

default_status: pending

default_assignee

Type: String (GitHub handle with @ prefix) or null Default: null

If set, automatically assigns this GitHub handle to new tasks when no assignees are specified. Useful for personal task management.

default_assignee: '@alice'

Behavior: Only applied when creating tasks without explicit assignees.

default_github_org

Type: String (GitHub organization/username) or null Default: null

If set, used as default organization when creating GitHub repositories with tsk create-repo.

default_github_org: 'HenriquesLab'

default_editor

Type: String (editor command) or null Default: null

Text editor for editing task descriptions. If not set, uses $EDITOR or $VISUAL environment variables.

default_editor: 'vim'

Common editors: vim, nano, code, emacs, subl

sort_by

Type: List of strings Default: ['due', 'priority']

Defines task sorting order. Tasks are sorted by fields in the order specified.

Supported fields: - priority - Priority (H > M > L) - due - Due date (earliest first) - created - Creation timestamp (oldest first) - modified - Last modified timestamp (newest first) - status - Task status - title - Alphabetically by title - project - Alphabetically by project - assignee - By first assignee (see Assignee Sorting below)

Descending order: Prefix field with - to reverse order

sort_by:
  - -priority      # High priority last
  - due            # Then by due date (earliest first)
  - created        # Then by creation time

Assignee Sorting

The assignee field supports special syntax for preferred sorting:

Basic alphabetical: 

sort_by:
  - assignee       # Tasks sorted by first assignee alphabetically
  - due

Preferred assignee: 

sort_by:
  - assignee:@alice   # @alice's tasks first, then others
  - due
  - priority

Descending order: 

sort_by:
  - -assignee:@alice  # Non-@alice tasks first, then @alice's

cluster_due_dates

Type: Boolean Default: false

When enabled, groups tasks by countdown buckets instead of exact due dates. This allows secondary sort fields (like priority) to take precedence within each time bucket.

cluster_due_dates: true

Time buckets: - Overdue (2+ weeks, 1 week, 1-6 days) - Today - Tomorrow - 2-3 days - 4-13 days - 1-3 weeks - 1 month - 2+ months - No due date

Example: Clustering Effect

Without clustering (cluster_due_dates: false): 

1. Task A (due today 11:59 PM, priority: L)
2. Task B (due tomorrow 12:01 AM, priority: H)  # Earlier timestamp

With clustering (cluster_due_dates: true): 

1. Task C (due today 11:59 PM, priority: H)     # Same bucket, higher priority
2. Task A (due today 11:59 PM, priority: L)
3. Task B (due tomorrow 12:01 AM, priority: H)  # Different bucket

With clustering enabled and sort_by: [due, priority]: - All "today" tasks are sorted by priority first - Then all "tomorrow" tasks are sorted by priority - Exact timestamps within a bucket don't matter

Complete Example

# TaskRepo Configuration

# Task repository location
parent_dir: ~/work/tasks

# Default values for new tasks
default_priority: M
default_status: pending
default_assignee: '@paxcalpt'

# GitHub integration
default_github_org: 'HenriquesLab'

# Text editor
default_editor: 'code --wait'

# Sorting configuration
sort_by:
  - assignee:@paxcalpt  # My tasks first
  - due                 # Then by due date
  - priority            # Then by priority
  - created             # Finally by creation time

# Enable due date clustering
cluster_due_dates: true

Configuration Management

View Configuration

# Show configuration in YAML format
tsk config-show

Edit Configuration

# Interactive configuration editor
tsk config

Opens a TUI with: - Arrow keys to navigate fields - Enter to edit values - 's' to save changes - 'q' to quit without saving

Manual Editing

You can also edit ~/.TaskRepo/config directly with any text editor:

vim ~/.TaskRepo/config

Important: Ensure YAML syntax is valid after manual edits.

Cache Files

TaskRepo maintains cache files alongside the configuration:

~/.TaskRepo/id_cache.json Maps display IDs (1, 2, 3...) to task UUIDs for consistent referencing.

~/.TaskRepo/update_check_cache.json Tracks when update checks were last performed to avoid excessive network requests.

Note: Cache files are automatically managed. Manual editing is not recommended.

Migration from Legacy Config

If you have an old ~/.taskreporc file, TaskRepo automatically migrates it to the new location on first run:

  1. Reads ~/.taskreporc
  2. Converts to new format at ~/.TaskRepo/config
  3. Renames old file to ~/.taskreporc.backup

Legacy cache files are also migrated: - ~/.taskrepo_id_cache.json → ~/.TaskRepo/id_cache.json - ~/.taskrepo_update_check.json → ~/.TaskRepo/update_check_cache.json

Next Steps