Track time against projects, from the terminal, on Linux, macOS and Windows.

It is a stopwatch with a memory: start a clock on a project, stop it, and get billable hours back. Every command also speaks --json, so a coding agent can clock its own work the same way you do — and @profullstack/billing turns those hours into invoices.

npm install -g @profullstack/timer

Node 20.11 or newer. No runtime dependencies.

timer start acme fix the login redirect     # everything after the project is the task
timer status                                # what is running, and today's total
timer stop

timer add acme code review --duration 45m   # time you forgot to clock
timer add acme --from 09:00 --to 11:30

timer log --week                            # what happened
timer report --month --group project        # what it adds up to
timer projects                              # everything you have ever tracked

Nothing is configured before first use. The timesheet appears the first time you start a clock.

timer help <command> prints the flags and examples for one command.

log, report, projects and export all take the same window flags: --today, --yesterday, --week (from Monday), --month, --year, or an explicit --since / --until.

Dates are loose on purpose: 09:15, 2026-08-01, -2h, yesterday, or a full ISO instant. A bare date means local midnight, not UTC midnight.

A window compares against the entry's start, and --until is exclusive. An entry that runs past midnight therefore belongs to the day it began on — which is what keeps a total from being counted twice.

An hour of agentic work is an hour times however many engines ran in it, so an entry carries an agent count:

timer start acme refactor auth --agents 4
timer add acme code review --duration 45m --agents 2

@profullstack/billing multiplies by it when the rate says to ($100/hour/agent/upto:4), and ignores it when the rate is flat. It defaults to 1, so you can ignore the whole idea until you need it.

start is also spelled on and stop is also spelled off, so muscle memory from other timers works.

Every entry is billable unless you say otherwise with --no-billable. Reports carry both numbers, because "how long did this take" and "what can I charge for it" are different questions:

timer add internal standup --duration 15m --no-billable
timer report --month

Two things make this usable by an agentic CLI without a wrapper.

Every command answers --json with a single JSON document on stdout and nothing else. Advisory lines go to stderr. A command that fails prints its error as JSON on stderr and leaves stdout empty, so parsing stdout can never yield a success shape for a failed run.

Exit codes are distinct: 0 success, 1 a runtime failure, 2 a bad command line, 3 you named something that is not there. timer stop with no clock running is a 0 — that is an answer, not a failure.

export TIMER_AGENT="claude-opus-5"            # stamps every entry it creates
timer start acme --task "refactor auth" --json
timer stop --json
timer log --today --json

--meta '{"pr":42}' hangs your own identifiers off an entry, and they survive round-trip unchanged. --agents N records how many engines were working, which is what an agent-priced rate multiplies by; it takes a number, not auto, since this package has no herd to count.

There is more detail, including the entry schema, in AGENTS.md.

One JSON file, in one place on every platform:

~/.profullstack/timer/timesheet.json

timer config prints all of it. The file is plain JSON you can read and edit; writes are atomic and locked, so several agents can clock in at once without losing an entry.

@profullstack/billing reads this file directly — it does not need timer on PATH — and turns unbilled hours into invoice line items:

billing invoice new --client acme --from-timer --month

moshcode installs and fronts it:

moshcode install timer
/timer start acme fix the login redirect

MIT © Profullstack, LLC