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.
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_SHA256SUMSCheck 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 # LinuxEach 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/httThen 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 --versionOn 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 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.
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.
$ 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.
Aliases keep the most-used subcommands close at hand:
alias t="htt t" # htt todo
alias jnl="htt l" # htt loghtt completion --help explains how to install tab completion for
bash, zsh, fish or PowerShell. htt --version prints the version you
have.
htt works offline. It reaches the network for one thing only, the update check below, and never sends your tasks or time logs anywhere.
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
GETwith aUser-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
helpnever check, and neither do builds without a version (htt --versionsays "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-filerecords 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.jsonin 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: falsein 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.)
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/.
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.logTODO.md holds the wishlist of unscoped ideas and a list of
known issues. Work that's been scoped lives in
GitHub Issues.
- https://github.com/google/go-github — Github API client
- https://github.com/gammons/todolist — Also in Go, similar idea with good query parsing
- http://jrnl.sh/ — Command-line journaling
- https://github.com/VladimirMarkelov/ttdl — Terminal Todo List Manager in Rust
- https://github.com/hugokernel/todofi.sh — todotxt with Rofi
- https://xwmx.github.io/nb/
- https://github.com/yuucu/todotui
- https://codeberg.org/pter/pter
- https://github.com/Fanteria/todotxt-tui
- http://todotxt.org/
- https://www.solidtime.io/ / https://github.com/solidtime-io/solidtime
htt is released under the MIT License.