whoson

Early warning when teammates are working on the same files — before merge conflicts happen.

No server. No database. Just git.

⚠ Heads up! budi is already working on this file
  Started: 2 hours ago
  Branch: feature/payment-v2
Continue anyway? (y/n)

How it works

whoson stores active session data inside git notes on the latest commit (refs/notes/whoson). Notes travel with git push and git fetch — so your whole team stays in sync automatically, using the git remote you already have.

Install

npm install -g whoson

Or as a devDependency in your project (recommended for teams):

npm install --save-dev whoson

Or try without installing:

npx whoson --help

Requires Node.js 18+

Quick start

# 1. One-time setup
whoson init

# 2. Before you start working on a file
whoson start src/screens/PaymentScreen.tsx

# 3. Check who's working on what
whoson status

# 4. When you're done
whoson done src/screens/PaymentScreen.tsx

Commands

whoson init

One-time setup. Saves your name and email to ~/.config/whoson/config.json.

whoson init
# What's your name? age
# ✓ Config saved to ~/.config/whoson/config.json

whoson start <file>

Mark that you're starting work on a file. Warns if someone else is already on it.

whoson start src/screens/PaymentScreen.tsx

# If clear:
# ✓ Marked as working on PaymentScreen.tsx

# If conflict:
# ⚠ Heads up! budi is already working on this file
#   Started: 2 hours ago
#   Branch: feature/payment-v2
# Continue anyway? (y/n)

# If session might be stale:
# ⚠ raka was working on this file
#   Started: 6 hours ago  (might be stale)
#   Branch: fix/formatting

whoson done [file]

Mark a file as done when you're finished. Moves the session to history.

whoson done src/screens/PaymentScreen.tsx

# Mark all your active sessions as done at once
whoson done --all

whoson status

Show who's currently working on what.

whoson status
whoson status --max-age 4h    # only sessions started in last 4 hours
whoson status --max-age 1d    # only sessions from last 1 day

# Output:
# Active sessions:
# age    src/screens/PaymentScreen.tsx   (feature/payment-v2)  — 1 hour ago
# budi   src/components/Button.tsx        (fix/button-style)    — 30 min ago
#
# Stale sessions (might be old):
# raka   src/utils/format.ts              (fix/formatting)      — 6 hours ago  ⚠ might be stale

whoson log

Show recent activity history.

whoson log                    # use logWindow from config (default: 7d)
whoson log --since 2d         # last 2 days
whoson log --since 6h         # last 6 hours
whoson log --file src/screens/PaymentScreen.tsx   # filter by file

# Output:
# Activity (last 2 days):
# age    started   src/screens/PaymentScreen.tsx   2 hours ago
# budi   done      src/components/Button.tsx        5 hours ago
# age    done      src/screens/PaymentScreen.tsx    1 day ago

whoson sync

Manually push/pull notes to/from remote. This is called automatically by start and done — you usually don't need this.

whoson sync

Configuration

Add a whoson.config.json to the root of your repo to configure team-wide settings:

{
  "sessionExpiry": "8h",
  "logWindow": "7d",
  "warnIfOlderThan": "4h"
}

| Key | Default | Description | |---|---|---| | sessionExpiry | "8h" | Sessions older than this are treated as stale and hidden from status | | logWindow | "7d" | Default time window for whoson log | | warnIfOlderThan | "4h" | Sessions older than this show a softer "might be stale" warning instead of a hard conflict |

Time format: "1h" (hours), "1d" (days), "1w" (weeks).

User config

Personal settings live in ~/.config/whoson/config.json (created by whoson init):

{
  "name": "age",
  "email": "[email protected]"
}

Priority order

CLI flag > user config > whoson.config.json > built-in defaults

Team setup

1. Add whoson.config.json to your repo root and commit it
2. Add whoson as a devDependency: npm install --save-dev whoson
3. Each developer runs whoson init once on their machine
4. Done — start using whoson start and whoson done as part of your workflow

Works offline

If there's no network or remote access, whoson continues working locally. Sync failures are shown as warnings, not errors. Changes sync automatically the next time you run start or done.

Requirements

• Node.js 18+
• Git (any version with notes support)
• A git remote (GitHub, GitLab, Bitbucket, etc.) for team sync

Development

git clone https://github.com/<your-username>/whoson
cd whoson
npm install

npm run build    # compile TypeScript
npm test         # run tests
npm run dev      # run without building (via tsx)

License

MIT