# ticktock

A Charm-native front-end for the [`tock`](https://github.com/dhth/tock) time
tracker. Review, edit, and backfill your tracked time in a fast terminal UI.
tock stays the source of truth — ticktock only reads and writes through it. The
command is `tt`.

## Install

```sh
brew tap humdrum/tap https://codex.humdrum.me/git/homebrew-tap.git
brew trust humdrum/tap        # newer Homebrew gates third-party taps
brew install tt
```

Upgrade later with `brew upgrade tt`.

## Requirements

- **`tock` on PATH.** ticktock owns no storage — every read and write shells out
  to your installed [`tock`](https://github.com/dhth/tock). Tested against tock
  **v1.9.8**; older versions may predate the `report --json` / `add -s/-e`
  contract it relies on.
- **tock's sqlite backend is strongly recommended.** ticktock works on any
  backend for reading and adding, but editing an entry is a remove-then-re-add,
  and on the file/markdown backend tock's `report --json` can omit tags/notes —
  so an edit could silently drop them. On sqlite the full row round-trips intact.
- **`sqlite3` CLI (optional).** Used only to pull history for autocomplete when
  the sqlite backend is active. Missing it just falls back to `tock last`;
  nothing breaks.

## Usage

Run `tt` for the command list. The three views:

- `tt timeline [date|today|yesterday]` — spatial day grid: fixed slot rows,
  range-select to add an entry, edit/delete logged sessions, per-project
  colors. (Alias: `tt tui`.)
- `tt day [date|today|yesterday]` — list view with per-project totals and
  Enter-to-edit. `←/→` change day.
- `tt menu` — guided menu over tock: start, stop, current, continue, note,
  tag, report, list, last, watch, analyze. Full-screen actions
  (watch/list/analyze) hand the terminal over to tock.

In the add/edit form, **project**, **description**, and **tags** autocomplete
from your tock history (Ctrl+E accepts a suggestion). Values stay free text.
History comes from the tock sqlite DB when that backend is active, otherwise
from `tock last`.

## Config

`~/.config/ticktock/config.json` (all optional):

| key            | default | meaning                                  |
|----------------|---------|------------------------------------------|
| `slot_minutes` | `30`    | grid row height in minutes (min 5)       |
| `grid_start`   | `07:00` | earliest grid hour (auto-expands to data)|
| `grid_end`     | `21:00` | latest grid hour (auto-expands to data)  |
| `project`      | `""`    | default project for a new entry          |

## License

AGPL-3.0-or-later. See `LICENSE`.