Warning

These docs have been generated by Claude, with some supervision and limited review.

They're undoubtedly better than what would currently exist without the robot work, but should be taken with a pinch of salt.

faffage

Faffage is a local-first, open standard for personal time tracking. Your time is tracked on your device. You choose what to share, with whom, and when.

Philosophy

Most time tracking tools think about billing first and you a distant third. Faffage is different.

Log locally. Your records live in ~/.faff/logs/ as human-readable TOML files. No account needed. No internet required. No data leaves your machine unless you explicitly push it somewhere.

Remotes are optional. A remote is an external system — your employer's time tracker, a project management tool, a client's billing system. Remotes can provide plans (vocabulary and tracker data that guide your logging) and receive timesheets (compiled, filtered snapshots of your log). You configure which remotes you use; none are assumed.

Share only what you intend. When you compile a timesheet for an audience, the audience plugin decides what to include. Notes, reflection scores, and personal subjects can be filtered out before the data is signed. The signature covers the filtered version — recipients cannot infer what you withheld.

Reflect, don't just bill. For each block of time, faffage encourages you to think about:

• Role — what function were you performing? (e.g. team lead, pre-sales engineer, human being)
• Impact — what were you trying to achieve? (e.g. develop staff, new revenue, process improvement)
• Mode — how were you working? (e.g. scheduled meeting, critical thinking, admin)
• Subject — who or what was it for? (e.g. a customer, a project, yourself)

These fields represent important dimensions of spent time; they're optional (but encouraged).

Reflection scores and notes are private. They never appear in timesheets unless you explicitly choose to include them. Over time, patterns emerge about what kinds of work you find meaningful — and which meetings are a waste of everyone's time.

Timesheets can be cryptographically signed. Ed25519 signatures prove integrity and authorship. Recipients can verify a timesheet independently. Key management, signing, and verification are handled by faff-core.

The core loop

• PULL fresh plans and tracking vocabulary from your configured remotes.
• START/STOP the tracker to update your log.
• COMPILE to transform your local log into an audience-appropriate timesheet (and optionally sign it).
• PUSH to submit.

Documentation

• Core concepts — the mental model: logs, sessions, intent fields, plans, remotes, plugins, timesheets
• Directory structure — how ~/.faff/ is organised

File formats:

• Log format — daily TOML log files
• Plan format — vocabulary and hints pulled from remotes
• Timesheet format — compiled, signed JSON timesheets
• Remote format — remote configuration files
• Config format — ~/.faff/config.toml

Extending faffage:

• Writing a plugin — implement PlanSource and/or Audience
• faff-core SDK — the canonical Rust library with Python and WASM bindings

Implementation

The canonical implementation of the faffage standard is faff-core — a Rust library with Python and WASM bindings. It handles all format parsing, writing, signing, and verification. If you're building something that reads or writes faffage files, use faff-core.

See faff-core.