HabitFlow - AI-Powered Atomic Habit Tracker

A clawdbot skill for building lasting habits through natural language interaction, streak tracking with forgiveness, smart reminders, and evidence-based coaching techniques from Atomic Habits.

Features

✅ Natural Language Logging - "I meditated today", "walked Monday and Thursday" ✅ Smart Streak Tracking - 1-day forgiveness mechanism for realistic progress ✅ Canvas Dashboard UI - Streak charts, completion heatmaps, weekly trends, multi-habit overview ✅ Scheduled Reminders - WhatsApp notifications at custom times ✅ Proactive Coaching - Automatic milestone celebrations, risk warnings, weekly check-ins ✅ AI Coaching - Evidence-based techniques from Atomic Habits ✅ 7 AI Coaching Personas - Flex, Coach Blaze, Luna, Ava, Max, Sofi, The Monk ✅ Progress Analytics - Completion rates, trends, best days ✅ Multi-Category Support - Health, fitness, productivity, mindfulness, and more

Installation

Option 1: Workspace Installation (Recommended for Single Gateway)

If you have a dedicated workspace directory for your gateway (e.g., ~/clawd/):

# Install into your workspace
cd ~/clawd/skills  # or wherever your workspace is
git clone https://github.com/tralves/habit-flow-skill.git habit-flow
cd habit-flow
npm install

This gives the skill highest precedence and keeps it specific to this gateway.

Option 2: Shared Installation (For Multiple Agents)

If you want the skill available to all agents on this machine:

# Install to shared directory
mkdir -p ~/.clawdbot/skills
cd ~/.clawdbot/skills
git clone https://github.com/tralves/habit-flow-skill.git habit-flow
cd habit-flow
npm install

Activate the Skill

After installation: "refresh skills" or restart your gateway.

Detailed Installation Guide

See: INSTALL.md for complete installation instructions, troubleshooting, and verification steps.

Quick Start

Create Your First Habit

npx tsx scripts/manage_habit.ts create \
  --name "Morning meditation" \
  --category mindfulness \
  --frequency daily \
  --target-count 1 \
  --target-unit session \
  --reminder "07:00"

Log a Completion

npx tsx scripts/log_habit.ts \
  --habit-id h_abc123 \
  --status completed

View Your Habits

npx tsx scripts/view_habits.ts --active --format markdown

Check Statistics

npx tsx scripts/get_stats.ts --habit-id h_abc123 --period 30

Generate Visual Dashboards

# Streak chart
npx tsx assets/canvas-dashboard.ts streak --habit-id h_abc123
 
# Completion heatmap
npx tsx assets/canvas-dashboard.ts heatmap --habit-id h_abc123 --days 90
 
# Weekly trends
npx tsx assets/canvas-dashboard.ts trends --habit-id h_abc123 --weeks 8
 
# Multi-habit dashboard
npx tsx assets/canvas-dashboard.ts dashboard

Generates GitHub-style calendar heatmaps showing habit completion patterns — perfect for identifying consistency trends and day-of-week patterns.

Natural Language Examples

The skill understands natural language for logging:

"I meditated today"
"Walked 3 miles yesterday"
"I went to the gym Monday, Wednesday, and Friday"
"Forgot to drink water on Tuesday"
"Skipped journaling last week - vacation"

Architecture

Core Technologies

TypeScript/JavaScript - Reused directly from original HabitFlow codebase
Node.js - Native clawdbot environment
JSON/JSONL - Simple, human-readable storage
chrono-node - Natural language date parsing
string-similarity - Fuzzy habit name matching

Directory Structure

~/clawd/skills/habit-flow/
├── SKILL.md                    # Main skill configuration
├── package.json                # Dependencies
├── tsconfig.json               # TypeScript config
├── scripts/                    # CLI scripts
│   ├── log_habit.ts           # Record completions
│   ├── calculate_streaks.ts   # Streak calculation (copied from original)
│   ├── view_habits.ts         # Query and list habits
│   ├── manage_habit.ts        # CRUD operations
│   ├── get_stats.ts           # Statistics and analytics
│   ├── parse_natural_language.ts  # NLP parsing
│   └── sync_reminders.ts      # Cron job management
├── assets/                     # Canvas Dashboard UI
│   ├── canvas-dashboard.ts    # Main CLI entry point
│   ├── components/            # Visualization components
│   ├── utils/                 # Chart rendering utilities
│   └── types/                 # Canvas type definitions
├── src/                        # Shared utilities
│   ├── types.ts               # Type definitions
│   ├── storage.ts             # File I/O
│   ├── daily-completion.ts    # Last log per day logic
│   └── streak-calculation.ts  # Core streak algorithm
├── references/                 # Documentation
│   ├── personas.md            # Persona definitions
│   ├── atomic-habits-coaching.md  # Coaching techniques
│   └── data-schema.md         # Data structure reference
├── examples/                   # Example scripts
│   └── test-canvas.sh         # Test Canvas visualizations
└── assets/                     # Reserved for Phase 2 Canvas UI

