Skip to content
bricefPublic

About

Command line application to manage tasks and time tracking

Resources

Stars

2 stars

Watchers

1 watching

Forks

Latest commit

 

History

325 Commits

Folders and files

Repository files navigation

Hypothetical Tasks & Time Tracker (htt)

CI

htt is a todo.txt-compatible command-line todo list manager and time tracker. Tasks live in plain-text files you can also edit by hand.

  • Todo lists in todo.txt format, split into contexts (work, home, …), with priorities, natural-language due dates (--due "next Friday"), search, and sorted or filtered views.
  • A time log: a timestamped record of what you worked on each day.
  • Reports: what you completed, added and deleted, and how long you worked, over any period.
  • Three ways in: one-shot commands, a todo-mode shell (htt repl) and a full-screen TUI (htt interactive) with search, in-place editing with a live preview and tag completion, task lines coloured by priority, tag and date, colour themes (Monokai, VS Code, Dracula, Nord, Solarized, Gruvbox) and per-colour config.

New to htt? GETTING-STARTED.md is a fifteen-minute walkthrough of the realistic workflow — add a task, prioritise it, complete it, organise with contexts, log time against it — and the reference for every command.

Installation

Download a binary

Every release from v0.3.0 on has a ready-to-run htt for Linux and macOS, so you don't need Go. Pick the archive for your machine (uname -sm tells you which you have):

Machine uname -sm Archive
Linux on Intel or AMD Linux x86_64 htt_vX.Y.Z_linux_amd64.tar.gz
Linux on 64-bit ARM Linux aarch64 htt_vX.Y.Z_linux_arm64.tar.gz
Mac with Apple silicon Darwin arm64 htt_vX.Y.Z_darwin_arm64.tar.gz
Mac with an Intel processor Darwin x86_64 htt_vX.Y.Z_darwin_amd64.tar.gz

There's no Windows build yet.

Download it and the checksums file, htt_vX.Y.Z_SHA256SUMS, from the release page, or with gh (v0.3.0 on an Apple silicon Mac, say):

gh release download v0.3.0 --repo bricef/htt \
  --pattern htt_v0.3.0_darwin_arm64.tar.gz --pattern htt_v0.3.0_SHA256SUMS

Check the archive against the checksums file. It should say OK:

grep htt_v0.3.0_darwin_arm64.tar.gz htt_v0.3.0_SHA256SUMS | shasum -a 256 -c   # macOS
grep htt_v0.3.0_linux_amd64.tar.gz htt_v0.3.0_SHA256SUMS | sha256sum -c        # Linux

Each archive also has a signed build-provenance attestation, which shows it was built by htt's release workflow from htt's repository. gh checks it:

gh attestation verify htt_v0.3.0_darwin_arm64.tar.gz --repo bricef/htt

Then unpack htt and put it somewhere on your PATH:

tar -xzf htt_v0.3.0_darwin_arm64.tar.gz htt
mv htt ~/.local/bin/
htt --version

On macOS, a file downloaded with a web browser is quarantined, and macOS won't run a quarantined program that isn't signed by an Apple developer, which htt isn't: it says Apple can't verify that "htt" is free of malware. Clear the quarantine flag to run it:

xattr -d com.apple.quarantine ~/.local/bin/htt

