Complish

A local-first task management library with project organization and efficient binary storage.

Features

• Three-List Workflow: Organize tasks into today, next, and someday lists
• Project Organization: Group related tasks with unique project keys (e.g., AUTH-01, WEB-15)
• Rich Task Model: Status tracking, priorities, work logs, notes, and tags
• Fast Local Storage: Binary serialization with efficient indexing for quick lookups
• Friendly IDs: Human-readable task identifiers that work great in CLIs

Quick Start

use complish::{Vault, TaskPriority};
use eyre::Result;

fn main() -> Result<()> {
    // Load or create a vault
    let mut vault = Vault::load()?;
    
    // Create a simple task
    let task = vault
        .add_task("Fix login bug")
        .in_list("today")?
        .with_priority(TaskPriority::High)
        .create()?;
    
    println!("Created task: {}", task.friendly_id); // "1"
    
    // Create a project-scoped task
    let project_task = vault
        .add_task("Update user authentication")
        .for_project("AUTH")?
        .in_list("next")?
        .with_description("Implement OAuth 2.0 flow")
        .create()?;
    
    println!("Created task: {}", project_task.friendly_id); // "AUTH-01"
    
    Ok(())
}

Core Concepts

Tasks

Individual work items with comprehensive metadata:

let mut task = vault.add_task("Write documentation").create()?;

// Status management
task.start_work()?;
task.complete();
task.reopen();

// Metadata
task.add_description("Add examples and API docs");
task.add_note("Remember to include code samples");
task.add_tag("documentation");
task.set_priority(TaskPriority::Medium);

// Work tracking
task.start_work_with_note("Starting research")?;
task.stop_work();
let total_time = task.total_time_worked();

Projects

Collections of related tasks with unique keys:

// Projects are automatically created when referenced
let task = vault
    .add_task("Setup CI pipeline")
    .for_project("DEVOPS")?  // Creates "DEVOPS" project if it doesn't exist
    .create()?;

// Task gets friendly ID: "DEVOPS-01"

Vault

The storage and indexing layer that manages everything:

let mut vault = Vault::load()?;

// Fast lookups by friendly ID
if let Some(task) = vault.find_task_by_friendly_id("AUTH-05") {
    task.complete();
}

// List operations
let today_tasks = vault.get_tasks_in_list("today");
let auth_project_tasks = vault.get_tasks_for_project("AUTH");

// Persistence
vault.save()?; // Saves to ~/.local/share/complish/vault

Architecture

Storage

• Binary format: Uses bincode for fast serialization
• Local-first: No cloud dependencies, complete data ownership
• Atomic operations: Safe concurrent access with file locking
• Efficient indexing: O(1) lookups for common operations

ID System

• Canonical IDs: Internal unique identifiers (e.g., 500)
• Friendly IDs: User-facing identifiers (e.g., "AUTH-15", "42")
• Project scoping: Tasks in projects get prefixed IDs
• Sequence preservation: No gaps in ID sequences, even with failed operations

Task Model

pub struct Task {
    pub id: u32,                          // Canonical ID
    pub friendly_id: String,              // User-facing ID
    pub subject: String,                  // Title
    pub description: Option<String>,      // Detailed description
    pub status: TaskStatus,               // Todo, InProgress, Done
    pub priority: TaskPriority,           // P0 (highest) to P4 (lowest)
    pub resolution: Option<TaskResolution>, // Completed, Cancelled, Delegated
    pub tags: Vec<String>,                // Flexible categorization
    pub notes: Vec<TaskNote>,             // Timestamped annotations
    pub work_logs: Vec<TaskWorkLog>,      // Time tracking entries
    pub due_at: Option<DateTime<Utc>>,    // Deadline
    pub completed_at: Option<DateTime<Utc>>, // Completion timestamp
    // ... timestamps and metadata
}

Examples

Daily Planning Workflow

// Morning: Move tasks to today's list
vault.move_task_to_list("AUTH-05", "today")?;
vault.move_task_to_list("WEB-12", "today")?;

// During work: Track progress
let task = vault.find_task_by_friendly_id_mut("AUTH-05").unwrap();
task.start_work_with_note("Implementing OAuth redirect")?;
// ... later
task.complete_with_note("Tested with Google and GitHub providers");

// Evening: Review completed tasks
let completed_today = vault.get_completed_tasks_today();

Project Management

// Create related tasks
for feature in ["Login page", "Password reset", "2FA setup"] {
    vault.add_task(feature)
        .for_project("AUTH")?
        .in_list("next")?
        .create()?;
}

// Get project overview
let auth_tasks = vault.get_tasks_for_project("AUTH");
let completed = auth_tasks.iter().filter(|t| t.is_complete()).count();
let total = auth_tasks.len();
println!("AUTH project: {}/{} tasks complete", completed, total);

Time Tracking

let mut task = vault.find_task_by_friendly_id_mut("WEB-08").unwrap();

// Start work with context
task.start_work_with_source("vscode")?;

// Add notes during work
task.add_note("Found the issue in the CSS grid layout");

// Stop work
task.stop_work();

// Get insights
let total_time = task.total_time_worked();
let is_currently_active = task.is_being_worked();

Error Handling

The library uses eyre for ergonomic error handling:

use eyre::Result;

// Validation errors provide helpful context
match vault.add_task("Fix bug").for_project("INVALID") {
    Ok(builder) => { /* ... */ }
    Err(e) => println!("Error: {}", e), // "Project with key 'INVALID' not found"
}

// List validation
match vault.add_task("Task").in_list("invalid_list") {
    Ok(builder) => { /* ... */ }
    Err(e) => println!("{}", e), // "List 'invalid_list' not found. Must be one of: today, next, someday"
}

Platform Support

• Linux: ~/.local/share/complish/
• macOS: ~/Library/Application Support/complish/
• Windows: %APPDATA%/complish/

Contributing

This library is part of the larger Complish productivity tool ecosystem. See the main repository for contribution guidelines.

License

Licensed under the MIT License. See LICENSE for details.