docs: rewrite README as a user-facing brew install + usage guide
f1a8ae470cab004e47c24f67ad354471ece50c27
Kevin Kortum <kevinkortum@me.com> · 2026-07-08 08:46
parent 4b3fd581
docs: rewrite README as a user-facing brew install + usage guide Retitle to 'ticktock' (no hyphen) with a subtitle, and drop the contributor-facing sections (make install/build/test, custard release). The README is now install-via-brew and how-to-use for others. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Pc56rzYZo9TjJgXN951Psk
1 files changed
README.md +22 −40
@@ -1,37 +1,37 @@
-# tt — a Charm-native front-end for tock
+# ticktock
-`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.
+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
- make install # builds bin/tt, symlinks it into ~/.local/bin
+```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
+```
-Once published to the tap:
-
- brew install humdrum/tap/tt
+Upgrade later with `brew upgrade 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
+- **`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 `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.
+ 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.
-- **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.
+## Usage
-## Commands
+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
@@ -39,7 +39,8 @@ 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.
+ 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.
@@ -56,25 +57,6 @@ | `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
-
-Releases ship through [custard](https://codex.humdrum.me/r/custard) to the
-self-hosted Homebrew tap. Config lives in `.custard.yaml` (source build,
-`depends_on "go"`). Push `main` first, then from the repo root:
-
- custard release v0.1.0
-
-custard runs the CI checks, tags the commit, pushes it, and the forge
-renders `Formula/tt.rb` into the tap. Install requirements (tock, sqlite)
-live under [Requirements](#requirements) — the auto-formula does not repeat
-them.
## License