(Downloads made with gh or curl aren't quarantined.)

To update, download the new release the same way. The update notice suggests go install, which only applies to an install made with Go.

With Go

With a working Go toolchain:

go install github.com/bricef/htt/cmd/htt@latest

Make sure $(go env GOBIN) (or $(go env GOPATH)/bin if GOBIN is unset) is on your PATH.

htt needs Go 1.26.11 or newer, because earlier releases have standard-library vulnerabilities its network code can reach. With an older Go, go install downloads 1.26.11 for the build by itself, unless you've set GOTOOLCHAIN=local.

Releases are listed on the releases page; htt --version tells you which one you have.

From source

htt takes its version from git: go install …@vX.Y.Z, or a build in a clone checked out at a release tag, knows it. A build from a source archive (the .tar.gz GitHub offers for each release, as a package manager uses) has no git information, so pass the version in, or htt --version says "unknown" and the update check stays off:

go build -ldflags "-X github.com/bricef/htt/internal/update.version=v0.3.1" -o htt ./cmd/htt

The v is optional (version=0.3.1 works too), and a version given this way wins over anything git says.

Usage

$ htt help
htt is a command line todo list manager and time tracker

Usage:
  htt [flags]
  htt [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  config      Manage configuration.
  help        Help about any command
  interactive Enter interactive mode
  log         Manage the activity log.
  repl        Interactive todo-mode shell.
  report      Summarise activity in a time period.
  status      Show the status of the tasklist and time log.
  todo        Manage todo lists.
  workon      Log that work has begun on numbered item in the current context.

Flags:
  -h, --help       help for htt
      --no-color   Disable color output for coloured commands

Use "htt [command] --help" for more information about a command.

Tips

Aliases keep the most-used subcommands close at hand:

alias t="htt t"      # htt todo
alias jnl="htt l"    # htt log

htt completion --help explains how to install tab completion for bash, zsh, fish or PowerShell. htt --version prints the version you have.

Online activity

htt works offline. It reaches the network for one thing only, the update check below, and never sends your tasks or time logs anywhere.

Update check

htt checks whether a newer release exists, so you hear about fixes.

  • What it contacts: one URL, https://api.github.com/repos/bricef/htt/releases/latest, which answers with the newest published htt release. Nothing else is contacted, and a redirect to another host is refused.
  • What it sends: a plain GET with a User-Agent: htt/<your version> header. No account, token, task data or settings. Like any request, it shows GitHub your IP address (see GitHub's privacy statement).
  • When: at most once a day, and only when you're there to see the answer: a command run at a terminal, or the TUI. Scripts, pipes, cron jobs, shell tab completion and help never check, and neither do builds without a version (htt --version says "unknown").
  • What you see: if the release is newer than yours, a notice after the command (on stderr) or on the TUI's status line, at most once a day. htt never downloads or installs anything itself.
  • If it fails (offline, a timeout, a rate limit, any error): nothing. The command runs exactly as it would have, and nothing is printed; the TUI's --log-file records why. The request runs in the background, and a command waits at most a second for it, only on the day's checking run.
  • What it stores: update-check.json in your user cache directory (~/.cache/htt/ on Linux): when it last checked, and the latest release it saw.
  • Turning it off: set check_for_updates: false in your config file (~/.config/htt/config.yaml).

There is nothing else: no telemetry, no analytics, no other servers. (Installing with go install downloads htt through the Go module proxy; that's the Go toolchain, before htt ever runs.)

Architecture

Layered around a domain package that owns the contracts and storage implementations that satisfy them. CLI (cobra) and TUI (bubble tea) sit at the top.

cli ─────────────► tui
 │                  │
 ▼                  ▼
storage ─────────► domain

The full tour — domain types, repository interfaces, storage impls, how features flow through the layers, and how to add one — lives at docs/architecture.md. Historical design docs are under docs/plans/.

Development

justfile is the source of truth for build / test / lint commands. just with no arguments lists every recipe:

$ just
Available recipes:
    build                    # Build the htt binary into ./bin/htt.
    check                    # Lint with golangci-lint.
    clean                    # Remove build artifacts and the in-repo Go cache.
    default                  # Default: list recipes.
    dist version             # Build the release archives for tag VERSION into dist/, as releases do.
    install                  # Install the htt binary into $GOBIN / $GOPATH/bin.
    mod-download             # Populate the module cache.
    release version notes    # Release main as VERSION with NOTES: check, tag, publish, verify.
    release-binaries version # Rebuild the binaries of the published release VERSION, and check them.
    release-check version    # Check main is ready to release as VERSION (vX.Y.Z); changes nothing.
    test                     # Run every test suite (e2e, TUI, internal packages).
    test-e2e                 # Run just the e2e CLI harness.
    test-pkg pkg             # Run one package, e.g. `just test-pkg internal/storage`.
    test-tui                 # Run just the TUI snapshot harness.
    test-unit                # Run all internal/* tests (domain, storage, usecase, todo, ...).
    vet                      # Static analysis across the module.

Releases are made with just release; see docs/releasing.md. Publishing one runs release-binaries.yml, which builds the binaries with scripts/dist.sh and attaches them to the release; just dist vX.Y.Z builds the same archives locally.

CI (.github/workflows/ci.yml) runs the same recipes on every push to any branch: go mod tidy -diff, just test, just vet and just check (golangci-lint v2.15.0), plus govulncheck. A separate workflow, weekly.yml, runs govulncheck on Mondays, so a vulnerability published while htt is quiet still shows up. GitHub pauses a scheduled workflow after 60 days without activity and doesn't resume it by itself; turn it back on with gh workflow enable weekly.yml. The workflows' actions are pinned to commits, and Dependabot updates them monthly.

Quick dev loop for the TUI. It never writes to the terminal outside its own screen; --log-file appends its diagnostics to a file, at debug level unless --log-level (debug, info, warn, error) says otherwise:

$ go run cmd/htt/main.go interactive --log-file debug.log
# in another shell:
$ tail -f debug.log

Wishlist and known issues

TODO.md holds the wishlist of unscoped ideas and a list of known issues. Work that's been scoped lives in GitHub Issues.

Prior art

License

htt is released under the MIT License.

About

Command line application to manage tasks and time tracking

Resources

Stars

2 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages