The Getting Things Done Terminal User Interface

A TUI/CLI/API for personal productivity built around GTD (Getting Things Done).

What it does

Capture items to an inbox and triage them into projects
Track projects with contexts, next actions, and follow-up dates
Log completions and auto-reschedule recurring items
Defer, snooze, and review Someday/Maybe lists
Filter by context for focused work sessions

Requirements

Python 3.12+
fzf (for interactive menus)
A Notion integration token (for gtd)

Installation

cd gtd
uv sync
uv pip install -e .

This installs the gtd command.

Usage

Default: the TUI

gtd

With no subcommand, gtd launches the Textual TUI — tabs for Today, Next Steps, Inbox, Projects, Waiting For, Incubation, Recurring, Someday, and Lists, plus a guided Weekly Review. This is the primary interface.

CLI subcommands

Each of these also works standalone, e.g. for scripting or quick one-offs without opening the TUI:

Command	Description
`gtd init`	Set up or upgrade the GTD Notion database.
`gtd triage`	Interactively process items needing triage.
`gtd filter`	Filter by context name (e.g. gtd filter Phone).
`gtd today`	Show actionable items for today.
`gtd snooze`	Snooze today's items until tomorrow.
`gtd log`	Log a note and reschedule a recurring item.
`gtd done`	Mark a current project as done (archives it).
`gtd review`	Run the GTD weekly review ritual.
`gtd update`	Update fields on an existing project.
`gtd defer`	Defer a project by setting a follow-up date.
`gtd someday`	Review Someday/Maybe items — keep, activate, or drop.
`gtd capture`	Quick-capture an item to the GTD inbox.
`gtd areas`	Manage Areas of Focus (Notion 'Area' select options).
`gtd areas add`	Add a new Area of Focus.
`gtd areas remove`	Remove an Area of Focus.
`gtd contexts`	Manage GTD contexts (Computer, Home, Phone, etc.).
`gtd contexts add`	Add a new context.
`gtd contexts remove`	Remove a context.
`gtd contexts rename`	Rename a context and update all items with that context.
`gtd dump`	Rapid-fire brain dump — capture everything, triage later.
`gtd config`	View or set GTD configuration.
`gtd config notes-editor`	Set notes editor: inline (TUI TextArea) or external (uses $EDITOR).
`gtd fzf`	Launch the legacy fzf-based interactive GTD menu.
`gtd tui`	Launch the interactive GTD TUI.
`gtd api`	Start the GTD HTTP API server (requires: pip install gtd[api]).

Legacy fzf menu

gtd fzf

An older fzf-driven menu predating the TUI, kept for anyone who prefers it:

Category	Action
Do	Today
Do	Log & Reschedule
Do	Snooze until tomorrow
Do	Capture new item
Do	Brain dump
Do	Triage inbox
Manage	Update project
Manage	Defer project until date
Manage	Waiting For
Manage	Mark done (delete)
Review	Weekly Review
Review	Review Someday/Maybe
View	View all projects
View	Filter by context

HTTP API

A small Flask app (gtd api) exposes GTD operations over HTTP, primarily so you can drive gtd from iOS Shortcuts (or any other HTTP client) without opening a terminal — capture a thought, check today's actionable items, or triage the inbox from your phone.

There's no central server in the loop: you run this yourself, against your own Notion integration and database. Your GTD data lives in your Notion account under your own token.

Install: uv pip install "gtd[api]" Run: gtd api (default 0.0.0.0:8000) or gtd api --port 9000 Auth: Bearer token — set GTD_API_KEY on the server, then pass Authorization: Bearer <key> on every request.

Method	Path	Description
`POST`	`/capture`	Add an item to the inbox. Body: {"header": "..."}.
`GET`	`/contexts`	Get active contexts.
`GET`	`/inbox`	Get all Triage entries (inbox).
`GET`	`/list-categories`	Return canonical list categories from Notion (for debugging/UI use).
`GET`	`/list/<category>`	Get all entries in a specific list category.
`GET`	`/next-steps`	Get actionable next steps, optionally filtered by context.
`GET`	`/triage-schema`	Get schema for triage workflow: statuses and contexts per status.
`POST`	`/triage/<page_id>`	Atomically triage an entry with full data.

Updating this README

The fzf menu table, CLI command table, project tree, and HTTP API table above are all extracted from source: cli.py's menu_items list and click command tree, module docstrings under src/gtd/ and scripts/, and the @app.get/@app.post/... routes in api.py, respectively. After changing any of these, regenerate everything:

python scripts/update_readme.py

