Task-scoped control for the real Hubstaff desktop timer on macOS.
hs is a small open-source shell around Hubstaff’s official HubstaffCLI.
It does not spoof Hubstaff, forge activity, or fake screenshots. It only starts the real app when you choose a task, and stops the timer and quits Hubstaff when you’re done—so the client isn’t sitting in the background collecting data with no work running.
Not affiliated with Hubstaff / Netsoft Holdings.
You must already have a legitimate Hubstaff account, the official desktop app, and org permission to use scripted control.
Hubstaff’s desktop client can collect screenshots, app titles, URLs, and input activity while the timer is running. Many people leave the app open all day.
This project makes a simple policy easy:
| Situation | Behavior |
|---|---|
You have a task and start it with hs start |
Real Hubstaff tracks that task |
You run hs stop or have no task |
Timer off + app quit → no collection |
Optional hs guard-bg |
If the app is open without a task timer, auto stop + quit |
- macOS (uses
open,osascript,pgrep) - Hubstaff desktop app installed (default:
/Applications/Hubstaff.app) - Hubstaff account logged in once in the GUI
- Scripted control enabled in Hubstaff Preferences
→ What is scripted control?
Linux/Windows are not supported yet (PRs welcome if you wire the official CLI paths).
brew tap krewdev/tap
brew trust krewdev/tap # required on Homebrew 6+ for third-party taps
brew install hubstaff-work-shell
hs doctorgit clone https://github.com/krewdev/hubstaff-work-shell.git
cd hubstaff-work-shell
./install.shinstall.sh copies bin/hs to ~/bin/hs and ensures ~/bin is on your PATH (zsh/bash).
git clone https://github.com/krewdev/hubstaff-work-shell.git
mkdir -p ~/bin
cp hubstaff-work-shell/bin/hs ~/bin/hs
chmod +x ~/bin/hs
echo 'export PATH="$HOME/bin:$PATH"' >> ~/.zshrc # or ~/.bashrc
source ~/.zshrc- Open Hubstaff and log in.
- Preferences → enable Scripted control / Allow CLI Control.
- Ensure Hubstaff is not set to open at login (or remove it from System Settings → General → Login Items).
- Run:
hs doctor
hs stophs status # is Hubstaff running / collecting?
hs orgs # list organizations
hs projects # list projects
hs projects <org_id> # filter by org
hs tasks <project_id> # list tasks
hs start <task_id> # start real timer on a TASK
# … do the work …
hs stop # stop timer + quit app (no collection)Optional always-on safety net:
hs guard-bg # background watcher
hs guard-stop # stop the watcher| Command | Description |
|---|---|
hs status |
Show tracker status, or report “not running” |
hs orgs |
List organizations via HubstaffCLI |
hs projects [org_id] |
List projects |
hs tasks <project_id> |
List tasks for a project |
hs start <task_id> |
Open app if needed and start timer on a task |
hs start-project <id> |
Start timer on a project only (prefer tasks) |
hs resume |
Resume last project/task |
hs pause |
Stop timer, leave app open |
hs stop |
Stop timer and quit Hubstaff |
hs open |
Open UI without starting the timer |
hs quit |
Quit app only |
hs guard |
Foreground: stop+quit if not on a task |
hs guard-bg |
Same policy in the background |
hs guard-stop |
Stop background guard |
hs doctor |
Diagnose app/CLI/login/scripted control |
hs version |
Print version |
hs help |
Help text |
┌─────────────┐ HubstaffCLI ┌──────────────────────┐
│ hs (shell) │ ───────────────────► │ Hubstaff.app (real) │
└─────────────┘ start_task/stop │ screenshots, apps, │
│ │ URLs only while │
│ hs stop / guard │ TIMER IS RUNNING │
└──── quit Hubstaff ─────────►└──────────────────────┘
- All timer control goes through
HubstaffCLIshipped insideHubstaff.app. hs stopcallsstopthen quits the app so a background agent isn’t left running.hs guardpollsstatus; if tracking without a task (or app open with timer off), it stops and quits.
Config and logs live under:
~/.config/hubstaff-work/
state
guard.pid
hs.log
| Variable | Default | Meaning |
|---|---|---|
HUBSTAFF_APP |
/Applications/Hubstaff.app |
Path to the app bundle |
HUBSTAFF_CLI |
$HUBSTAFF_APP/Contents/MacOS/HubstaffCLI |
Path to CLI binary |
HUBSTAFF_KEEP_OPEN |
0 |
Set to 1 to leave app open after hs stop |
HUBSTAFF_GUARD_INTERVAL |
30 |
Seconds between guard checks |
XDG_CONFIG_HOME |
~/.config |
Base for config directory |
- Not a fake Hubstaff client or activity generator
- Not a way to hide tracking while a timer is running (org policies still apply)
- Not an official Hubstaff product
- Not a substitute for your employment/client agreement—if the org requires continuous tracking, use their rules
While a timer is on, Hubstaff still collects whatever the organization policy allows (screenshots, apps, etc.). This tool only helps you keep the timer off and the app closed when you have no tasks.
rm -f ~/bin/hs
rm -rf ~/.config/hubstaff-work
# remove the PATH line from ~/.zshrc if you added itOptionally remove the clone:
rm -rf /path/to/hubstaff-work-shellgit clone https://github.com/krewdev/hubstaff-work-shell.git
cd hubstaff-work-shell
make check # shellcheck + smoke tests
./bin/hs help
./bin/hs doctor| Target | What it runs |
|---|---|
make check |
ShellCheck + smoke tests |
make smoke |
CLI works without Hubstaff.app |
make install |
Install via install.sh |
CI runs on every push/PR.
See CONTRIBUTING.md. Bug reports and PRs for clearer status parsing, Linux support, and docs are welcome.
- Never commit Hubstaff tokens, session files, or
~/Library/Application Support/Hubstaff/. - This project does not store Hubstaff passwords; it only invokes the local CLI.
- See SECURITY.md for reporting issues.
MIT — free to use, modify, and distribute.
- Hubstaff scripted control / CLI docs
- Hubstaff desktop ships
HubstaffCLI; this project is only a workflow wrapper around it. - privacy-kit — full local macOS privacy audits (
pk audit)