🎯 Vibetasker (Cognitive Orthotics)

ADHD-optimized TUI task manager with semantic prioritization using WSJF (Weighted Shortest Job First).

Overview

Vibetasker helps you overcome decision paralysis by automatically prioritizing tasks based on:

• Goal alignment - semantic similarity to your stated goal
• Urgency - hyperbolic time decay for due dates
• Cognitive relief - how many blocked tasks this unblocks
• Energy cost - matched against your current energy level

The app learns from your completion patterns and helps you maintain focus through AI-assisted task breakdown, goal drift detection, and daily reviews.

Installation

Prerequisites

• Python 3.11 or higher
• uv or pip package manager

Install from source

# Clone repository
git clone <repository-url>
cd vibetasker

# Install using uv (recommended)
uv pip install -e .

# Or using pip
pip install -e .

Verify installation

vibetasker --version

Configuration

Configuration file location

Default: ~/.config/taskmanager/config.toml

On first run, a setup wizard will guide you through initial configuration. To manually edit config:

# ~/.config/taskmanager/config.toml

goal = "Finish my thesis"
current_energy = 7

embedding_provider = "local"  # or "openai", "vertex", "bedrock"
vector_store = "sqlite-vec"

# Optional: Apple Reminders sync (macOS only)
sync_reminders = false
reminders_list_name = "Tasks"

# Optional: Cloud provider credentials
# openai_api_key = "sk-..."
# anthropic_api_key = "sk-ant-..."

Environment variables

Override config with environment variables using TASKMANAGER_ prefix:

export TASKMANAGER_GOAL="Launch MVP"
export TASKMANAGER_CURRENT_ENERGY=5
export ANTHROPIC_API_KEY="sk-ant-..."

CLI arguments

Override config for a single session:

vibetasker --goal "Finish thesis" --energy 3
vibetasker --config /path/to/custom/config.toml

Quickstart

First run

vibetasker

Follow the setup wizard:

1. Enter your main goal (e.g., "Launch MVP", "Finish thesis")
2. Set current energy level (1-10 scale)
3. Choose embedding provider (local recommended for privacy)
4. Enable/disable Apple Reminders sync (macOS only)

Basic workflow

1. Capture ideas: Press i to quickly capture tasks to staging area
2. Add tasks: Press a to add structured tasks with details
3. View priorities: Tasks auto-sort by WSJF score
4. Complete tasks: Press c to mark complete (updates streak)
5. Energy filter: Press [ or ] to adjust energy, hiding high-energy tasks when you're tired

Daily routines

• Morning review (m): Review upcoming tasks, adjust priorities
• Evening reflection (e): Review completed tasks, update learnings

Keyboard Shortcuts

Navigation

• j / ↓ - Move down
• k / ↑ - Move up
• Enter - View task details

Task Actions

• a - Add task
• i - Capture idea (staging)
• c - Complete task
• r - Give feedback (reject task)
• / - Search tasks (semantic search)
• p - View projects (auto-clustered)

AI Features

• b - Break down task (AI decomposition)
• d - Check for goal drift
• n - What's next? (AI recommendation)
• w - Why am I doing this? (goal alignment check)

Energy & Focus

• [ - Decrease energy level
• ] - Increase energy level
• f - Focus mode (Pomodoro)

Reviews

• m - Morning review
• e - Evening reflection

Sync & Help

• s - Sync integrations (Apple Reminders)
• ? - Show help
• q - Quit application

WSJF Prioritization

Vibetasker uses WSJF (Weighted Shortest Job First) to calculate task priority:

priority = (W_I × impact + W_T × urgency + W_R × relief) / energy_cost

Components

Impact (Goal Alignment)

• Semantic similarity between task and your stated goal
• Uses sentence embeddings (cosine similarity 0.0-1.0)
• Weight: 3.0 (highest priority factor)

Urgency (Time Criticality)

• Hyperbolic decay: tasks due tomorrow score higher than tasks due next month
• Formula: 1 / (1 + days_until_due)
• Weight: 2.0

Relief (Cognitive Load)

• How many tasks are blocked waiting for this one
• Unblocking 3 tasks scores higher than unblocking 0
• Weight: 1.0

Energy Cost

• Estimated energy required (1-10 scale)
• When your energy is low (e.g., 3/10), high-energy tasks are filtered out
• Learned from completion history via mem0

Example scores

Example goal: "Finish thesis and graduate"

Task	Goal Align	Urgency	Relief	Energy	WSJF Score	Rank
Set up thesis LaTeX template	0.70	0.10	1.00	3.0	1.10	1st
Finalize thesis introduction	0.76	0.15	0.40	6.0	0.50	2nd
Update personal website	0.58	0.00	0.10	4.0	0.46	3rd

Key insights:

• Task 1 ranks highest due to high relief (unblocks 5 other tasks) + low energy cost
• Task 2 has highest goal alignment but ranks 2nd due to moderate energy cost
• Task 3 ranks lowest - low alignment and no blocking relationships
• WSJF naturally prioritizes "quick wins" (low energy, high value) when appropriate
• Urgency uses hyperbolic decay: tomorrow = ~0.15, next week = ~0.02, next month = ~0.002

