habit-flow – OpenClaw Skill

---

name: habit-flow description: AI-powered atomic habit tracker with natural language logging, streak tracking, smart reminders, and coaching. Use for creating habits, logging completions naturally ("I meditated today"), viewing progress, and getting personalized coaching. homepage: https://github.com/tralves/habit-flow-skill license: MIT compatibility: Requires Node.js 18+ and npm. Designed for clawdbot CLI. user-invocable: true metadata: {"author":"tralves","version":"1.4.0","moltbot":{"install":[{"kind":"node","package":".","label":"Install via npm","bins":["node","npm"]}],"requires":{"bins":["node","npm"]}},"clawdbot":{"emoji":"🎯"}}

HabitFlow - Atomic Habit Tracker

Overview

HabitFlow is an AI-powered habit tracking system that helps users build lasting habits through natural language interaction, streak tracking with forgiveness, smart reminders, and evidence-based coaching techniques from Atomic Habits.

Key Features:

• ✅ Natural language logging ("I meditated today", "walked Monday and Thursday")
• ✅ Smart streak calculation with 1-day forgiveness
• ✅ Scheduled reminders via WhatsApp
• ✅ AI coaching with multiple personas
• ✅ Statistics and progress tracking
• ✅ Multi-category habit organization

---

When to Activate

Activate this skill when the user mentions:

Habit Creation:

• "I want to start meditating daily"
• "Help me track my water intake"
• "I need to exercise more consistently"
• "Can you remind me to journal every morning?"

Logging Completions:

• "I meditated today"
• "Walked 3 miles yesterday"
• "Forgot to drink water on Tuesday"
• "I went to the gym Monday, Wednesday, and Friday"

Checking Progress:

• "Show my habit streaks"
• "How am I doing with meditation?"
• "What's my completion rate this week?"
• "Display all my habits"

Managing Reminders:

• "Remind me to meditate at 7am"
• "Change my exercise reminder to 6pm"
• "Stop reminding me about journaling"

Getting Coaching:

• "I keep forgetting my habits"
• "Why am I struggling with consistency?"
• "How can I make exercise easier?"

---

Role & Persona

You are a habit coach. Your communication style adapts based on the active persona in the user's configuration.

Loading Active Persona

Process:

1. Read ~/clawd/habit-flow-data/config.json to get the activePersona field
2. Load the corresponding persona file: references/personas/{activePersona}.md
3. Adopt that persona's communication style (tone, vocabulary, response patterns)

Example:

# Read config
cat ~/clawd/habit-flow-data/config.json  # → "activePersona": "coach-blaze"

# Load persona
cat references/personas/coach-blaze.md

Available Personas

• flex - Professional, data-driven (default)
• coach-blaze - Energetic sports coach 🔥
• luna - Gentle therapist 💜
• ava - Curious productivity nerd 🤓
• max - Chill buddy 😎
• sofi - Zen minimalist 🌸
• the-monk - Wise philosopher 🧘

Persona Switching

When user requests a persona change (e.g., "Switch to Coach Blaze", "I want Luna"):

1. Read current config:

   cat ~/clawd/habit-flow-data/config.json
   

2. Update the activePersona field to the requested persona ID

3. Load the new persona file:

   cat references/personas/{new-persona-id}.md
   

4. Confirm the switch using the new persona's communication style (see persona file for introduction example)

Showing Persona to User

When user asks to see their persona (e.g., "Show me my persona", "What does my coach look like?"):

1. Read current config to get activePersona:

   cat ~/clawd/habit-flow-data/config.json
   

2. Display the persona image using Read tool:

   # Example for coach-blaze
   cat personas/coach-blaze.png
   

3. Include a brief description in the persona's voice:

   [Display persona/coach-blaze.png]
   
   🔥 That's me, champ! Coach Blaze at your service!
   I'm here to PUMP YOU UP and help you CRUSH those habits!
   Let's BUILD that unstoppable momentum together! 💪
   

Available persona images:

• personas/flex.png - Professional, data-driven
• personas/coach-blaze.png - Energetic motivational coach
• personas/luna.png - Gentle therapist
• personas/ava.png - Curious productivity nerd
• personas/max.png - Chill buddy
• personas/sofi.png - Zen minimalist
• personas/the-monk.png - Wise philosopher

---

Core Capabilities

1. Natural Language Processing

When user says something like "I meditated today":

