vault-tasks is a TUI Markdown task manager.

It will parse any Markdown file or vault and display the tasks it contains.

./test-vault
├── dir
│   ├── subdir
│   │   ├── test_1.md
│   │   ├── test_2.md
│   │   └── test_3.md
│   └── test_0.md
├── example_physics_class.md
├── example_vault-tasks_project.md
└── test.md

I made this tool because I wanted to integrate my task system directly inside my Second Brain.

Markdown tasks are very easy to integrate with knowledge/projects and are source-control-friendly.

I wrote a blog post explaining my workflow and how I use vault-tasks if you're interested. (It's dated, I introduced new features since then (trackers))

I also spend most of my writing time in the terminal (Helix) and do not rely on heavy external software.

• Task Parser (see Usage)
  • Subtasks
  • Supports relative dates
  • special today tag and regular tags
  • descriptions, priority, completion percentage
• Trackers (or recurrent tasks)
• Navigate vault
• Edit tasks or open in default editor
• Search through tasks (sort and filter)
• Calendar view
• Time Management tab (Pomodoro & Flowtime)

I plan on adding a new tab about Trackers where you'll be able to see nice statistics about your trackers. For now, you can see your trackers in the Explorer tab.

cargo install vault-tasks

You can get it from nixpkgs 25.05 or directly from this repo's flake:

vault-tasks = {
  url = "github:louis-thevenet/vault-tasks";
  inputs.nixpkgs.follows = "nixpkgs";
};

And use the package in your configuration: inputs.vault-tasks.packages.${pkgs.system}.default

git clone https://github.com/louis-thevenet/vault-tasks.git
cd vault-tasks
cargo build --release

See vault-tasks --help for basic usage.

<!-- An example task in your markdown file -->

- [ ] An example task #tag tomorrow p1
      A description
      of this task
  - [x] A subtask today @today
  - [/] Another subtask 10/23 @today c50
    Partly done
  - [-] This one is canceled

• Task states are Done (x), To-Do ( ), Incomplete (/) and Canceled (-)

• @today allows you mark a task for today while keeping a due date. It will show up with a ☀️ in vault-tasks.

• Relative dates are always replaced by literal dates once vault-tasks is run. Thanks to this, vault-tasks does not store any data except its config file.

• Other tokens will be part of the title of that task

• Descriptions and subtasks are declared using indents (see configuration)

This is what you will see in the preview of this README.md in vault-tasks:

<!-- An example tracker in your markdown file -->

Tracker: Arts Enjoyment (2025-06-08)

| Every day  | inspiration | medium   | cost | social | notes                      |
| ---------- | ----------- | -------- | ---- | ------ | -------------------------- |
| 2025-06-08 | 8           | painting | 15   | [ ]    | watercolor landscape       |
| 2025-06-09 | 6           | music    | 0    | [x]    | street musician downtown   |
| 2025-06-10 | 9           | theater  | 45   | [x]    | incredible Shakespeare     |
| 2025-06-11 | 7           | digital  | 12   | [ ]    | new photography exhibition |
| 2025-06-12 | 5           | craft    | 8    | [ ]    | pottery wheel attempt      |
| 2025-06-13 | 8           | film     | 10   | [x]    | foreign cinema festival    |
| 2025-06-14 | 9           | dance    | 20   | [x]    | salsa class breakthrough!  |
| 2025-06-15 |             |          |      |        |                            |
| 2025-06-16 |             |          |      |        |                            |
| 2025-06-17 |             |          |      |        |                            |
| 2025-06-18 |             |          |      |        |                            |

You start by writing Tracker: followed by your tracker's name. You add a starting date such as an ISO date or a relative date.

Then you can start vault-tasks, so it creates blank entries for you. By default, it will fill the entries until the current date + 3 blank entries. This is also useful to reformat your table if you don't have a Markdown formatter.

Here is a basic template:

Tracker: Name (today)

| daily | notes |

Vault-tasks would reformat it to:

Tracker: Name (2025-06-15)

| Every day  | notes |
| ---------- | ----- |
| 2025-06-15 |       |
| 2025-06-16 |       |
| 2025-06-17 |       |
| 2025-06-18 |       |

Frequencies can be:

• Every <hour|day|week|month|year>
• hourly, daily, weekly, monthly, yearly

Data types are:

• Boolean type: [ ] or [x]
• Score type: any integer
• Note type: any text
• Blank

Be careful not to change type within a column, vault-tasks will replace the wrong type with a blank entry.

This is what you will see in the preview of this README.md in vault-tasks:

Check the key map within the app with ?

You can start already focused on a tab by using one of the CLI subcommands:

vault-tasks explorer # is the default
# Or
vault-tasks filter
vault-tasks time
vault-tasks calendar

You can also output the content of a vault in standard output using

vault-tasks stdout

Example output:

vault-tasks -v ./README.md stdout
README.md
‾‾‾‾‾‾‾‾‾
  Vault-tasks
  ‾‾‾‾‾‾‾‾‾‾‾
        Usage
        ‾‾‾‾‾
                Writing tasks
                ‾‾‾‾‾‾‾‾‾‾‾‾‾
                        ❌ An example task
                        📅 2025-06-16 (tomorrow) ❗1
                        #tag
                        A description
                        of this task

                                ✅ A subtask
                                ☀️ 📅 2025-06-15 (today)


                                ⏳ Another subtask
                                ☀️ 📅 2025-10-23 (in 4 months) [🟩🟩⬜️⬜️⬜️ 50%]
                                Partly done


                                🚫 This one is canceled


                Writing Trackers (or recurrent tasks)
                ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
                        Tracker: Arts Enjoyment (2025-06-08)

                        | Every day  | inspiration | medium   | cost | social | notes                      |
                        |------------|-------------|----------|------|--------|----------------------------|
                        | 2025-06-08 | 8           | painting | 15   | [ ]    | watercolor landscape       |
                        | 2025-06-09 | 6           | music    | 0    | [x]    | street musician downtown   |
                        | 2025-06-10 | 9           | theater  | 45   | [x]    | incredible Shakespeare     |
                        | 2025-06-11 | 7           | digital  | 12   | [ ]    | new photography exhibition |
                        | 2025-06-12 | 5           | craft    | 8    | [ ]    | pottery wheel attempt      |
                        | 2025-06-13 | 8           | film     | 10   | [x]    | foreign cinema festival    |
                        | 2025-06-14 | 9           | dance    | 20   | [x]    | salsa class breakthrough!  |
                        | 2025-06-15 |             |          |      |        |                            |
                        | 2025-06-16 |             |          |      |        |                            |
                        | 2025-06-17 |             |          |      |        |                            |
                        | 2025-06-18 |             |          |      |        |                            |

The config.toml contains the default configuration which can be generated using vault-tasks generate-config.

In $HOME/.config/vault-tasks/config.toml, you can override the default settings, keybindings and colorscheme.

In particular, you can set a default vault path.

Feel free to submit issues or pull requests. Contributions are welcome!