Tock

<p align="center"> <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> </p> <p align="center"> <a href="#features"><strong>Features</strong></a> <span>&nbsp;•&nbsp;</span> <a href="#quick-start"><strong>Quick Start</strong></a> <span>&nbsp;•&nbsp;</span> <a href="#commands"><strong>Commands</strong></a> <span>&nbsp;•&nbsp;</span> <a href="#openclaw"><strong>OpenClaw</strong></a> <br /> <a href="#configuration"><strong>Configuration</strong></a> <span>&nbsp;•&nbsp;</span> <a href="#theming"><strong>Theme</strong></a> <span>&nbsp;•&nbsp;</span> <a href="#file-format"><strong>File Format</strong></a> <span>&nbsp;•&nbsp;</span> <a href="#shell-completion"><strong>Shell</strong></a> <span>&nbsp;•&nbsp;</span> <a href="#inspiration"><strong>Inspiration</strong></a> <span>&nbsp;•&nbsp;</span> <a href="#license"><strong>License</strong></a> </p>

Features

<img src="assets/demo.png" width="820px" />

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)

<hr clear="right"/>

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

<img src="assets/demo.gif" width="820px" /> <hr clear="right"/>

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:

1. Command-line flags
2. Environment variables
3. Configuration file (~/.config/tock/tock.yaml or ./tock.yaml)
4. 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
  use_tock_tag_colors: true
  use_tock_tag_colors_calendar: true
  use_tock_tag_colors_weekly_activity: true
  use_tock_tag_colors_top_projects: true
working_hours:
  enabled: true
  stop_at: "17:30"
  weekdays: "mon,tue,wed,thu,fri"
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

When working_hours.enabled is true, tock will automatically stop the latest running activity at working_hours.stop_at the next time you run a command after that cutoff. The feature is disabled by default.

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"

# Optional: Ignore tags.*.color from timewarrior.cfg and use tock theme.tag_colors
export TOCK_TIMEWARRIOR_USE_TOCK_TAG_COLORS="true"

# Optional: Selective overrides for specific calendar sections
export TOCK_TIMEWARRIOR_USE_TOCK_TAG_COLORS_CALENDAR="true"
export TOCK_TIMEWARRIOR_USE_TOCK_TAG_COLORS_WEEKLY_ACTIVITY="true"
export TOCK_TIMEWARRIOR_USE_TOCK_TAG_COLORS_TOP_PROJECTS="true"

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, or "decimal" for decimal hours)
  time_spent_format: "15:04" # Default
  # time_spent_format: "decimal" # Decimal hours: 2h15m → "2.25", 5h45m → "5.75"

  # 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 (Go time syntax, or "dec