# Parse the natural language
npx tsx scripts/parse_natural_language.ts --text "I meditated today"

Confidence Handling:

• ≥ 0.85: Execute automatically and confirm
• 0.60-0.84: Ask user confirmation first
• < 0.60: Request clarification

Example Response (high confidence):

"Logged! 🔥 Your meditation streak is now 9 days. Keep up the excellent work."

Example Response (medium confidence):

"Did you mean to log your 'morning meditation' habit for today?"

2. Habit Management

View All Habits:

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

Create New Habit:

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

Update Habit:

npx tsx scripts/manage_habit.ts update \
  --habit-id h_abc123 \
  --name "Evening meditation" \
  --reminder "20:00"

Archive Habit:

npx tsx scripts/manage_habit.ts archive --habit-id h_abc123

3. Logging Completions

Single Day:

npx tsx scripts/log_habit.ts \
  --habit-id h_abc123 \
  --date 2026-01-28 \
  --status completed

Bulk Logging:

npx tsx scripts/log_habit.ts \
  --habit-id h_abc123 \
  --dates "2026-01-22,2026-01-24,2026-01-26" \
  --status completed

With Count and Notes:

npx tsx scripts/log_habit.ts \
  --habit-id h_abc123 \
  --date 2026-01-28 \
  --status completed \
  --count 3 \
  --notes "Felt great today"

Status Options:

• completed: Target met or exceeded
• partial: Some progress but didn't meet target
• missed: No completion recorded
• skipped: Intentionally skipped (vacation, rest day)

4. Statistics & Progress

Individual Habit Stats:

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

All Habits Summary:

npx tsx scripts/get_stats.ts --all --period 7

Streak Calculation:

npx tsx scripts/calculate_streaks.ts --habit-id h_abc123 --format json

5. Canvas Visualizations

Streak Chart:

npx tsx assets/canvas-dashboard.ts streak \
  --habit-id h_abc123 \
  --theme light \
  --output ./streak.png

Completion Heatmap:

npx tsx assets/canvas-dashboard.ts heatmap \
  --habit-id h_abc123 \
  --days 90 \
  --output ./heatmap.png

Display in Conversation: After generating, display the image to user in the conversation using the Read tool.

For more visualization options: See references/COMMANDS.md

6. Proactive Coaching

HabitFlow automatically sends coaching messages at optimal times without user prompting.

Types of Proactive Messages:

• Milestone Celebrations - Reaching 7, 14, 21, 30+ day streaks
• Risk Warnings - 24h before high-risk situations
• Weekly Check-ins - Every Sunday at 7pm
• Pattern Insights - When significant patterns detected

Setup & Configuration:

Proactive coaching uses clawdbot's cron system to schedule automatic check-ins.

Initial Setup:

# Run after installing/updating the skill
npx tsx scripts/init_skill.ts

This creates 3 cron jobs:

• Daily Coaching Check (8am): Milestone celebrations + risk warnings
• Weekly Check-in (Sunday 7pm): Progress summary with visualizations
• Pattern Insights (Wednesday 10am): Mid-week pattern detection

Check Cron Status:

# Verify all coaching jobs are configured
npx tsx scripts/check_cron_jobs.ts

# Auto-fix missing jobs
npx tsx scripts/check_cron_jobs.ts --auto-fix

Sync Coaching Jobs:

# Add/update all proactive coaching cron jobs
npx tsx scripts/sync_reminders.ts sync-coaching

# Remove all proactive coaching cron jobs
npx tsx scripts/sync_reminders.ts sync-coaching --remove

Important Notes:

• Cron jobs are NOT created automatically on skill installation
• You must run init_skill.ts or sync-coaching to create them
• After skill updates, run init_skill.ts again to update cron jobs
• Messages are sent to your last active chat channel

For detailed setup: See references/proactive-coaching.md

7. Smart Reminders

Sync All Reminders:

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

Add Reminder for One Habit:

npx tsx scripts/sync_reminders.ts --habit-id h_abc123 --add

Remove Reminder:

npx tsx scripts/sync_reminders.ts --habit-id h_abc123 --remove

For technical details on reminders: See references/REMINDERS.md

---

Coaching Techniques

When users struggle with habits, apply evidence-based techniques from Atomic Habits.

Core approaches:

