Clockker

Clockker watches your macOS file system and submits any file changes to the Clockk web service. Learn more about Clockk at http://clockk.com.

Installation

Install it with:

$ gem install clockker

To access your Safari history when using macOS Mojave (10.14) and higher, you must give the Terminal app "Full Disk Access".

Settings
Security & Privacy
Privacy
Full Disk Access
+ to add
Browse to find /Applications/Utilities/Terminal
Quit and restart Terminal

Usage

Run it with:

$ clockker watch <path>

This will start the clockker executable in the foreground, and it will watch for file changes at .

Clockker takes several command-line options:

-t=x / --token=x : sets the token for communication, as provided by Clockk. REQUIRED.

-r=x / --region=x : sets the region for the Clockk server. Regions can be ca-central, us-east, eu-frankfurt, etc.

-v / --verbose : sets verbosity. Default: info. Options (with -v= or --verbose=): debug, info, warn, error, fatal

-s=x / --submit-frequency=x : upload changed files list to Clockk server every seconds. Default: 300 seconds.

-d / --development : Development mode. In addition to submitting to the Clockk server, also submit the same artifacts to the server running at localhost:4000. Errors on the local server are logged and ignored.

-w=x y z / --whitelist=x y z : Space-separated list of absolute paths to watch. Defaults to your home directory (~).

-b=x y z / --blacklist=x y z : Space-separated list of absolute paths to ignore that are undeneath your whitelisted paths. Defaults to ~/Library. The blacklist always includes dot-files (e.g. .DS_Store, .bashrc, etc.)

Instead of using the command-line options, you can specify a default configuration in ~/.clockker, which is a JSON-formatted file. An example structure is:

{
  "version": "0.1.0",
  "token": "asdf1234",
  "region": "ca-central",
  "whitelist": [
    "/Users/paul",
    "/web"
  ],
  "blacklist": [
    "/Users/paul/Library",
    "/Users/paul/Pictures",
    "/Users/paul/.dropbox"
  ],
  "url_whitelist": [
    "facebook.com",
    "linkedin.com",
    "trello.com",
    "other.com"   # or simply "", which matches everything
  ]
}

Note: Version 0.1.0 is the Clockker configuration file version.

A note on privacy

Clockker does its very best to respect what you consider private. By default, nothing is watched - no files, no URLs. You add things to watch by adding them to the whitelist. If you want to hide something that's inside the whitelist, (e.g. /Users/joe/Photos which is inside the tracked folder /Users/joe/), add that path to the blacklist.

URLs work the same way — the Clockker will only report them if they are in the url_whitelist. That can be a bit tedious, so if you do want Clockk to track everything, simply add "" to the whitelist.

Safari Private Browsing and Google Incognito windows are NEVER tracked.

Development

After checking out the repo, run bin/setup to install dependencies. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

To run a development version run bundle exec exe/clockker <params>.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/liquidmedia/clockker. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

Please note that this software is intended for use with the Clockk web service. It is released as open source for the following reasons:

To be as transparent as possible with software that runs on our users’ computers.
To be open to bug fixes from our user community.
To share some of the code (and the lessons we learn from it) that we develop internally with the wider community.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Clockker project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.