nilock / tuido

a text user interface for navigating [x]it! spec todo across multiple files

An opinionated terminal interface for efficient browsing and management of [x]it! formatted todo items. Inspired, loosely, by Getting Things Done (David Allen) and informed by various entries of the self-help skills & habits genre (Charles Duhigg, James Clear, Anders Ericsson, etc).

Features

• searches the working directory recursively for [x]it! compatible items in .xit, .md, and .txt files
• compactly displays pending todos and offers navigation between todo and done
• allows for creating new items, updating existing items, and persists updates to disk
• search / filter todos by keywords
• one-button (p) pomodoro mode for timeboxed focus on individual items; tracks overall time spend
• one-button (z) progressive snooze parks items for 1,2,3,5,8,... days
• progressive deterrence for adding new items
• respect for .gitignore configs (ie, don't parse a billion node_modules files)

Usage

From some directory containing [x]it! files / items, or from anywhere to recover items written in app:

tuido

In app controls

• ?: help
• n: make a new item
• slected item controls:
  • [space]: set status open
  • x, X: set status checked (done)
  • s, ~: set status obsolete
  • a, @: set status ongoing
  • e: edit item text
  • p: enter a pomodoro session for item
  • z: snooze this item (set a later active date)
  • !/1: bump/decrement the importance modifier on this item
• [tab]: switch between pending and done items
• /: filter list by search terms (plain-old-string-matching)
• [up], [down]: navigate items
• q: quit

Shorthands

tuido permits some shorthands for authoring items with time & date content. Shorthand timespans take the form NT, where N is some number, and T is one of m, h, d, w, M, or y (minute, hour, day, week, month, and year). 4d is four days, 253h is 253 hours, etc.

An item shorthand is one of:

• d (due)
• a (active after)
• r (recurs every)
• e (estimate)

followed by a shorthand timespan.

Examples:

• english 1101 comparison paper d2w will expand into english 1101 comparison paper #due=YYYY-MM-DD, with the date appropriately filled in for two weeks from now
• call mom r1w will expand into call mom #repeat=1w, which will reschedule itself one week into the future each time it is marked complete.
• a1m catch up on stranger things expands into #active=YYYY-MM-DD catch up on stranger things, with the date one month from now. This hides the item from view until the active date - essentially setting yourself a reminder for the future.
• fix the sink e2h expands into fix the sink #estimate=2h

Sorting

Displayed items are sorted like this:

1. First, list the most important items (prefixed with !)
2. Then, list those items with set due dates, from earliest to latest
3. Finally, items are grouped according to the order in which they were parsed from disk. This has the effect of grouping items from the same file together.

Configuration

Tuido writes new items by default to $HOME/.tuido/YYYY-MM-DD.xit. To set a different write location, create file tuido.conf in the user config directory ($HOME/.config in linux, $HOME/AppData in windows). The write location can be a file, which will be appended to, or a directory, which whill recieve datestamped .xit files as in the default setting.

writeto=~/mysingletodolist.txt

writeto=~/todos

Include a .tuido file in individual directories to add filetypes for parsing along that subtree.

extensions=go,js,cpp

Default configuration values are:

writeto=~/.tuido
extensions=xit,txt,md

Development

0. install go (see https://go.dev)
1. (suggested) read the in-readme tutorial for https://github.com/charmbracelet/bubbletea
2. clone repo
3. go run .

tuido is dogfooding. The project's .tuido file:

• instructs tuido to parse items in .go files as well as the defaults.
• instructs tuido to write new items directly to this readme

Result being that the app, running in test, contains a good running list of development todos & a convenient method to append to the roadmap.

Licence

GPL

Roadmap

• #feat allow for copying current item to clipboard (via ctrl-C?)
• #feat make new-items repsect the filetype being written to (leading comment slashes for code files, leading bullet for readme, etc)
• [@] process #dates
  • from items themselves
    • from #due tags
    • according to [x]it spec
  • (for creation #date) from the names of an item's source file
• #feat #ui provide details / context (preview into source file) on current selected item, or quick open of an item's source location
• #feat allow plain-text fuzzy text search/filter of item body text (only tag names currently)
• have infrastructure for managing task-specific checklist files (beach trip) #feat #ui #maybe
• [@] #feat #maybe accept command line flags or config for other file extenstions, source directories, etc
• #feat #maybe fully respect / implement the [x]it spec
• tag v0.0.1, produce platform builds
• add command-line flags for
  • ignoring current working dir (ie, run only in the write-to directory) tuido --norecurse
  • printing a list to stdout, rather than launching an app. tuido --print
  • viewing and setting config. tuido --config extensions=xit,md,go,js,ts
• #maybe allow marking items done or obsolete during a pomodoro (closes the pomo)
• #maybe mark items [ongoing] when entering a pomo
• #maybe add a #spent=timespan tag which gets updated on pomo exits & by shorthand
  • #maybe generate reports on #estimate=x vs #spent=y, categorizing by tag, etc

tuido's Issues

How to sort the todo list?

Firstly, thank you for this project, it's really helpful to me. I keep my notes in *.md files and when to-do items arise I add them in xit notation. Having all my to-do's in one place makes a huge difference for me!

My question: is there a way to sort the list alphabetically?

Here is roughly how my "todo" tab looks at the moment:

[ ] PROJ-2878 Adding a review for the item gives an error
[@] #! menu code needs refactoring
[@] #! PROJ-2890 problem with playlist
[@] #! PROJ-2832 Remove unneeded directory
[ ] #! PROJ-2746 completely remove the xxx integration code
[ ] #!!!! In January I need do something super important
[ ] ask my manager for certain equipment
[ ] Check software version of certain dependency

It would be great if I could sort it, is there a way to do that? Thanks!

[esc] slower than [enter] when exiting file peek mode

Either key returns to main screen, but only [enter] feels instant.

[feature] Be able to de-escalate an item

Unless I'm missing something in the docs, I'm unsure if I could de-escalate an item (remove the ! from the item). Perhaps ; could be the syntax for de-escalating?

add a (hot) reload option

while running, if other tools add an item to a file in scope, tuido should be able to

approaches:

• manual: hit, say, r to refresh against from configured sources. Equivalent to shutting down and restarting
• automatic: with a filewatcher, scrape files in scope as they change

Slice Range error on "empty" markdown item

Caught panic:

runtime error: slice bounds out of range [4:3]

Restoring terminal...

goroutine 1 [running]:
runtime/debug.Stack()
        /opt/hostedtoolcache/go/1.18.10/x64/src/runtime/debug/stack.go:24 +0x65
runtime/debug.PrintStack()
        /opt/hostedtoolcache/go/1.18.10/x64/src/runtime/debug/stack.go:16 +0x19
github.com/charmbracelet/bubbletea.(*Program).StartReturningModel.func3()
        /home/runner/go/pkg/mod/github.com/charmbracelet/[email protected]/tea.go:359 +0x95
panic({0x7bfd40, 0xc000206a50})
        /opt/hostedtoolcache/go/1.18.10/x64/src/runtime/panic.go:844 +0x258
github.com/nilock/tuido/tuido.(*Item).GetContext(0xc0005b0368, 0x1c)
        /home/runner/work/tuido/tuido/tuido/tuido.go:208 +0x649
github.com/nilock/tuido/tui.(*peekScreen).View(0xc0005b0368, 0x1e, 0x3?, 0xc000206d38?)
        /home/runner/work/tuido/tuido/tui/peek.go:21 +0x85
github.com/nilock/tuido/tui.tui.View({{{0xc60240, 0x3, 0x3}, {0xc000206d38, 0x12}}, {0x0, 0x0}, {0xc0003d26e0, 0x1, 0x1}, ...})
        /home/runner/work/tuido/tuido/tui/view.go:165 +0xc7d
github.com/charmbracelet/bubbletea.(*Program).StartReturningModel(0xc00011a080)
        /home/runner/go/pkg/mod/github.com/charmbracelet/[email protected]/tea.go:549 +0x1398
github.com/charmbracelet/bubbletea.(*Program).Start(...)
        /home/runner/go/pkg/mod/github.com/charmbracelet/[email protected]/tea.go:556
github.com/nilock/tuido/tui.Run()
        /home/runner/work/tuido/tuido/tui/tui.go:68 +0x4ae
main.main()
        /home/runner/work/tuido/tuido/main.go:8 +0x17

when attempting to preview item:

> [ ]

from file:

- [ ]

Duplicate entries for a user defined directory

Hello. I love the project, but I had some issues when I was trying to incorporate it into my workflow.

I edited the .tuido file, removed "go" from the extensions, and changed writeto to be the full path to my own notes folder. This notes folder only contains a single .md file right now.

When I run the program, it loads the notes from the file, but each entry is duplicated. So my original file that contains:
[ ] Task 1
[ ] Task 2

In the tuido interface it looks like:
[ ] Task 1
[ ] Task 2
[ ] Task 1
[ ] Task 2