README
¶
gh-todo
Build a to-do list from the GitHub issues and pull requests assigned to you.
gh-todo groups your open work by due date, shows the status of each item, and
optionally lists what you closed recently. Output is styled with
lipgloss and adapts to light and
dark terminals.
╭──────────────────────────────────────────────────────────────────────────╮
│ GitHub to-do │
│ octocat · your-org Thursday, 15 October │
╰──────────────────────────────────────────────────────────────────────────╯
╭───────────────╮ ╭───────────────╮ ╭───────────────╮ ╭───────────────╮
│ 12 │ │ 2 │ │ 1 │ │ 4 │
│ OPEN │ │ OVERDUE │ │ DUE TODAY │ │ NEXT 7 DAYS │
╰───────────────╯ ╰───────────────╯ ╰───────────────╯ ╰───────────────╯
▌ OVERDUE 2 ──────────────────────────────────────────────────────────────
● api-gateway#412 Rotate the signing keys before the audit
In progress ◷ Oct 9 · 6 days ago ◇ Q4 hardening ▸ Platform security
● billing#88 Backfill the invoice totals
Todo ◷ Oct 13 · 2 days ago ▸ Platform
▌ DUE TODAY 1 ────────────────────────────────────────────────────────────
◉ web#1204 Ship the new onboarding flow
In review ◷ Oct 15 · today ◇ v3.2 ▸ Product
Requirements
- Go 1.26 or newer, to build
- A GitHub token, from the
ghCLI or the environment
Install
go install github.com/patrickjmcd/gh-todo@latest
Or build from a clone:
make install # builds and copies to ~/.local/bin/gh-todo
To install somewhere else, set PREFIX:
make install PREFIX=/usr/local/bin
Authenticate
gh-todo reads a token from GITHUB_TOKEN, then GH_TOKEN, then gh auth token.
If you already use the gh CLI, no setup is needed.
For GitHub Enterprise Server, set the host:
gh-todo --host github.example.com
The host also reads from GH_TODO_HOST, the host config key, or GH_HOST.
gh-todo derives the API URL from it: https://api.github.com/graphql for
github.com, https://HOST/api/graphql otherwise.
For due dates and statuses that live in GitHub Projects, the token needs the
project or read:project scope. Without it, gh-todo prints a warning and
falls back to milestones and body markers.
Use
gh-todo # open work, grouped by due date
gh-todo --completed # add what you closed in the last 7 days
gh-todo --completed --days 30 # widen the completed window
gh-todo --reviews # add PRs waiting on your review
gh-todo --org your-org # restrict to one organization
gh-todo --repo owner/name --repo owner/x # restrict to specific repositories
gh-todo --due-only --sort due # only dated work, soonest first
gh-todo --watch # stay open, refreshing every minute
gh-todo --compact # one line per task, as a table
gh-todo --format markdown > todo.md # a Markdown checklist
gh-todo --format json | jq '.buckets' # machine-readable output
Short forms: -c completed, -d days, -f format, -o org, -r repo,
-s sort, -u user, -w watch.
Groups
Open work falls into one of seven groups: Overdue, Due today, Due tomorrow, Due this week, Later, No due date, and Blocked. Empty groups are skipped.
Blocked comes last and takes precedence over every due-date group, because blocked work is not something you can act on. A task counts as blocked when its Projects V2 status or one of its labels contains "blocked". Blocked tasks are also left out of the overdue, due-today, and next-7-days counts, so the summary tiles only ever count work you can pick up.
Where due dates come from
GitHub issues have no native due date, so gh-todo checks three sources in order
and uses the first hit:
- A Projects V2 date field whose name matches
due,deadline,target date,end date, orship by. Fields namedstartare ignored. - The milestone due date.
- A
due: YYYY-MM-DDor📅 YYYY-MM-DDmarker in the title or body.
The JSON output records which source was used in due_source.
Where status comes from
- A Projects V2 single-select field named
Status, such asIn progressorBlocked. - Otherwise a derived value:
Draft,Needs review,Approved,Changes requested, orMergedfor pull requests;In progressorBlockedfrom labels for issues;Openotherwise.
Configuration
Settings resolve in this order, highest first:
- Flags
- Environment variables, prefixed
GH_TODO_ - The config file
- Built-in defaults
Every config key matches a flag name, so --no-prs is no-prs in the file and
GH_TODO_NO_PRS in the environment.
Write a commented starter file:
gh-todo config init # writes ~/.config/gh-todo/config.yaml
gh-todo config path # print the path in use
gh-todo config show # print resolved settings and where each came from
The file lives at $XDG_CONFIG_HOME/gh-todo/config.yaml, falling back to
~/.config/gh-todo/config.yaml. A config.yaml in the working directory is
picked up too. Point somewhere else with --config:
org:
- your-org
completed: true
days: 14
compact: true
interval: 30s
A missing file is fine. A malformed one prints a warning and falls back to
defaults. A --config path that cannot be read is an error.
Live view
--watch keeps the list on screen and refreshes it on an interval, default one
minute:
gh-todo --watch # refresh every minute
gh-todo --watch --interval 30s # refresh twice a minute
gh-todo --watch --compact # the table view, live
The live view runs in the alternate screen, so your scrollback is untouched when you quit. Keys:
| Key | Action |
|---|---|
↑ ↓ j k |
Scroll the list |
PgUp PgDn |
Scroll a page |
r |
Refresh now |
q Esc Ctrl-C |
Quit |
The status bar shows how long ago the list refreshed, the countdown to the next refresh, and how far you have scrolled. Your scroll position survives a refresh. Failed refreshes show the error in the status bar and keep the last good list on screen. Hyperlinks stay clickable.
--watch needs a terminal and the text format; it refuses to run when output is
piped. The minimum interval is 10s, to stay well inside the GitHub API rate
limit.
Hyperlinks
Each task reference is an OSC 8 hyperlink to the issue or pull request, so you can click or ⌘-click it instead of copying a URL. iTerm2, WezTerm, Kitty, Ghostty, and the VS Code terminal all support this; terminals that do not, such as Apple Terminal, ignore the sequence and show plain text.
Links are emitted only when output goes to a terminal, so piped and redirected
output stays clean. Turn them off with --no-links or NO_HYPERLINKS=1. Use
--urls to print the full URL under each task instead.
Views
The default view gives each task two lines: the reference and title, then a status pill, a due-date tag, and the milestone, project, and labels.
--compact gives each task one line in a table — reference, title, status, and
due date — which scans faster when you have dozens of open items.
Flags
| Flag | Default | Description |
|---|---|---|
-c, --completed |
false |
Include recently completed tasks |
-d, --days N |
7 |
Lookback window in days for completed tasks |
--reviews |
false |
Also include pull requests waiting on your review |
--no-prs |
false |
Issues only |
--due-only |
false |
Only show tasks that have a due date |
-o, --org NAME |
— | Restrict to an organization; repeatable |
-r, --repo OWNER/NAME |
— | Restrict to repositories; repeatable |
-u, --user LOGIN |
@me |
Build the list for another GitHub user |
-f, --format FMT |
text |
text, markdown, or json |
-s, --sort KEY |
due |
due, updated, or repo |
--limit N |
200 |
Maximum tasks to fetch per query |
-w, --watch |
false |
Stay open and refresh on an interval |
--interval D |
1m |
Refresh interval for --watch, minimum 10s |
--compact |
false |
One line per task, rendered as a table |
--urls |
false |
Print the URL under each task |
--no-color |
false |
Disable ANSI color; NO_COLOR also works |
--no-links |
false |
Disable OSC 8 hyperlinks; NO_HYPERLINKS also works |
--host HOST |
github.com |
GitHub host, for GitHub Enterprise Server |
--config PATH |
— | Use a specific config file |
--version |
— | Print the version and exit |
Color turns off automatically when output is piped to a file, and the layout sizes itself to the terminal width.
Shell completion
gh-todo completion zsh > "${fpath[1]}/_gh-todo" # zsh
gh-todo completion bash > /usr/local/etc/bash_completion.d/gh-todo
gh-todo completion fish > ~/.config/fish/completions/gh-todo.fish
Daily list
To see the list every time you open a shell, add this to ~/.zshrc:
alias todo='gh-todo --completed --days 3'
alias todos='gh-todo --watch'
Contributing
Issues and pull requests are welcome. Before opening a pull request, run:
gofmt -l .
go vet ./...
go test -race ./...
CI runs the same three checks on Linux and macOS.
License
MIT. See LICENSE.