flow-cli

ZSH workflow tools designed for ADHD brains. Start working in 10 seconds. Stay motivated with visible wins.

---

⚡ 10-Second Start

# 1. Install
antidote install data-wise/flow-cli   # or: zinit light data-wise/flow-cli

# 2. Work
work my-project    # Start session
win "Fixed bug"    # Log win → get dopamine
finish             # Done for now

That's it. Everything else is optional.

📺 See it in action (click to expand)

Or try the commands yourself:

$ work my-project
🚀 Starting session: my-project
   📍 ~/projects/my-project

$ win "Fixed the login bug"
🔧 fix: Fixed the login bug
   ✨ Win #1 today!

$ win "Added unit tests"
🧪 test: Added unit tests
   ✨ Win #2 today!

$ yay
╭──────────────────────────────────────╮
│ 🏆 Today's Wins (2)                 │
├──────────────────────────────────────┤
│ 🔧 Fixed the login bug              │
│ 🧪 Added unit tests                 │
╰──────────────────────────────────────╯
   🔥 2-day streak!

$ finish
✅ Session complete (47 min, 2 wins)

---

🎯 Why This Exists

ADHD Challenge	flow-cli Solution
"Where was I?"	why shows your context
"What should I do?"	dash shows priorities
No visible progress	win logs accomplishments
Context switching pain	hop instant project switch
Starting is hard	work removes friction
Multiple devices	flow sync keeps wins synced

---

🚀 Core Commands

Start & Stop

work myproject     # Start working (creates session)
finish "done X"    # End session (optional commit)
hop other          # Quick switch (tmux)

Stay Motivated

win "Fixed the bug"     # Log accomplishment → 🔧 fix
win "Deployed v2"       # Log accomplishment → 🚀 ship
yay                     # See your wins
flow goal set 3         # Daily target

Stay Oriented

dash           # What's happening?
why            # Where was I?
pick           # Choose a project

---

🧠 ADHD-Friendly Features

🏆 Dopamine Hits

Every win gives you a category and emoji:

• 💻 code - "Implemented feature"
• 🔧 fix - "Fixed that bug"
• 🚀 ship - "Deployed to prod"
• 📝 docs - "Updated README"
• 🧪 test - "Added tests"

🔥 Streak Tracking

Day 1: work → 🌱 1 day
Day 3: work → 🔥 3 days - On a roll!
Day 7: work → 🔥🔥 Strong week!

📊 Dashboard

dash              # Quick overview
dash -i           # Interactive picker
dash --watch      # Live updates

☁️ Multi-Device Sync (v4.7.0)

Sync your wins and goals across devices via iCloud:

flow sync remote init    # Set up once
flow sync                # Auto-sync daily

Works offline, syncs when connected. Zero config after setup.

---

🔌 Smart Dispatchers

Context-aware commands that adapt to your project:

Command	What it does
cc	Launch Claude Code here
cc pick	Pick project → Claude
cc pick opus ✨	Pick → Opus (natural order!)
dot	Manage dotfiles & secrets
dot edit .zshrc	Edit dotfile with preview
r test	Run R package tests
qu preview	Preview Quarto doc
g push	Git push with safety
flow sync	Sync data across devices

Each dispatcher has built-in help: cc help, dot help, r help, etc.

✨ New in v4.8.0: Unified grammar - both cc opus pick AND cc pick opus work identically! ✨ New in v5.0.0: Dotfile management with dot dispatcher

---

📦 Installation

Homebrew (Recommended for macOS)

# Tap the repository
brew tap data-wise/tap

# Install flow-cli
brew install flow-cli

That's it! Homebrew handles everything. No plugin manager needed.

Alternative: Quick Install Script

curl -fsSL https://raw.githubusercontent.com/Data-Wise/flow-cli/main/install.sh | bash

Auto-detects your plugin manager and installs accordingly.

Install specific version:

FLOW_VERSION=v4.8.0 curl -fsSL https://raw.githubusercontent.com/Data-Wise/flow-cli/main/install.sh | bash

Installation Methods Comparison

Method	Command	Best For
Homebrew	brew tap data-wise/tap && brew install ...	macOS users ⭐
Quick Install	curl -fsSL .../install.sh | bash	Auto-detection
Antidote	Add Data-Wise/flow-cli to .zsh_plugins.txt	Antidote users
Zinit	zinit light Data-Wise/flow-cli	Zinit users
Oh-My-Zsh	Clone to $ZSH_CUSTOM/plugins/	OMZ users
Manual	git clone + source	Full control

📋 Manual installation commands

Antidote:

echo "Data-Wise/flow-cli" >> ~/.zsh_plugins.txt
antidote update

Zinit:

zinit light Data-Wise/flow-cli

Oh-My-Zsh:

git clone https://github.com/Data-Wise/flow-cli.git \
  ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/flow-cli
# Then add 'flow-cli' to plugins=(...) in ~/.zshrc

Manual:

git clone https://github.com/Data-Wise/flow-cli.git ~/.flow-cli
echo 'source ~/.flow-cli/flow.plugin.zsh' >> ~/.zshrc

Verify Installation

flow doctor        # Health check

Uninstall

curl -fsSL https://raw.githubusercontent.com/Data-Wise/flow-cli/main/uninstall.sh | bash

---

✅ Testing

Interactive dog feeding test (yes, really):

./tests/interactive-dog-feeding.zsh

• 🐕 Feed a virtual dog by confirming commands work
• ⭐ Earn 1-5 stars
• 👀 See expected output before running

---

⚙️ Configuration

# In .zshrc (before sourcing plugin)
export FLOW_PROJECTS_ROOT="$HOME/projects"  # Where your projects live
export FLOW_QUIET=1                         # Skip welcome message

---

📚 Documentation

• Quick Start - 5 minutes
• Dopamine Features - Win tracking
• Sync Command - Multi-device sync
• All Commands - Reference

---

🤝 Philosophy

1. Instant response - Sub-10ms, no waiting
2. Smart defaults - Works without config
3. Visible progress - See your wins
4. Low friction - Start working fast

---

License: MIT Docs: data-wise.github.io/flow-cli