In a world of constant distraction, your attention is a superpower. Flow is a minimalist command-line tool that helps you protect it. It's for developers, writers, and anyone who wants to build a deep work habit without leaving the terminal.
Flow is built on a few core principles that guide its design and purpose.
-
Mindful Focus, Not Just Time Tracking. Flow isn't about logging hours for a timesheet. It's about creating a ritual around deep work, helping you build the habit of single-tasking.
-
Your Terminal is Your Sanctuary. Deep work happens when you eliminate distractions. Flow lives in the command line, your most focused environment, preventing the context-switching required by GUI apps.
-
Your Data is Yours. Period. Flow is private by default. It works offline, requires no account, and stores all your data in simple, local text files. You have complete control.
-
Compose Your Perfect Workflow. Flow embraces the Unix philosophy. It's a simple, powerful tool that can be scripted and combined with others. Use its hooks to integrate with your existing setup.
-
Install Flow:
curl -sSL https://raw.githubusercontent.com/e6a5/flow/main/install.sh | bash -
Start your first session:
flow start --tag "My first deep work session" -
Check your progress:
flow status
-
End when complete:
flow end
Flow is designed to be intuitive. Here's how a typical session works:
-
Start a session when you're ready to focus. Give it a tag and a target duration.
flow start --tag "Writing the first draft" --target 2h -
Check your status at any time to see your progress.
flow status > 🌊 Deep work: Writing the first draft (Active for 45m) / 2h 0m (1h 15m remaining)
-
End the session when the work is complete. Your focus time is automatically logged.
flow end > ✨ Session complete: Writing the first draft > Total focus time: 2h 5m
-
Review your day and find your patterns.
flow recent flow insights
-
Clean up if needed - Remove any test sessions or mistakes.
flow delete
curl -sSL https://raw.githubusercontent.com/e6a5/flow/main/install.sh | bashThe installer will add the flow binary to /usr/local/bin and check for necessary dependencies.
For other installation methods (Go, manual), see the Installation Guide.
| Command | Description |
|---|---|
start [--tag ""][--target ""] |
Begin a deep work session with an optional target duration. |
status [--raw] |
Check the current session status. |
pause |
Pause the active session. |
resume |
Resume a paused session. |
end |
Complete the session and log it. |
delete |
Interactively delete a session from your log. |
💡 Tip: After ending a session, if you made a mistake, you can immediately run
flow deleteto remove it!
🛡️ Stale Session Protection: If you forget to end a session and it runs for over 8 hours (configurable), Flow will automatically detect and clean it up when you start a new session. The abandoned session will be logged with an [ABANDONED] tag for your records.
| Command | Description |
|---|---|
log [flags] |
View completed session history. See flow log --help for flags. |
recent |
Show a summary of today's completed sessions. |
dashboard |
Show a yearly contribution graph of your focus sessions. |
insights |
Analyze your work history to see patterns like your busiest day. |
export [flags] |
Export session data to CSV or JSON. See flow export --help for flags. |
| Command | Description |
|---|---|
completion [bash|zsh] |
Generate shell completion scripts. |
You can extend Flow to fit your unique workflow using hooks and environment variables.
- Automation Hooks: Trigger custom scripts on session events.
- Configuration: Customize storage paths using environment variables.
For detailed information, see the Customization Guide.
Flow is built for the community, and we welcome contributions! Whether it's a bug report, a feature request, or a pull request, we'd love to hear from you. Please see our Contributing Guidelines to get started.
Flow is open-source software licensed under the MIT License.
One thing at a time. Runs offline. Powered by presence.