things

Things

A terminal application to help keep track of all the things you're juggling at work or life in general.

Things Dir

By default it's ~/.things/.

You can override this with THINGS_DIR.

Thing Files

Things are files in THINGS_DIR/things/.

When you create a new thing, a file is created and it's opened with EDITOR.

---
title: Thing
type: chore
priority: 5
---

Do a thing!

Frontmatter

Title

Use title: to set a thing's title.

Note

You can add a note: field to provide additional context about the current state of a thing. The note is displayed next to the title in faint text:

> Important thing | blocked waiting for other thing

Where "blocked waiting for other thing" is the note. This is useful for tracking brief, dynamic information that may change as work progresses.

Priority

You can assign things an integer priority value. Things are grouped by priority with blank lines between groups:

• Priorities 0-4: Each is its own group, separated by blank lines
• Priority 5+: All grouped together without separation

Within each priority group, things are sorted by your chosen sort mode (age/priority/type).

Done, Pause

Add done: true to a thing to mark it as done. It will be removed from the default list.

Add pause: true to pause it. This just dims its color a little to indicate you can skip it for now.

You can filter by each of these. This is documented below.

Type

Finally, type: allows you to categorize things by type. It's value refers to the name of a type file which is explained in the next section.

Type Files

Things have types that you define in THINGS_DIR/types/.

You can create a new type from within the application by switching to type mode (>) and pressing n. You'll be prompted to enter a type name, then the type file will be created and opened in your EDITOR.

For example, a type file THINGS_DIR/types/chore.md might look like:

---
color: '#33ffc1'
---

Random, small task. Something otherwise untracked.

Time Files

The amount of time a thing is open in your editor is tracked with csv files in ~/.things/time/. Each thing has a file here as well. A row is added with the open and close time every time you open a thing in order to calculate the cumulative time you've spent working on a thing.

Thing Directories

For complex things that require extended research, multiple files, or collaboration with AI tools, you can create a directory for it.

Directories are stored in THINGS_DIR/things-deep/{thing-id}/.

Things that have directories show a * indicator in the list.

Actions

// mode

> = switch between "thing" and "type" modes

/ = search ("thing" mode only)

? = toggle help

// navigation

k = cursor up

j = cursor down

ctrl+u = cursor up 5

ctrl+d = cursor down 5

g = set cursor to first

G = set cursor to last

// filter ("thing" mode only)

C = current, done: false (default)

D = done: true

A = all, no filter

P = pause: true

// sort ("thing" mode only)

a = sort things by age

p = sort things by priority (default)

t = sort things by type and priority

// display

# = toggle line numbers

// edit

n = create a new thing or type and open in $EDITOR

enter = open thing or type in $EDITOR

E = open thing directory in $EDITOR ("thing" mode only)

ctrl+e = open thing time file in $EDITOR ("thing" mode only)

ctrl+x = delete thing ("thing" mode only)

// quit

ctrl+c, q = quit