Tock

<a href="https://github.com/kriuchkov/tock/releases"> <img src="https://img.shields.io/github/v/release/kriuchkov/tock?style=flat-square" alt="Release" /> </a> <a href="LICENSE"> <img src="https://img.shields.io/github/license/kriuchkov/tock?style=flat-square" alt="License" /> </a> <a href="https://github.com/kriuchkov/tock/stargazers"> <img src="https://img.shields.io/github/stars/kriuchkov/tock?style=flat-square" alt="Stars" /> </a> <a href="go.mod"> <img src="https://img.shields.io/github/go-mod/go-version/kriuchkov/tock?style=flat-square&logo=go&label=Go" alt="Go Version" /> </a> <a href="https://github.com/kriuchkov/tock/actions"> <img src="https://img.shields.io/github/actions/workflow/status/kriuchkov/tock/ci.yml?style=flat-square&label=tests" alt="CI" /> </a> <a href="docs/openclaw.md"> <img src="https://img.shields.io/badge/OpenClaw-ready-0A84FF?style=flat-square" alt="OpenClaw" /> </a> <a href="#features">Features</a>  •  <a href="#quick-start">Quick Start</a>  •  <a href="#commands">Commands</a>  •  <a href="#openclaw">OpenClaw</a> <a href="#configuration">Configuration</a>  •  <a href="#theming">Theme</a>  •  <a href="#file-format">File Format</a>  •  <a href="#shell-completion">Shell</a>  •  <a href="#inspiration">Inspiration</a>  •  <a href="#license">License</a>

Features

Tock is a powerful time tracking tool for the command line. It saves activity logs as plaintext files and provides an interactive terminal UI for viewing your time.

Features include:

Simple plaintext format - Activities stored in human-readable files (default)
Multiple Backends - Support for flat files, TodoTXT, TimeWarrior, and SQLite databases
Notes & Tags - Attach detailed notes and tags to activities
Interactive TUI - Beautiful terminal calendar view using Bubble Tea
Fast & Lightweight - Single binary, no dependencies
Compatible - Reads/writes Bartib file format, TodoTXT-compatible lines, and TimeWarrior data files
Customizable Themes - Multiple color themes and custom color support
Report Export - Export report data as text, CSV, or JSON
iCal Export - Generate .ics files for calendar integration, or sync with system calendars (macOS only)

Quick Start

Installation

Homebrew (macOS)

# https://formulae.brew.sh/formula/tock
# Install from official repository (build from source)
brew install tock

# Install pre-built binary via latest release (Goreleaser)
brew install kriuchkov/tap/tock

Go Install

go install github.com/kriuchkov/tock/cmd/tock@latest

Build from source

go build -o tock ./cmd/tock

Install Script (Linux & macOS)

curl -sS https://raw.githubusercontent.com/kriuchkov/tock/master/install.sh | sh

Download Binary

Download the latest release from the Releases page.

Basic Usage

Start tracking time:

tock start # Interactive mode (requires no arguments)
tock start "My Project" "Implementing features" # Quick start with arguments
tock start "My Project" "Implementing features" "Some notes" "tag1,tag2"  # Quick start with arguments + notes/tags
tock start -d "Implementing features" -p "My Project" # Start with flags
tock start -d "Implementing features" -p "My Project" -t 14:30 --note "Some notes" --tag "afternoon" # Start with flags + time + notes/tags

Stop the current activity:

tock stop # Stop now
tock stop -t 17:00 # Stop at specific time
tock stop --note "Finished for the day" # Stop with a note
tock stop --tag "end-of-day" # Stop with a tag

Continue a previous activity (Create a new entry with the same project/description):

tock continue  # Continue the last activity
tock continue 1   # Continue the 2nd to last activity
tock continue -d "New" # Continue last activity but with new description
tock continue -p "New Project" # Continue last activity but with new project
tock continue -t 14:00 # Continue last activity but with specific start time
tock continue --note "Resuming work" --tag "resumed" # Continue last activity with a note and tag

View activities in interactive calendar:

tock list

Calendar controls:

Arrow Keys / h,j,k,l: Navigate days
n: Next month
p: Previous month
q / Esc: Quit

tock calendar

Configuration

Tock supports a flexible configuration system using YAML files and environment variables.

Priority Order:

Command-line flags
Environment variables
Configuration file (~/.config/tock/tock.yaml or ./tock.yaml)
Default values

Configuration File

Example tock.yaml:

backend: file
file:
    path: /Users/user/tock.txt
todotxt:
  path: /Users/user/todo.txt
sqlite:
    path: /Users/user/tock.db
time_format: "24"
theme:
    faint: '#404040'
    highlight: '#FFFF00'
    name: custom
    primary: '#FF00FF'
    secondary: '#00FFFF'
    sub_text: '#B0B0B0'
    text: '#FFFFFF'
