Skip to content

Flow CLI

See More

Version License Tests Docs Pure ZSH ADHD-Friendly

ZSH workflow tools designed for ADHD brains.

Start working in 10 seconds. Stay motivated with visible wins.

⚡ Get Started in 30 Seconds

brew tap data-wise/tap && brew install flow-cli
work my-project         # Start session
win "installed flow!"   # Log your first win
That's it! No configuration required.

New here? setup walks you through configuration interactively, or run tutorial for 12 hands-on lessons at your own pace — both are guided, no docs required to start.

🎉 What's New in v7.16.0

agy (Antigravity CLI) added as an em-ai backend — ahead of gemini (now legacy) in the fallback chain, with automatic output cleaning and validation. em flag/em star bug fixed — a dead-code dispatch bug silently made em flag behave differently than intended; em star now also supports multiple IDs. em help <topic> — filter help to one section instead of scanning the full command reference. Full details → Changelog.

⚡ See It in Action

The entire workflow in 3 commands:

work my-project    # Start session
win "Fixed bug"    # Log win → dopamine hit
finish             # Done

Expected output:

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

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

$ finish
✅ Session complete
   💾 Changes saved

Everything else is optional enhancement

These 3 commands are the core. Dispatchers (cc, r, qu, teach), dopamine tracking (yay, flow goal), and advanced features are bonuses.

📺 Demo GIF

flow-cli demo

🎯 What Problem Does This Solve?

ADHD Challenge flow-cli Solution
"Where was I?" why → shows context
"What should I work on?" dash → shows priorities
No visible progress win → logs accomplishments
Context switching hurts hop → instant switch
Starting is hard work → removes friction

🏆 Built-in Dopamine System

Every win gets categorized and tracked:

win "Fixed login bug"       # → 🔧 fix
win "Deployed to prod"      # → 🚀 ship
win "Added tests"           # → 🧪 test

See your progress:

yay              # Recent wins
yay --week       # Weekly graph
flow goal        # Daily progress (🌱🔥🔥🔥 streaks!)

→ Learn about dopamine features

📦 Installation

brew tap data-wise/tap
brew install flow-cli
No shell config needed! Commands work immediately. 
antidote install data-wise/flow-cli

zinit light data-wise/flow-cli

git clone https://github.com/data-wise/flow-cli.git \
  ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/flow-cli
# Add 'flow-cli' to plugins array in .zshrc

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

Verify installation: flow doctor

🧭 Next Steps

Three questions, pick the one that matches where you are — not eight options at once.

🆕 New here?

🔧 Solve a specific problem

📚 Already using it? Look something up

  • 🧭 Command Reference

    Quick lookup for all commands — also try ref in your terminal

    → Reference

  • 📆 Daily & Weekly Cookbook

    Copy-paste routines for the two cadences flow-cli is built around

    → Cookbook

🔌 Command Architecture

Smart Dispatchers

Commands that adapt to your project type:

Dispatcher Example What it does
cc cc / cc pick Launch Claude Code (here or picker)
r r test / r check R package development
qu qu preview / qu render Quarto publishing
g g push / g commit Git with smart safety
teach teach init / teach deploy Teaching workflow
mcp mcp status / mcp logs MCP server management
wt wt create / wt status Worktree management
tm tm title / tm ghost Terminal manager
dots dots edit / dots sync Dotfile management
sec sec add / sec list Secret management
tok tok github / tok rotate Token management
prompt prompt toggle Prompt engine switcher
v v on / v status Vibe coding mode
em em inbox / em pick / em forward Email: 38 commands (read, reply, forward, AI, organize, manage)

Get help: <dispatcher> help (e.g., r help, teach help)

→ Complete dispatcher guide

Core Session Commands

work <project>    # Start session
finish [note]     # End session
hop <project>     # Quick switch (tmux)
dash              # Dashboard (what's happening now)
agenda            # What's due soon (deadlines, exams, milestones)
catch "idea"      # Quick capture
ref               # Quick-reference card (forgot the syntax? this is faster than docs)

→ All commands

🧠 Design Philosophy

Built for ADHD Brains

Principle Implementation
Sub-10ms response No waiting = no frustration
Smart defaults Works without configuration
Visible progress Dopamine from seeing wins
Consistent patterns Less to memorize
Forgiving Hard to break things

→ Read full philosophy

v7.16.0 · Pure ZSH · Zero Dependencies · MIT License