Skip to content

TaskRepo

TaskRepo Logo

CI Status PyPI version Python versions License: MIT

TaskWarrior-inspired CLI for managing tasks as markdown files in git repositories

TaskRepo is a powerful command-line task management tool that combines the best of TaskWarrior's workflow with the simplicity of markdown and the collaboration features of git.

✨ Key Features

  • Git-Backed Storage

    All tasks stored as markdown files in git repositories with full version control and collaboration capabilities

  • TaskWarrior-Inspired

    Familiar workflow with priorities, tags, dependencies, and due dates for power users

  • Rich Metadata

    YAML frontmatter for structured task data with markdown descriptions

  • Link Associations

    Attach URLs to tasks (GitHub issues, PRs, emails, documentation, etc.)

  • Interactive TUI

    User-friendly prompts with autocomplete and validation for seamless task creation

  • Multiple Repositories

    Organize tasks across different projects or contexts

  • GitHub Integration

    Associate tasks with GitHub user handles and repositories

  • Beautiful Output

    Rich terminal formatting with tables and colors

🎨 Interactive TUI

TaskRepo TUI Interface
Browse and manage tasks with the interactive Terminal User Interface

The TUI provides a visual, keyboard-driven interface for managing your tasks with:

  • Color-coded status indicators - Instantly see pending, in-progress, and completed tasks
  • Real-time task details panel - View all task metadata at a glance
  • Multi-select operations - Select and operate on multiple tasks at once
  • Keyboard shortcuts - All operations accessible via intuitive keyboard shortcuts
  • Countdown timers - See how much time until tasks are due

Launch with tsk tui to experience the full power of TaskRepo!

🚀 Quick Start

Get started with TaskRepo in just a few commands:

# Install TaskRepo
brew install henriqueslab/formulas/taskrepo  # macOS
pipx install taskrepo                         # Linux/Windows

# Initialize and create a repository
tsk init
tsk create-repo work

# Add your first task
tsk add

# List your tasks
tsk list

Get Started → View on GitHub →

📖 Example

Tasks are stored as markdown files with YAML frontmatter:

---
uuid: 'a3f2e1d9-4b7c-4e3f-9a1b-2c3d4e5f6a7b'
title: Fix authentication bug
status: pending
priority: H
project: backend
assignees:
  - '@alice'
  - '@bob'
tags:
  - bug
  - security
links:
  - https://github.com/org/repo/issues/123
due: '2025-11-15T00:00:00'
created: '2025-10-20T10:30:00'
modified: '2025-10-20T14:22:00'
---

## Description

The login endpoint is not properly validating JWT tokens.

## Steps to reproduce

1. Attempt to login with expired token
2. Observe that access is granted

## Solution

Update JWT validation middleware to check expiration.

🎯 Why TaskRepo?

  • Version Control: Full git history for all task changes
  • Collaboration: Share task repositories with your team
  • Portability: Plain text files that work with any text editor
  • Flexibility: Organize tasks however you want with multiple repositories
  • Power: TaskWarrior-inspired features without the learning curve
  • Beautiful: Rich terminal output makes task management enjoyable

🌟 What's Next?

🤝 Contributing

Contributions are welcome! Check out our contributing guide to get started.

📝 License

TaskRepo is released under the MIT License.

Made with ❤️ by HenriquesLab