repo-tasks

Fast, file-based task management for git repositories

repo-tasks is a lightning-fast CLI tool for managing tasks directly in your git repository. Tasks are stored as simple Markdown files with YAML frontmatter, making them easy to read, edit, and version control.

Features

• ⚡ Blazing Fast - Sub-10ms response times for most operations
• 📁 File-Based - Tasks stored as readable Markdown files
• 🎨 Beautiful CLI - Color-coded output with emoji indicators
• 🔍 Powerful Search - Full-text search powered by ripgrep
• 🔄 Git Integration - Commit changes with auto-generated messages
• 🏷️ Flexible Filtering - Filter by status, priority, or tags
• 🤖 LLM-Friendly - Designed for easy AI agent manipulation
• 📦 Single Binary - No runtime dependencies (only 3.3 MB!)

Installation

From Source

git clone https://github.com/yourusername/repo-tasks
cd repo-tasks
cargo install --path .

From Crates.io (coming soon)

cargo install repo-tasks

From Homebrew (coming soon)

brew install repo-tasks

Quick Start

# Initialize in your project
cd your-project
tasks init

# Create a new task
tasks new

# List all todo tasks
tasks list

# Move a task to in-progress
tasks move my-task in-progress

# Search for tasks
tasks search "bug fix"

# Save changes to git
tasks save

Usage

Initialize Repository

tasks init [--project-name NAME]

Creates a .repo-tasks/ directory with the following structure:

.repo-tasks/
├── config.json
└── tasks/
    ├── todo/
    ├── in-progress/
    ├── testing/
    └── done/

Create Tasks

tasks new

Interactively creates a new task with:

• Title (required)
• Priority (Low, Medium, High, Critical)
• Optional description

Tasks are saved as Markdown files with YAML frontmatter:

---
ID: "20260109120000"
Title: Implement user authentication
Priority: High
Tags:
  - security
  - backend
---

Add JWT-based authentication to the API endpoints.
Includes login, logout, and token refresh functionality.

List Tasks

# List tasks in a specific status
tasks list [STATUS]

# Filter by priority
tasks list --priority High

# Filter by tag
tasks list --tag security

# Combine filters
tasks list in-progress --priority Critical

View Task Details

tasks show SLUG_OR_ID

Displays full task information including description, dependencies, and metadata.

Update Tasks

tasks update SLUG_OR_ID

Interactively update task properties:

• Title
• Priority
• Tags
• Description

Move Tasks

tasks move SLUG_OR_ID STATUS

Move tasks between statuses:

• todo - Not started
• in-progress - Currently working on
• testing - Ready for testing/review
• done - Completed

Search Tasks

tasks search QUERY

Full-text search with regex support. Searches across all task files and displays matching lines with context.

Open in Editor

tasks open SLUG_OR_ID

Opens the task file in your $EDITOR or platform default editor.

Save Changes

tasks save [-m "commit message"]

Commits all changes in .repo-tasks/ to git. Auto-generates commit messages if not provided.

Configuration

Configuration is stored in .repo-tasks/config.json:

{
  "project_name": "my-project",
  "statuses": [
    "todo",
    "in-progress",
    "testing",
    "done"
  ],
  "priorities": [
    "Low",
    "Medium",
    "High",
    "Critical"
  ],
  "auto_commit": false
}

Customization

You can customize:

• Project name - Display name for the project
• Statuses - Add custom workflow states
• Priorities - Define priority levels
• Auto-commit - Automatically commit after each change

Task File Format

Tasks are stored as Markdown files with YAML frontmatter:

---
ID: "YYYYMMDDHHMMSS"
Title: Task title
Priority: High
Tags:
  - tag1
  - tag2
Blocks:
  - other-task-id
DependsOn:
  - dependency-id
---

Task description goes here.
Supports full Markdown formatting.

## Subtasks

- [ ] Subtask 1
- [ ] Subtask 2

Frontmatter Fields

• ID (required) - Unique timestamp identifier
• Title (required) - Task title
• Priority (optional) - Task priority
• Tags (optional) - List of tags
• Blocks (optional) - IDs of tasks this task blocks
• DependsOn (optional) - IDs of dependency tasks

Performance

repo-tasks is designed for speed:

LLM Integration

repo-tasks is designed to be easily manipulated by AI agents:

1. Simple file format - Plain Markdown with YAML frontmatter
2. Direct file access - No database or complex API
3. Self-documenting - Structure is evident from examples
4. Git-integrated - Changes are versioned automatically

Example LLM Workflow

Human: "Create a task for implementing search functionality"

LLM: [Reads config.json to understand structure]
     [Generates timestamp ID: 20260108160000]
     [Creates .repo-tasks/tasks/todo/20260108160000-implement-search.md]
     [Optionally runs: tasks save -m "Add search task"]

Development

Building from Source

# Debug build
cargo build

# Release build (optimized)
cargo build --release

# Run tests
cargo test

# Run benchmarks
cargo bench

Project Structure

repo-tasks/
├── src/
│   ├── commands/      # Command implementations
│   ├── models/        # Data structures (Task, Config)
│   ├── utils/         # Utilities (output, errors)
│   ├── main.rs        # CLI entry point
│   └── lib.rs         # Library exports
├── tests/             # Integration tests
├── Cargo.toml
└── README.md

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

MIT License - see LICENSE for details

Acknowledgments

Built with:

• clap - CLI argument parsing
• serde - Serialization framework
• ripgrep - Fast search
• git2 - Git integration
• dialoguer - Interactive prompts

Roadmap

• Shell completion scripts (bash, zsh, fish)
• Task templates
• Dependency visualization
• Watch mode for auto-refresh
• GitHub Issues integration
• TUI mode with interactive interface

Made with ❤️ and Rust