timewarrior:
    data_path: /Users/user/.timewarrior/data
calendar:
    time_spent_format: "15:04"
    time_start_format: "15:04"
    time_end_format: " • 15:04"
export:
    ical:
        file_name: "tock_export.ics"
weekly_target: "40h"
check_updates: true

You can specify a custom config file path with the --config flag:

tock --config /path/to/tock.yaml list

Example a config file tock.yaml.example.

Environment Variables

All settings can be overridden with environment variables (prefix TOCK_).

TOCK_BACKEND: file, todotxt, timewarrior, or sqlite
TOCK_EXPORT_ICAL_FILE_NAME: Custom filename for bulk iCal export (default: tock_export.ics)
TOCK_FILE_PATH: Path to activity log
TOCK_TODOTXT_PATH: Path to TodoTXT activity log
TOCK_TIME_FORMAT: Time display format (12 or 24) Notes are stored as individual files in ~/.tock/notes/ (or relative to your configured file path).
TOCK_THEME_NAME: Theme name (dark, light, custom)
TOCK_WEEKLY_TARGET: Weekly workload target as a duration (e.g., 40h, 37h30m)
TOCK_CHECK_UPDATES: Check for updates (default: true)

Storage Backends

Tock supports multiple storage backends.

OpenClaw

Tock includes a workspace-ready OpenClaw skill in skills/tock.

This integration model uses the local tock CLI instead of coupling Tock to OpenClaw internals. For agent-safe flows, use machine-readable commands where possible:

tock current --json
tock last --json -n 10
tock export --today --format json --stdout
tock start -p "Backend" -d "Implement OpenClaw skill" --json
tock stop --json

Setup details are documented in docs/openclaw.md.

1. Flat File (Default)

Stores activities in a simple plaintext file.

export TOCK_FILE_PATH="$HOME/.tock.txt"

2. TodoTXT

Stores activities in a TodoTXT-compatible file. Tock keeps exact timestamps and full field fidelity in tock_* key:value extensions, so round-tripping remains lossless even though base TodoTXT has date-only task metadata.

# Enable TodoTXT backend
export TOCK_BACKEND="todotxt"

# Optional: Specify custom TodoTXT file path (default: ~/.tock.todo.txt)
export TOCK_TODOTXT_PATH="$HOME/.tock.todo.txt"

3. TimeWarrior

Integrates with TimeWarrior data files.

# Enable TimeWarrior backend
export TOCK_BACKEND="timewarrior"

# Optional: Specify custom data directory (default: ~/.timewarrior/data)
export TOCK_TIMEWARRIOR_DATA_PATH="/path/to/timewarrior/data"

4. SQLite

Stores activities in an SQLite database file.

# Enable SQLite backend
export TOCK_BACKEND="sqlite"

# Optional: Specify custom database file path (default: ~/.tock.db)
export TOCK_SQLITE_PATH="/path/to/tock.db"

Or use flags:

tock --backend timewarrior list

Calendar View

Customize the time format in the calendar view (tock calendar).

calendar:
  # Format for duration display (Go time syntax)
  time_spent_format: "15:04" # Default

  # Format for start time (Go time syntax)
  # Default: uses global time_format
  time_start_format: "15:04"

  # Format for end time (appended to duration)
  # Includes separators or icons.
  # Default: " • " + global time_format
  # Example: " 🏁 15:04"
  time_end_format: " • 15:04"

  # Format for total daily duration.
  # Defaults to time_spent_format.
  time_total_format: "15:04"

  # Align duration to the left side in the details view
  # true:  "01:30 Project Name"
  # false: "- Project Name: 01:30" (Default)
  align_duration_left: false

Theming

Tock supports customizable color themes for the calendar view.

You can configure the theme in tock.yaml:

theme:
  name: custom
  primary: "#ff0000"

Or use environment variables:

Theme Name

Set TOCK_THEME_NAME (or theme.name in config) to one of:

dark: Standard 256-color dark theme
light: Standard 256-color light theme
ansi_dark: 16-color dark theme
ansi_light: 16-color light theme
custom: Use custom colors defined by environment variables

Auto-detection

If theme.name is not set, Tock automatically selects the best theme:

Detects terminal capabilities (TrueColor/256 vs ANSI).
Detects background color (Light vs Dark).
Selects the appropriate theme (e.g. `l

Tock

Install / Use

README

Tock

Features

Quick Start

Installation

Homebrew (macOS)

Go Install

Build from source

Install Script (Linux & macOS)

Download Binary

Basic Usage

Configuration

Configuration File

Environment Variables

Storage Backends

OpenClaw

1. Flat File (Default)

2. TodoTXT

3. TimeWarrior

4. SQLite

Calendar View

Theming

Theme Name

Auto-detection