Features

Semantic Search

Search by meaning, not just keywords:

• Query "authentication" finds "login", "auth", "security" tasks
• Query "documentation" finds "README", "docs", "guide" tasks
• Uses cosine similarity threshold (>0.7 for relevance)

Task Clustering (Projects)

Tasks automatically cluster by semantic similarity:

• "Write auth tests" + "Implement login" → "Authentication" project
• "Update README" + "Add docstrings" → "Documentation" project
• Press p to view clustered projects

Energy-Aware Filtering

• Set energy level 1-10 ([ and ] keys)
• High-energy tasks automatically filtered when tired
• Focus on quick wins when energy is low

Duplicate Detection

New tasks checked against existing tasks:

• Warns if semantic similarity >0.85
• Prevents accidental duplicates
• Option to merge or keep separate

Streak Tracking

• Tracks consecutive days with completed tasks
• Displayed in header: "🔥 5 days streak"
• Resets if you skip a day

Focus Mode

• Press f to enter distraction-free mode
• Shows only current task (no task list, simplified UI)
• Built-in Pomodoro timer (default: 25 minutes)
• Timer features:
  • Pause/Resume with p
  • Visual countdown display (MM:SS format)
  • Warning color when < 5 minutes remaining
  • Bell notification on completion
• Displays goal alignment percentage ("Why this matters")
• Press Esc to exit and return to main view
• Minimizes UI noise to maintain flow state

AI Agents

Requires ANTHROPIC_API_KEY environment variable.

Task Breakdown (b key)

• "Write thesis" → ["Outline chapter", "Research sources", "Write draft"]
• Recursively breaks down large tasks

Goal Drift Detection (d key)

• Warns after completing 5+ low-alignment tasks
• Suggests refocusing on high-priority work

Next Task Recommendation (n key)

• Suggests top 3 tasks considering context switching cost
• Prefers similar tasks (coding → coding, not coding → email)

Learning Engine (mem0)

After 10+ task completions, the system learns:

• Your actual vs estimated durations
• Energy cost patterns by task type
• Friction multipliers (procrastination indicators)
• Improves future estimates

Apple Reminders Sync (macOS)

Bidirectional sync with Apple Reminders for mobile task capture:

Setup:

# In ~/.config/taskmanager/config.toml
sync_reminders = true
reminders_list_name = "Tasks"  # Name of list in Reminders.app

How it works:

• Create in Vibetasker → Syncs to Apple Reminders (title, description, due date, completion status)
• Create on iPhone/iPad → Syncs to Vibetasker on next sync (press s)
• Complete in either app → Completion status syncs bidirectionally
• Update in Reminders → Changes sync back to Vibetasker

Key behaviors:

• No duplicates: Tasks matched by title (existing tasks updated, not duplicated)
• Timestamp-based updates: Only syncs if remote timestamp is newer
• Metadata preserved: Vibetasker-specific fields (tags, energy_cost, goals) preserved locally
• Manual sync: Press s in the app to trigger sync (not automatic)

Limitations:

• macOS only: Uses EventKit framework (requires macOS system)
• Title-based matching: Tasks matched by title string (not UUID)
• Permissions required: Grant Reminders access on first use
• One-way metadata: Vibetasker metadata (tags, WSJF scores) doesn't sync to Reminders
• No conflict resolution: Newer timestamp wins (last-write-wins strategy)

Architecture

taskmanager/
├── config/          # Pydantic settings with TOML/env support
├── core/            # Domain logic (WSJF, energy, urgency, relief)
├── embeddings/      # Sentence transformers, OpenAI, Vertex
├── storage/         # Git-backed JSONL storage (beads)
├── integrations/    # Apple Reminders, AI agents, mem0 learning
└── tui/             # Textual TUI, wizard, widgets

Storage

• Format: JSONL (one task per line)
• Versioning: Git commits for every change
• Location: ~/.local/share/taskmanager/tasks.jsonl
• Backup: Full git history, easily recoverable

Embeddings

• Local: sentence-transformers/all-MiniLM-L6-v2 (default)
• Cloud: OpenAI, Vertex AI, AWS Bedrock (optional)
• Privacy: Local embeddings keep data on-device

Troubleshooting

Setup wizard doesn't run on first launch

The wizard runs automatically when no config file exists at ~/.config/taskmanager/config.toml.

To retrigger the wizard:

rm ~/.config/taskmanager/config.toml
vibetasker

The wizard will:

• Guide you through 4 steps (goal, energy, provider, sync)
• Support "Back" navigation to revise previous choices
• Create config.toml upon completion
• Not run again on subsequent launches (config file exists)
• Exit cleanly if cancelled (no config created)

Tasks not syncing with Apple Reminders

• Check sync_reminders = true in config
• Verify Reminders.app has correct list name
• macOS only - requires System Events permissions

Semantic search returns irrelevant results