Data Storage

~/clawd/habit-flow-data/
├── habits.json              # All habits metadata
├── logs/                    # One JSONL file per habit per year
│   ├── h_abc123_2026.jsonl
│   └── h_def456_2026.jsonl
└── config.json              # User config (timezone, persona)

Scripts Reference

Script	Purpose	Key Options
`manage_habit.ts`	Create/update/archive/delete habits	`create`, `update`, `archive`, `delete`
`log_habit.ts`	Record completions	`--habit-id`, `--date`, `--dates`, `--status`
`view_habits.ts`	Query habits	`--active`, `--archived`, `--search`, `--format`
`calculate_streaks.ts`	Recalculate streaks	`--habit-id`, `--format`, `--update`
`get_stats.ts`	Generate statistics	`--habit-id`, `--all`, `--period`
`parse_natural_language.ts`	Parse natural language	`--text`
`sync_reminders.ts`	Sync reminders to cron	`--sync-all`, `--add`, `--remove`

Streak Calculation

HabitFlow uses a 1-day forgiveness mechanism:

✅ Perfect Streak: No missed days
✅ Excellent Streak: 1-2 forgiveness days used
✅ Good Streak: 3-5 forgiveness days used
⚠️ Fair Streak: More than 5 forgiveness days

Example: If you complete days 1, 2, 3, miss day 4, then complete days 5, 6, 7 - your current streak is 7 days with 1 forgiveness day used.

Coaching Techniques (Atomic Habits)

The skill applies 9 evidence-based coaching techniques:

Minimum Quotas - Start incredibly small (30 seconds of meditation)
Habit Stacking - Link to existing routines ("After coffee, then...")
Reduce Friction - Remove obstacles (lay out workout clothes)
Optimize Timing - Match natural energy levels
Two-Minute Rule - Any habit can start with 2 minutes
Immediate Rewards - Add instant gratification
Temptation Bundling - Pair with pleasures (podcast + walking)
Identify Breakdown Points - Plan for high-risk situations
Reframe and Reflect - Connect to identity ("I AM someone who...")

{
  "activePersona": "coach-blaze"
}

To see your current persona's avatar, ask: "Show me my persona"

Development

Testing

Run individual scripts to test:

# Create a test habit
npx tsx scripts/manage_habit.ts create --name "Test" --category other --frequency daily --target-count 1
 
# Log a completion
npx tsx scripts/log_habit.ts --habit-id <id> --status completed
 
# View results
npx tsx scripts/view_habits.ts --active

Adding New Features

New Script: Create in scripts/ directory
New Utility: Add to src/ directory
Update Types: Modify src/types.ts
Document: Update SKILL.md and this README

Troubleshooting

"command not found: tsx"

Use npx tsx instead of just tsx:

npx tsx scripts/view_habits.ts --active

"Habit with id X not found"

List all habits to find correct ID:

npx tsx scripts/view_habits.ts --active --format json

Natural language parsing low confidence

Be more specific with habit names or dates:

❌ "I did it" (too vague)
✅ "I meditated today" (clear)

Reminders not working

Ensure clawdbot cron is enabled and WhatsApp channel is configured:

npx tsx scripts/sync_reminders.ts --sync-all

Roadmap

Phase 1 (MVP) ✅ COMPLETED

Core habit tracking
Natural language logging
Streak calculation with forgiveness
Basic statistics
Smart reminders
Single AI persona (Flex)

Phase 2 ✅ COMPLETED

All 7 AI coaching personas (Flex, Coach Blaze, Luna, Ava, Max, Sofi, The Monk)
Dynamic persona switching

Phase 3 (In Progress)

Advanced analytics (time-of-day patterns, correlations)
Enhanced atomic habits coaching techniques
Canvas dashboard UI with visualizations

Phase 4 (Future)

Habit templates and bundles
Multi-user bot mode (see docs/MULTI_USER_BOT_MODE.md)
Social features and accountability partners

Credits

Built by reusing and adapting code from the original HabitFlow TypeScript codebase, specifically:

Streak calculation algorithm from libs/shared/calculations/
Type definitions from libs/shared/types/
Coaching techniques from apps/ai-service/src/prompts/
Persona definitions from libs/shared/config/src/lib/personas/

License

Follows the same license as the original HabitFlow project.

Support

For issues or questions:

Check SKILL.md for detailed usage instructions
Review references/ directory for data schemas and coaching techniques
Refer to original HabitFlow documentation for algorithm details