Clockwerk

Clockwerk is a local work history engine. It reconstructs developer work sessions from activity signals - every prompt, edit, and command in your tools already has a timestamp. Clockwerk turns those into sessions.

How it works

The pipeline is: activity signals (hooks in your tools) produce raw events, which are stored in local SQLite. A session detection algorithm groups events into sessions based on activity gaps. The result is a complete work history.

Everything runs locally. Events are stored on your machine, sessions are computed on your machine, and corrections happen on your machine. Nothing ever leaves your machine.

Install

Supports Linux and macOS (x64 and ARM). Also available via npm: npm install -g @getclockwerk/cli.

Initialize a project

Run this in any project directory. It creates a local config, auto-detects your AI tools, and offers to install hooks for automatic tracking.

Start tracking

The daemon runs in the background and picks up activity from your hooks automatically. Use clockwerk status to see your tracked time.

Check your status

That's it. Sessions are being computed from your tool activity. Use clockwerk list today to inspect sessions from the CLI, open Studio for a visual overview, or export to CSV for billing.

Local-first architecture

Raw activity data never leaves your machine. Events are stored in local SQLite and sessions are computed locally. Clockwerk never captures your source code, prompts, credentials, or keystrokes.

Open source

Clockwerk is open source on GitHub. MIT licensed. You can audit what gets tracked and how sessions are computed.

Quick install

Or with npm:

The package includes pre-compiled binaries for your platform. No build step needed.

Supported platforms

Verify installation

Uninstall

Stop the daemon, remove the package, and delete the config directory. Project-level .clockwerk files can be removed individually.

Why open source

Time tracking tools have access to sensitive data about your work patterns, projects, and workflow. We believe you should be able to verify exactly what data is collected and where it goes. That's why Clockwerk's CLI and core packages are open source.

What's open source

What you can verify

With the source available, you can audit:

Architecture

Clockwerk is built with Bun and TypeScript. The CLI compiles to a single standalone binary with no runtime dependencies. Events are stored in a local SQLite database and sessions are computed on-device.

Contributing

Contributions are welcome. File issues, submit pull requests, or build your own integrations. Check the GitHub repository for setup instructions and contribution guidelines.

Interactive mode

Run clockwerk init in any project directory. It prompts for a project name, detects installed AI tools, and offers to install hooks.

Non-interactive mode

Pass the project name as an argument to skip the prompt:

The .clockwerk file

Init creates a .clockwerk JSON file in your project root:

{
  "version": 1,
  "project_name": "my-project",
  "project_token": "local_my-project",
  "harnesses": {
    "claude-code": true,
    "cursor": true
  }
}

Hook auto-detection

During init, Clockwerk checks for the presence of AI tool config directories:

Start the daemon

The daemon runs in the background, listens for events from hooks and plugins, and computes sessions from activity gaps.

Stop the daemon

Sends SIGTERM for a graceful shutdown. If the daemon doesn't stop within 2 seconds, it's force-killed.

Foreground mode

Useful for debugging. Logs are printed to stdout instead of the log file:

How it works

The daemon communicates over a Unix socket using a simple RPC protocol. Hooks and plugins send events to the socket, and the daemon stores them in a local SQLite database.

Usage

Output breakdown

When the daemon is stopped

When the daemon is not running, today's time and plugin info are not available. Run clockwerk up to start tracking.

Usage

Duration formats

Examples

How it works

Manual log entries create events at 4-minute intervals, which is under the 5-minute session gap threshold. This means the logged time appears as a single continuous session.

Usage

Examples

Log levels

Log file location

Logs are written to ~/.clockwerk/daemon.log. The logs command reads this file directly.

How hooks work

Hooks are post-tool-use callbacks that fire whenever your AI tool executes an action (editing a file, running a command, etc.). Each hook invocation sends an event to the Clockwerk daemon with context about what happened.

Hooks capture: tool name, file paths, session IDs, working directory, and timestamps. All hooks have a 5-second timeout to avoid slowing down your tools.

Auto-install

Auto-detect checks for tool config directories in your home folder and installs the appropriate hook configuration.

Install a specific hook

Available hook IDs: claude-code, cursor, copilot.

Claude Code

Installs a PostToolUse hook in ~/.claude/settings.json that fires on all tool calls.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "clockwerk hook claude-code",
            "timeout": 5000
          }
        ]
      }
    ]
  }
}

Captured data: tool name (Edit, Write, Bash, Read, etc.), session ID, file paths from tool input, and working directory.

Cursor

Installs a postToolUse hook in ~/.cursor/hooks.json.

{
  "hooks": [
    {
      "event": "postToolUse",
      "command": "clockwerk hook cursor",
      "timeout": 5000
    }
  ]
}

Captured data: tool name, conversation ID, tool arguments, working directory.

GitHub Copilot

Installs a postToolUse hook in .github/hooks/clockwerk.json within your project.

{
  "hooks": [
    {
      "event": "postToolUse",
      "command": "clockwerk hook copilot",
      "timeout": 5000
    }
  ]
}

Event data

Each hook invocation extracts the following from the tool's JSON input:

Source override

By default, each hook sets the event source based on the tool that triggered it. You can override this for all events in a process by setting the CLOCKWERK_SOURCE environment variable before running your agent.