• Threshold too low - increase in code (default 0.7)
• Try different embedding provider
• Add more context to task descriptions

App crashes on launch

# Check Python version
python --version  # Must be >=3.11

# Reinstall dependencies
uv pip install -e . --force-reinstall

# Check logs
vibetasker --debug

High memory usage

• Local embeddings load model into RAM (~100MB)
• Switch to cloud provider if memory-constrained
• Reduce task count (archive completed tasks)

WSJF scores seem wrong

• Update goal in config to match current focus
• Verify due dates are set correctly
• Check energy level matches your actual state
• Review task dependencies (blocked/blocking)

Development

Run tests

pytest tests/ -v --cov=taskmanager

Current test coverage: 81% (909 passing tests, 23 failing)

To generate HTML coverage report:

pytest --cov=taskmanager --cov-report=html tests/
# Open htmlcov/index.html in browser

Type checking

mypy taskmanager/ --strict

TUI E2E Testing

The project includes comprehensive end-to-end tests for the terminal UI using Textual Pilot. These tests validate real user interactions, keyboard shortcuts, and modal flows.

Prerequisites

Tests use Textual's built-in Pilot testing framework (no external dependencies required).

Run TUI tests

pytest tests/tui_e2e/ -v

Test coverage

• Wizard flow (4-step onboarding)
• Focus mode (timer activation, pause, exit)
• Task CRUD operations (add, complete, delete)
• Keyboard navigation and shortcuts
• Search functionality (semantic search)

CI integration

TUI tests run automatically on every PR via GitHub Actions. See the badge at the top of this README for current test status.

Debugging TUI tests

For detailed TUI testing guidelines, patterns, and debugging tips, see tests/tui_e2e/README.md.

Run locally

python -m taskmanager
# or
vibetasker

Performance Benchmarks

Vibetasker is designed for speed to minimize decision paralysis. Performance targets (tested on 100 tasks):

Operation	Target	Actual	Notes
Task entry	<12s	~10.7s	Includes embedding generation with model loading
WSJF calculation (100 tasks)	<2s	~1.1s	94 tasks/second throughput
Semantic search (100 tasks)	<2s	<0.01s	17,000+ tasks/second throughput
App launch	<3s	<0.01s	Initialization only (not TUI rendering)
WSJF recommendations (100 tasks)	<2s	~1.1s	End-to-end: filter, score, sort
Embedding generation	-	First: ~10s, Subsequent: <0.1s	Model loading on first call

Key findings:

• First task entry includes ~10s model loading time (one-time cost per session)
• Subsequent operations are very fast (<1s for 100 tasks)
• Semantic search is extremely fast due to pre-computed embeddings
• WSJF calculations scale linearly with task count

Run benchmarks:

pytest tests/test_performance.py -v -s

Learning & Adaptation (mem0)

Vibetasker uses mem0.ai to learn from your task completion patterns and improve estimates over time.

What It Learns

After completing 10+ tasks, the system learns:

1. Task Duration Estimates: Actual task durations vs initial estimates

   • Groups tasks by tags (e.g., "coding + python", "docs + writing")
   • Calculates average actual duration for each task type
   • Auto-updates energy_cost estimates for new tasks based on learned patterns

2. Procrastination Patterns: Tasks you repeatedly skip

   • Detects when you view but skip a task 5+ times
   • Helps identify tasks with high activation energy or unclear requirements
   • Suggests breaking down avoided tasks or clarifying requirements

How It Works

from taskmanager.core.energy_learning import record_actual_duration, auto_update_energy_cost
from taskmanager.integrations.learning_engine import LearningEngine

# Initialize learning engine
learning_engine = LearningEngine()

# After completing a task, record actual duration
record_actual_duration(task, actual_minutes=45, learning_engine=learning_engine)

# Auto-update new tasks with learned estimates
auto_update_energy_cost(new_task, learning_engine)

Setup Requirements

mem0 learning requires either:

1. OpenAI API key (recommended): Set OPENAI_API_KEY environment variable
2. Ollama (local): Install Ollama and pull llama3.2:1b model

Without either option, learning features will be disabled (app still works, but no learning).

Validating Learning

Run the validation script to verify mem0 is working:

python validate_mem0_learning.py

This tests:

• Energy learning improves after 10+ completions
• Auto-update applies learned estimates
• Procrastination detection works after repeated skips
• Learning persists across sessions

Privacy

All learning data is stored locally on your machine:

• Default location: ~/.cache/taskmanager/mem0/
• Uses Qdrant vector database for semantic storage
• No data sent to cloud (unless using OpenAI embeddings)
• Can be cleared by deleting the cache directory

Contributing

Contributions welcome! Please:

1. Fork repository
2. Create feature branch
3. Add tests for new features
4. Ensure pytest and mypy --strict pass
5. Submit pull request

License

[Add license here]

Credits

Built with:

• Textual - TUI framework
• sentence-transformers - Semantic embeddings
• Anthropic Claude - AI agents
• Pydantic - Configuration management