Focus

A simple command-line utility to track, manage, and sync your focused programming sessions.

focus is designed to help you build and maintain the habit of deep work. It allows you to start a timer for a session, attach descriptive tags or session names, and later view the history and duration of your sessions. It also supports syncing your focus history to a GitHub Gist, acting as a cloud backup and a single source of truth for your deep work stats.

You can build and install the tool using go:

go build -o focus .
# Move the executable to a directory in your PATH (e.g., /usr/local/bin/)
mv focus /usr/local/bin/

By default, the tool will automatically create a configuration directory at ~/.config/focus/ and store its state in state.json.

Start a new focus session. You can optionally add a session name, description, and comma-separated tags.

focus start -n "Refactoring" -d "Cleaning up architecture" -t "golang,refactor"

Ends the currently active session and saves the total duration to your state.

focus stop

Displays the details of your currently active session and lists all your past session history.

focus status

Syncs your local focus state (state.json) with your configured GitHub Gist.

focus sync

To enable syncing your focus state with a GitHub Gist, create a .env file in the directory from which you run the command or add the following environment variables to your shell profile:

• GITHUB_GIST_PAT: Your GitHub Personal Access Token (requires Gist permissions).
• FOCUS_STATE_GIST_ID: The unique ID of the Gist where your state will be synced.
• FOCUS_STATE_GIST_FILE_NAME: The filename inside the Gist to save the data under.