Show HN: Flow – A Command-Line Tool for Deep Work

5 hours ago 2

A Command-Line Tool for Deep Work

Flow is a minimalist command-line tool designed to help you focus on single-tasking by creating a mindful boundary around your work. It emphasizes mindfulness and presence, not productivity metrics.

curl -sSL https://raw.githubusercontent.com/e6a5/flow/main/install.sh | bash

2. Run a Full Session Cycle

# Start a session to focus on a task flow start --tag "Drafting a proposal" # Check your current status flow status # Take a short break flow pause # Resume your work flow resume # End the session when you're done flow end # Review your completed sessions flow log

3. Enable Shell Integration (Optional)

For ambient awareness in your shell prompt:

# For bash users echo 'eval "$(flow completion bash)"' >> ~/.bashrc # For zsh users echo 'eval "$(flow completion zsh)"' >> ~/.zshrc

Mindful Focus: Helps you maintain a single-tasking mindset with one active session at a time
Session Management: Start, pause, resume, and end sessions easily
Session Logging: Automatic tracking of completed sessions for reflection and insights
Shell Integration: Seamlessly integrates with your shell for ambient awareness
Automation Hooks: Customize workflows with session event hooks (on_start, on_pause, on_resume, on_end)
Privacy First: No tracking, no cloud, purely local with XDG-compliant storage
Script Friendly: Raw output mode for integration with other tools

Flow believes in creating a mindful boundary around your work. It's about protecting your attention and engaging deeply with one task at a time. The tool serves your consciousness, not metrics.

Command Description Examples

start [--tag "name"]	Begin a deep work session	flow start --tag "code review"
status [--raw]	Check the current session	flow status or flow status --raw
pause	Take a mindful break	flow pause
resume	Continue working	flow resume
end	Complete the session	flow end
log [flags]	View session history	flow log --today --stats
completion [bash\|zsh]	Generate shell completions	flow completion bash

Flag Description

--today	Show only today's sessions
--week	Show this week's sessions
--stats	Display summary statistics
--all	Show all sessions (no limit)

Examples:

flow log # Recent sessions (last 10) flow log --today # Today's work only flow log --week --stats # This week's statistics flow log --all # Complete history

Quick Install (Recommended)

curl -sSL https://raw.githubusercontent.com/e6a5/flow/main/install.sh | bash

go install github.com/e6a5/flow@latest

Download pre-built binaries from the releases page.

git clone https://github.com/e6a5/flow.git cd flow make build

Flow supports automation hooks that trigger on session events. Create executable scripts in ~/.config/flow/hooks/:

on_start - Triggered when starting a session
on_pause - Triggered when pausing a session
on_resume - Triggered when resuming a session
on_end - Triggered when ending a session

Each hook receives the session tag as its first argument.

Example hook (~/.config/flow/hooks/on_start):

#!/bin/bash echo "Starting work on: $1" | notify-send "Flow"

Flow follows XDG Base Directory standards:

Session data: $XDG_DATA_HOME/flow/session (default: ~/.local/share/flow/session)
Session logs: $XDG_DATA_HOME/flow/logs/YYYYMM_sessions.jsonl (default: ~/.local/share/flow/logs/202507_sessions.jsonl)
Hooks: $XDG_CONFIG_HOME/flow/hooks/ (default: ~/.config/flow/hooks/)
Custom session path: Set FLOW_SESSION_PATH environment variable
Custom log path: Set FLOW_LOG_PATH environment variable

We welcome contributions! Please see CONTRIBUTING.md for guidelines. This is a tool for mindful computing that serves consciousness.

MIT License - see the LICENSE file for details.

One thing at a time. Runs offline. Powered by presence.

Read Entire Article