@datasolace/oath

Oath

A beautiful terminal app for tracking accountability tasks with automated verification scripts, streaks, and analytics.

Also a primary test project for Claude Code - so beware there will be vibe coding ahead... 🙃

Features

• ✅ Create and manage accountability tasks
• 📊 Interactive Dashboard with productivity insights and analytics
• 🗃️ SQLite backend for robust data persistence
• 🔥 Track completion streaks and habit patterns
• 🔍 Run verification scripts to confirm task completion
• 🎨 Beautiful terminal UI built with Ink and React
• 📈 GitHub-style activity graphs and performance visualizations
• 💾 Automatic database backups with configurable retention

Installation

From npm (Recommended)

Install globally to use the oath command anywhere:

npm install -g @datasolace/oath

Then run:

oath

From Source

Clone and build locally:

git clone https://github.com/DataSolace/oath.git
cd oath
pnpm install
pnpm build

Getting Started

Launch the interactive terminal app:

# If installed globally
oath

# If running from source
pnpm start

This opens a beautiful full-screen interface where you can manage everything through an intuitive menu system.

Main Menu Navigation

Use arrow keys to navigate or press hotkeys for quick access:

• [L]ist Tasks - View and manage your accountability tasks
• [A]dd New Task - Create a new task with categories, frequency, and optional verification scripts
• [D]ashboard - View comprehensive analytics and insights
• [S]ettings - Configure app preferences and manage data
• [X] - Exit the app (works from anywhere)

Task Management

In the task list view:

• Use arrow keys to select tasks
• Press Enter to mark a task as complete
• Press [V] to run verification scripts
• Press [D] to delete tasks
• Your completion streaks update automatically! 🔥

Analytics Dashboard

Press [D] from the main menu to access analytics:

• [O]verview - Performance summary and consistency scores
• [C]ategories - See which task types you're excelling at
• [S]treaks - Track your consecutive completion records
• [P]atterns - Discover your most productive days

Settings

Press [S] from the main menu to access:

• Activity Graph Period - Configure how many months to display (1, 3, 6, or 12)
• Backup Settings - Manage database backup retention and policies
• Profile Management - Edit your name/email or regenerate your ASCII avatar
• Data Management - Reset progress, delete tasks, or remove your profile
  • Reset Progress: Clear completions and streaks, keep tasks
  • Delete All Tasks: Remove all tasks but keep your profile
  • Delete Profile: Remove everything and exit (creates backup first)

Example Tasks

The project includes example verification scripts in example-scripts/:

• daily-commits.sh - Checks if you made git commits today
• exercise-tracker.sh - Interactive exercise completion tracker

Data Storage

All your data is stored locally in ~/.oath/:

• oath.db - SQLite database with your profile, tasks, and completion history
• backups/ - Automatic and manual database backups

The app automatically:

• Creates backups before database migrations
• Creates backups before destructive operations (profile deletion, resets)
• Maintains configurable retention policies (default: keep last 10 manual, 5 auto backups)

Database Backups

Manage backups through the interactive UI:

Access: Settings → Backup Settings

Or use CLI commands:

pnpm backup:create [optional-label]   # Create a manual backup
pnpm backup:list                       # List all backups
pnpm backup:restore <filename>         # Restore from a backup
pnpm backup:config                     # View/update retention settings

See docs/BACKUPS.md for detailed backup documentation.

Creating Verification Scripts

Verification scripts should:

• Exit with code 0 for success
• Exit with code 1 for failure
• Output meaningful messages to stdout
• Be executable (chmod +x script.sh)

Example script:

#!/bin/bash
if [ some_condition ]; then
    echo "Task completed successfully!"
    exit 0
else
    echo "Task not completed"
    exit 1
fi

Features In Detail

Analytics & Insights

The analytics dashboard provides comprehensive insights into your productivity:

• 📈 GitHub-style Activity Graph - Visual heatmap of completion history (adjustable period: 1-12 months)
• 🔥 Streak Tracking - Monitor consecutive completion streaks and all-time bests
• 📊 Category Performance - Completion rates and averages by task type
• 📉 Pattern Analysis - Discover your most productive days and weekly trends
• ⚡ Consistency Scoring - Measure habit formation strength

Navigate between views using hotkeys: [O]verview, [C]ategories, [S]treaks, [P]atterns

Verification Scripts

Automate task completion verification by attaching shell scripts to tasks. Scripts should:

• Exit with code 0 for success, 1 for failure
• Output meaningful messages to stdout
• Be executable (chmod +x script.sh)

Example: Check if you made git commits today, tracked exercise, or completed any automated task.

See example-scripts/ for working examples.

Development

If you're contributing to the project:

# Run in development mode
pnpm dev

# Run interactive mode in development
pnpm dev interactive

# Build for production
pnpm build

# Run tests
pnpm test

# Type check
pnpm typecheck