WhatDo

A "what am I doing right now" tracker CLI for macOS. Track your tasks with a stack-based model: start tasks, pause/resume them, and maintain an append-only event log for complete history.

Features

• Stack-based task tracking: Tasks stack on top of each other. When you finish a task, you resume the previous one.
• Pause/Resume: Pause tasks to work on interruptions, then resume where you left off.
• Notes: Add timestamped notes to any task (active or paused).
• Append-only log: All events are stored in a JSONL file. State is computed from events.
• Archiving: Manually archive completed sessions to keep logs manageable.
• Configuration via PKL: Flexible configuration using Apple's Pkl language.
• State caching: Automatic caching for fast status lookups, even with large logs.

Installation

cd /Users/junebash/repos/WhatDo
swift build -c release
cp .build/release/wd /usr/local/bin/  # or add to your PATH

Quick Start

# Start a task
wd now "Write README"

# Check status
wd status

# Start an interruption (pauses previous task)
wd now "Answer email"

# Finish the interruption (resumes previous task)
wd done

# Add a note to current task
wd note "Don't forget to add examples"

# Finish the original task
wd done

# View recent activity
wd log --limit 10

# Archive the session
wd archive

Commands

Task Management

• wd now <text> [--tag <tag>...] - Start a new task
• wd done [--count N] - Complete N tasks (default: 1)
• wd pause - Pause the current task
• wd resume <task-id> - Resume a paused task
• wd note [--task <id>] <text> - Add a note to a task

Status & History

• wd status [--json] - Show current active and paused tasks
• wd log [--limit N] [--json] - Show recent events

Archiving

• wd archive - Archive current session to ~/.local/share/whatdo/archives/

Configuration

• wd config init - Create default configuration
• wd config path - Show configuration directory
• wd config edit - Edit configuration in $EDITOR

Configuration

Configuration is stored at ~/.config/whatdo/config.pkl (respects $XDG_CONFIG_HOME).

Default configuration:

module whatdo.config

xdgDataHome = env("XDG_DATA_HOME") ?: (homeDir + "/.local/share")

config {
  dataDir = xdgDataHome + "/whatdo"
  archive.onEmptyStack = false
  time.iso8601FractionalSeconds = true
}

Data Storage

• Active log: ~/.local/share/whatdo/active.jsonl
• State cache: ~/.local/share/whatdo/state.json
• Archives: ~/.local/share/whatdo/archives/<session-id>.jsonl
• Session index: ~/.local/share/whatdo/archives/index.json

Event Schema

Events are stored as newline-delimited JSON:

{"id":"...","ts":"2025-10-24T09:18:23.123Z","type":"start","taskId":"...","text":"Write README","tags":["docs"]}
{"id":"...","ts":"2025-10-24T09:40:00.456Z","type":"start","taskId":"...","text":"Answer email"}
{"id":"...","ts":"2025-10-24T09:55:00.789Z","type":"stop","count":1}
{"id":"...","ts":"2025-10-24T10:00:00.012Z","type":"pause","taskId":"..."}
{"id":"...","ts":"2025-10-24T14:00:00.345Z","type":"resume","taskId":"..."}
{"id":"...","ts":"2025-10-24T14:30:00.678Z","type":"note","taskId":"...","text":"Important update"}
{"id":"...","ts":"2025-10-24T15:30:00.901Z","type":"stop","count":1}

Architecture

Modules

• WhatDoCore: Domain models (Event, Task, TrackerState, Reducer)
• WhatDoIO: File I/O, locking, state caching, archiving
• WhatDoConfig: PKL-based configuration loading
• WhatDoReport: Status and log formatting (human + JSON)
• WhatDoCLI: Command-line interface

Design Principles

• Event Sourcing: All state is derived from an append-only log of events.
• Stack-based Model: Tasks are organized as a stack (LIFO).
• Pause/Resume Support: Tasks can be paused and resumed across sessions.
• Never Delete Data: Archiving moves data but never deletes it.
• State Caching: State is cached after every command when log exceeds 1000 events.

Development

Building

swift build

Running Tests

swift test

Dependencies

• swift-argument-parser - CLI argument parsing
• swift-dependencies - Dependency injection
• pkl-swift - PKL configuration language support

License

This project is open source and available under your preferred license.