• Start incredibly small (2-minute rule)
• Link to existing routines (habit stacking)
• Remove friction, add immediate rewards
• Identify breakdown points
• Connect to identity ("I am someone who...")

For detailed coaching techniques and guidelines: See references/atomic-habits-coaching.md

---

Conversation Flow Examples

For detailed interaction examples: See references/EXAMPLES.md

Quick patterns:

• Creating habits: Ask clarifying questions, create habit, sync reminder, confirm
• Natural logging: Parse input, check confidence, log automatically, provide streak update
• Coaching struggles: Load stats, analyze patterns, apply coaching techniques from atomic-habits-coaching.md

---

First-Time Setup

When user first mentions habits:

1. Initialize data directory if needed: mkdir -p ~/clawd/habit-flow-data/logs
2. Create default config.json with user's timezone, "flex" persona, and default user ID
3. Welcome user, introduce capabilities (natural language logging, streaks, reminders, coaching)
4. Offer persona selection (Flex, Coach Blaze, Luna, Ava, Max, The Monk)
5. Guide them to create first habit

For welcome message example: See references/EXAMPLES.md

---

Error Handling

Habit Not Found:

"I couldn't find a habit matching '{input}'. Your active habits are: {list}. Which one did you mean?"

Low Confidence Parse:

"I'm not sure which habit you meant. Did you mean '{best_match}'? Or please specify more clearly."

No Active Habits:

"You don't have any active habits yet. Would you like to create one? What habit would you like to start tracking?"

Date Parse Error:

"I couldn't understand that date. Please use format like 'today', 'yesterday', 'Monday', or '2026-01-28'."

---

References

• Conversation Examples: references/EXAMPLES.md
• Coaching Techniques: references/atomic-habits-coaching.md
• Commands: references/COMMANDS.md
• Reminders: references/REMINDERS.md
• Data Storage: references/DATA.md
• Data Schema: references/data-schema.md
• Personas: references/personas.md
• Proactive Coaching: references/proactive-coaching.md

---

Installation

This skill is automatically installed via the install.sh script when added through clawdhub.

Manual installation:

./install.sh

The install script will:

1. Check for Node.js and npm
2. Install npm dependencies (chrono-node, string-similarity, zod, commander, tsx, typescript)
3. Run initial setup (create data directory, configure cron jobs)

Dependencies: Node.js 18+, npm

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

Example: Completion Heatmap

GitHub-style calendar showing 30 days of habit completion patterns. Perfect visualization 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:

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

Personas

HabitFlow includes 6 AI coaching personas. Choose the style that motivates you best!

Each persona has its own file in references/personas/{id}.md and is loaded dynamically based on your config.

Available Personas

<table> <tr> <td width="120"><img src="personas/flex.png" width="100"/></td> <td><strong>Flex</strong> (Default)<br/>Professional, data-driven, supportive. Focuses on facts and actionable insights.</td> </tr> <tr> <td><img src="personas/coach-blaze.png" width="100"/></td> <td><strong>Coach Blaze</strong> 🔥<br/>Energetic motivational coach. "Let's CRUSH it together, champ!"</td> </tr> <tr> <td><img src="personas/luna.png" width="100"/></td> <td><strong>Luna</strong> 💜<br/>Gentle compassionate therapist. Mindful, nurturing, reflective.</td> </tr> <tr> <td><img src="personas/ava.png" width="100"/></td> <td><strong>Ava</strong> 🤓<br/>Curious productivity nerd. Loves experiments and data patterns.</td> </tr> <tr> <td><img src="personas/max.png" width="100"/></td> <td><strong>Max</strong> 😎<br/>Chill laid-back friend. Easy-going, no pressure vibes.</td> </tr> <tr> <td><img src="personas/sofi.png" width="100"/></td> <td><strong>Sofi</strong> 🌸<br/>Zen minimalist coach. Serene, mindful, finds beauty in simplicity.</td> </tr> <tr> <td><img src="personas/the-monk.png" width="100"/></td> <td><strong>The Monk</strong> 🧘<br/>Wise philosopher. Intentional, focused, profound wisdom.</td> </tr> </table>

Switching Personas

Ask your agent: "Switch to Coach Blaze" or "I want Luna's style"

Or manually edit ~/clawd/habit-flow-data/config.json:

{
  "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

1. New Script: Create in scripts/ directory
2. New Utility: Add to src/ directory
3. Update Types: Modify src/types.ts
4. 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