A pre-commit hook (sync-readme) runs this automatically whenever any src/gtd/**/*.py, scripts/**/*.py, or README.md file changes, so these sections shouldn't drift in practice.

Data storage

GTD: Notion database (configured via gtd init or NOTION_NOTES_TOKEN / NOTION_PROJECTS_DB_ID env vars)
Weekly review state, Areas of Focus, list categories: JSON files in ~/.local/share/gtd/

Project structure

src/gtd/
├── api.py          # Thin Flask wrapper around GTD Notion operations for iOS Shortcuts.
├── cli.py          # GTD CLI — David Allen's Getting Things Done powered by Notion.
├── gtd_tui.py      # Unified GTD TUI.
├── storage.py      # Local JSON I/O for weekly review state and habit dates.
├── tui.py          # Shared Textual widgets and modals for the GTD TUI.
├── ui.py           # fzf helpers, prompts, and formatting shared across CLI commands.
└── notion/
    ├── capture.py  # Quick-capture items to the GTD inbox (Notion Projects table).
    ├── client.py   # Notion REST API client (httpx).
    ├── commands.py # Manage commands: mark done, defer, waiting for, notion dispatch.
    ├── config.py   # Configuration management for GTD CLI.
    ├── display.py  # Display formatting for Notion entries.
    ├── entries.py  # Entry listing, selection, and field editing.
    ├── init.py     # Database initialization and schema management for GTD CLI.
    ├── log.py      # Log, reschedule, and recurring-item utilities.
    ├── models.py   # Parse Notion page properties into simple data structures.
    ├── review.py   # Weekly review and Someday/Maybe review flows.
    ├── schema.py   # GTD Notion database schema definition — single source of truth.
    ├── today.py    # Today view and snooze commands.
    └── triage.py   # Interactive triage flow for processing inbox items.
scripts/
├── check_commit_msg_early.py # Validate the commit message during the *pre-commit* stage, not commit-msg.
└── update_readme.py          # Update README.md menu, CLI, tree, and HTTP API sections from source.

Metadata

Release files for gtd-tui 0.2.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for gtd-tui 0.2.2
File	Size	Uploaded
gtd_tui-0.2.2.tar.gz	86.9 kB	Jul 30, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for gtd-tui 0.2.2
File	Interpreter	ABI	Platform	Reset
gtd_tui-0.2.2-py3-none-any.whl 69.6 kB Jul 30, 2026	Python 3	none	any	Details

Total release size: 156.5 kB

Release files / gtd_tui-0.2.2.tar.gz

Download URL	gtd_tui-0.2.2.tar.gz
Size	86.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`14c1c7a6936da397ce27e730cb47910c79341ed6336fff7aeae1adba5d22acd5`
BLAKE2b-256 checksum How to use checksums	`c63eee9cfe44b3ea192de267fdb29eaed7e84c78e5a6ce70e755ef53de191f96`
Upload date	Jul 30, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/dannybrown37/gtd
Publishing commit: github.com/dannybrown37/gtd/tree/098b79b665e97b424137dcd8a2956cff41820196

Workflow

Publishing configuration: github.com/dannybrown37/gtd/blob/098b79b665e97b424137dcd8a2956cff41820196/.github/workflows/publish.yml
Publishing logs: github.com/dannybrown37/gtd/actions/runs/30503992434/attempts/1

Artifact

Subject: gtd_tui-0.2.2.tar.gz
SHA-256 checksum: 14c1c7a6936da397ce27e730cb47910c79341ed6336fff7aeae1adba5d22acd5 Verifying attestations

Release files / gtd_tui-0.2.2-py3-none-any.whl

Download URL	gtd_tui-0.2.2-py3-none-any.whl
Size	69.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`3c475eedcc89380a3d359a19f3f9825b33b3b0f3b6d37c3bc7c794ac18e04fda`
BLAKE2b-256 checksum How to use checksums	`bc766e5948e2c621d775d3d4cfdcaad2f439255b212fe9a14973ed04a01b4427`
Upload date	Jul 30, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/dannybrown37/gtd
Publishing commit: github.com/dannybrown37/gtd/tree/098b79b665e97b424137dcd8a2956cff41820196

Workflow

Publishing configuration: github.com/dannybrown37/gtd/blob/098b79b665e97b424137dcd8a2956cff41820196/.github/workflows/publish.yml
Publishing logs: github.com/dannybrown37/gtd/actions/runs/30503992434/attempts/1

Artifact

Subject: gtd_tui-0.2.2-py3-none-any.whl
SHA-256 checksum: 3c475eedcc89380a3d359a19f3f9825b33b3b0f3b6d37c3bc7c794ac18e04fda Verifying attestations