#tasks #tui #notes #task #todo #config-file #text-file

app taskfinder

Keep your project-related tasks where they belong - with your notes on the project! This program, a terminal user interface (TUI), will extract and display them

8 releases (1 stable)

1.0.0 May 8, 2024
0.8.0 Mar 26, 2024
0.7.0 Mar 20, 2024
0.6.0 Mar 19, 2024
0.3.1 Jan 19, 2024

#153 in Command line utilities

Download history 301/week @ 2024-02-20 40/week @ 2024-02-27 6/week @ 2024-03-05 1/week @ 2024-03-12 287/week @ 2024-03-19 166/week @ 2024-03-26 62/week @ 2024-04-02 10/week @ 2024-04-09 180/week @ 2024-05-07

180 downloads per month




Keep your project-related tasks where they belong - with your notes on the project! This program, a terminal user interface (TUI), will extract and display them.

Install with cargo install taskfinder and then run tf to start it.

See the changelog for changes with each release.


For years, I used a task SaaS app to keep track of what I needed to do. However, I disliked this large amount of data about me and what I do being on someone else's server, and unencrypted to boot. So I started to just use pen and paper, organized by date. However, this doesn't allow for easy capturing of tasks that don't really have to be done on a particular date, or that belong to a single project. So I then started to write down tasks in my digital-file-based note-taking system (you can read more about that here), where I also keep project notes. But then I had to start searching for them, and sometimes they were getting lost in the mix. So, taskfinder was born.

Tasks, task sets, files, and configuration

How tasks get identified and extracted from files:

  • the term "TODO" (in caps) must be in the text of the file
  • excluding whitespace, a line in a file starting with [ ] or [] identifies an incomplete task
  • excluding whitespace, a line in a file starting with [X] or [x] is a completed task
  • excluding whitespace, a line in a file starting with [/] is a partially completed task

A "task set" is a group of tasks. All tasks following a line containing "TODO" will be in a task set labelled as the full text of that line. Another line containing "TODO" within a file will end one task set and start another.

By default, files are defined as .md and .txt files in your home directory. However, both the directory and the extensions are configurable. Upon first run, this program will create a configuration file at $HOME/taskfinder/config.toml. Edit the file to change these defaults. Also configurable are:

  • how many days constitutes a file being stale
  • whether to include completed tasks by default
  • the text in a file that indicates a priority level ("priority markers")


Priorities can be set at either the file level or the task-set level. To set the priority on a file, use one of the priority markers (see below) within the first two lines of a file. To set one at the task-set level, include one of the priority markers on the line that starts a task set, i.e. a line containing "TODO". Task sets without a priority will inherit the priority of the file, if any.

Priorities can be a string you define, but by default they are, from highest to lowest priority: pri@1, pri@2, pri@3, pri@4, pri@5. To change these, modify the priority_markers list in the configuration file. Note, however: there must be five of them.

Results will automatically be sorted by these priorities, with the tasks from files without one of these markers shown last.

Toggle the priority filter by pressing 1-5.


Unlike priorities, tags are defined at the file level only, and they must be in the first two lines of the file.

Tags are actually just whatever string you pass, so you may follow whatever convention you like. I use the form "@sometag".

Press t to open a dialog box to enter a tag.

Due dates

There is preliminary support for due dates. If a task (see above on how a task is identified) contains a due date (in the form "due:YYYY-MM-DD"), it will be highlighted. Pressing d will show only those files that contain an incomplete task with a due date.


If a file is considered stale (last modified more than days_to_stale days ago, with default of 365 initially set in the config file), no tasks from it will be returned. Press s to toggle between stale and non-stale files/tasks. A file can also be explicitly marked as stale by including the text "@stale" within it.


The first time during a day that the program is run, it will log the number of complete and incomplete tasks - both overall and by priority. Press l to show this log.

Example files

Here is the text of two example files to demonstrate the conventions/expectations described above. Explanatory comments for our purposes here start with a '#'.

A file with no file-level priority:

Tree planting                         # <- first line/title of the file
@thegreatoutdoors                     # <- tags; no priority at the file level.

TODO (preparation) (pri@1):           # <- a task set with level 1 (highest) priority.
  [x] identify sapling to transplant  # <- a completed task

TODO (actual planting) (pri@2):       # <- a task set with a level 2 priority.
  [/] dig a hole                      # <- a partially complete task
  [ ] dig up the sapling              # <- an incomplete task
  [] plant sapling                    # <- also an incomplete task

Another possible configuration:

Tree planting                         
@thegreatoutdoors pri@2               # <- priority 2 at the file level

TODO (preparation):                   # <- a task set with no priority
  [x] identify sapling to transplant  
    - maybe the holly?                # <- a note, ignored by program

TODO:                                 # <- another task set with no priority
  [/] dig a hole                        
  [ ] dig up the sapling                
  [] plant sapling (due:2025-10-01)   # <- an incomplete task with a due date


~246K SLoC