This is useful for autonomous agent loops and headless runs where no human is interacting with the tool directly. Setting the source to autonomous signals that the session was machine-driven rather than human-driven.

# Run a headless agent loop with autonomous tracking
export CLOCKWERK_SOURCE=autonomous
claude -p "Run the test suite and fix any failures"

Overview

Plugins let you track time from any tool or process. A plugin is a shell command that outputs events. Clockwerk runs it on an interval and records the output as tracking events.

Plugins can be installed from the registry with a single command, or defined inline for custom tooling. The plugin registry is hosted on GitHub and community contributions are welcome.

Install from registry

Install a plugin by name. Clockwerk fetches the plugin manifest and script from the registry and installs it to ~/.clockwerk/plugins/.

Browse available plugins at getclockwerk.com/plugins.

Install inline

Define a plugin inline without a registry entry by passing --command directly:

Templates

Built-in templates for common tools:

Plugin manifest format

Registry plugins are defined by a plugin.json manifest file. This file describes the plugin and how Clockwerk should run it:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "display_name": "My Plugin",
  "description": "A short description of what this plugin tracks.",
  "author": "Your Name",
  "event_type": "manual",
  "source": "plugin:my-plugin",
  "command": "./plugin.sh",
  "interval": 5,
  "tags": ["example"]
}

Manage plugins

Update plugins

Check all installed registry plugins for newer versions and apply updates interactively:

Create a plugin

Scaffold a new plugin from the official template. This generates a plugin.json and plugin.sh in a new directory under plugins/:

Contribute a plugin

Anyone can publish a plugin to the Clockwerk registry. To contribute:

Once merged, the plugin becomes available via clockwerk plugin add <name> for all users.

Valid event types

Source naming

Plugin sources must be 2-64 characters, lowercase alphanumeric with hyphens and colons allowed. By default, the source is plugin:<name>.

Clockwerk Studio is a local web interface for your time data. It reads directly from your SQLite database - no cloud, no daemon dependency for reads, no latency.

Launch

Opens a local web server and your browser. The daemon must be running for write operations (editing descriptions, deleting sessions), but reads work independently.

Custom port

Dashboard

The landing page shows your day at a glance: total time tracked today and this week, average daily hours, and a list of today's sessions. Click any session to see its full detail.

Session browser

The sessions page lists all tracked sessions grouped by date. Filter by period - today, yesterday, this week, or this month. Each row shows the time range, duration, source, branch, and description if one exists.

Session detail

Drill into any session to see the full metadata: source, branch, issue ID, event count, topics, file areas, individual files changed, git commits, and tools used. Edit the description inline or delete the session entirely.

How it reads data

Studio opens your local SQLite database in read-only mode for every page load. No socket connections, no daemon queries, no timeouts. Writes (description edits, deletes) go through the daemon.

Events

Everything Clockwerk tracks starts as an event: a timestamped record of something that happened. Events are generated by hooks, plugins, manual logging, and file watching.

Event types

Sources

Session computation

Clockwerk groups events into sessions using a gap-based algorithm. Sessions are computed incrementally on your machine - each new event either extends an existing session or starts a new one.

Session data

Each session aggregates data from its events:

Event context

Each event can carry optional context fields:

Overview

The file watcher monitors your project directory for changes and generates heartbeat events. This tracks development activity even when you're not using an AI tool, for example manual editing in VS Code or Vim.

Enable file watching

Configuration

{
  "watch": {
    "enabled": true,
    "interval": 30,
    "exclude": ["node_modules", ".git", "dist", "build"]
  }
}

How it works

The file watcher uses inotify (Linux) or FSEvents (macOS) to detect changes. When a file is modified, it generates a heartbeat event with the file path. Events are throttled by the interval setting to avoid noise.

Default exclusions

Temporary and generated files are automatically excluded from session data:

View config

Subcommands

Available config keys

Examples

The .clockwerk file

All project configuration is stored in the .clockwerk file at your project root. This is a JSON file that can be edited directly or managed via the config command.

{
  "version": 1,
  "project_name": "my-project",
  "project_token": "local_my-project",
  "harnesses": {
    "claude-code": true,
    "cursor": true
  },
  "watch": {
    "enabled": false,
    "interval": 30,
    "exclude": ["node_modules", ".git"]
  },
  "plugins": []
}

Usage

Examples

CSV format

The CSV output includes the following columns:

Invoicing workflow

Export your tracked time for client invoicing:

Local-only by design

Clockwerk is built on a simple principle: your development data belongs to you. Everything is stored locally on your machine in a SQLite database. There is no cloud, no accounts, no telemetry. The CLI and core packages are open source so you can verify this yourself.

What Clockwerk stores

Clockwerk stores timestamped activity events and computed sessions in ~/.clockwerk/clockwerk.db:

What Clockwerk never stores

Clockwerk never captures or stores:

No network access

Clockwerk makes zero network requests. There is no cloud sync, no analytics, no update checks, no phone-home behavior. The daemon communicates exclusively over a local Unix socket.

Export is explicit

The only way data leaves your machine is through the clockwerk export command, which you run manually. Exports include session metadata (timestamps, duration, source) and are saved to a local file.

Audit it yourself

Clockwerk is open source. MIT licensed. You can read the implementation and inspect your local database directly with any SQLite client.