# Complish
[](https://crates.io/crates/complish)
[](https://docs.rs/complish)
[](./LICENSE)
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
```rust
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:
```rust
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:
```rust
// 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:
```rust
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
```rust
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
```rust
// 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
```rust
// 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
```rust
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:
```rust
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](https://github.com/aaronmallen/complish-dev) for contribution guidelines.
## License
Licensed under the MIT License. See [LICENSE](LICENSE) for details.