# tt — a Charm-native front-end for tock

`tt` makes it easy to review, edit, and backfill time tracked with the
[`tock`](https://github.com/dhth/tock) CLI. tock stays the source of truth;
`tt` only reads and writes through it.

## Install

    make install            # builds bin/tt, symlinks it into ~/.local/bin

Once published to the tap:

    brew install humdrum/tap/tt

## Requirements

- **`tock` on PATH.** `tt` 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 `tt` relies on.
- **tock's sqlite backend is strongly recommended.** `tt` 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.
- **Building from source needs Go ≥ 1.26.** The Homebrew formula is a source
  build and pulls the Go toolchain automatically.

`tt menu`'s full-screen actions (watch/list/analyze) hand the terminal over to
tock.

## Commands

- `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.

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          |

## Build & test

    make build      # -> bin/tt
    make test
    make vet

## Release

Homebrew release scaffolding lives in `scripts/brew-release.sh` and
`deploy/deploy.env.example` (copy to `deploy/deploy.env`, gitignored). The
formula is a source build (`depends_on "go"`); publishing is a manual step.

## License

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