Tomb

Personal todo list and task helper CLI tool

To (Todo) - M (Markdown) - B (Barrow)

Important

The first iteration of tomb is built by composing Unix tools like grep and sed. However, the next version will be properly developed using a statically-typed programming language, 🦀.

• Background
• Features
• Installation
• Usage
  • Special Keywords
    • Dates
    • Tasks
  • Commands
    • Open
    • Tasks
• Sketchybar Integration

Background

I've struggled to find a suitable tool that feels great to use for tracking my daily tasks. The most essential feature is the ability to edit tasks in a buffer with an editor I’m comfortable with (). Inspired by my coworker @ssiltanen, I decided to create my own!

Introducing tomb — a simple Markdown-based todo "barrow" to unearth your buried tasks and keep you accountable when new tasks need to be "laid to rest." You are the taskyard keeper!

Features

• Task management in a single markdown file
• Open todo file buffer directly to your editor
• Easily integrated with other tools (Like version control or sketchybar)

Installation

The easiest way to install tomb is with shm.

To install shm, run one of the following commands:

Using curl:

curl -sSL https://raw.githubusercontent.com/erikjuhani/shm/main/shm.sh | sh

Using wget:

wget -qO- https://raw.githubusercontent.com/erikjuhani/shm/main/shm.sh | sh

Then, run the following command to get the latest version of tomb:

shm get erikjuhani/tomb

Usage

tomb is designed to be used alongside other tools like tmux and sketchybar, though it can also be used on its own.

To set up a tmux popup for tomb, add the following to ~/.tmux.conf:

bind-key -n C-t run-shell "tmux popup -E 'tomb open || exit 0'"

This binds the tomb open command to C-t, opening the tomb Markdown file in a tmux popup using the neovim editor.

Special Keywords

tomb searches for specific patterns in the tomb tasks file. The file can also contain additional headings or notes.

Example .tomb.md file:

## Notes

- Remember to check the README for grammar errors!

## Tasks

### 03.11.2024

- [ ] Open task
- [.] Task in-progress
- [x] Completed task

To move tasks to other dates, edit the file directly and manually move tasks to a new date heading. For example, if a task is not completed, simply copy it to the next date heading:

### 04.11.2024

- [.] Task I started working on

### 03.11.2024

- [.] Task I started working on

Dates

Currently, all tasks need to be grouped under a specific date heading using this format: dd.mm.yyyy.

### 03.11.2024

- [ ] Task

Tasks

There are three task types, following GitHub Markdown syntax for tasks with one exception: "in-progress" tasks.

1. Open tasks use this pattern:

- [ ] Open task

2. In-progress tasks use a . (dot):

- [.] In-progress task

3. Completed tasks use an x:

- [x] Completed task

Commands

Open

tomb open [date] [-h|--help]

Opens the .tomb.md file in the editor. If a date argument is given, the file will open at the specified line if the date exists (works only in neovim and vim).

Change the default editor (nvim) to another by providing EDITOR=vim variable when calling the open command.

EDITOR=vim tomb open

Tasks

tomb tasks [date] [-c|--completed] [-o|--open] [-p|--progress] [--count] [-h|--help]

Lists tasks from the .tomb.md file based on the provided options. If no options are specified, it returns all tasks for the current date. The --count option returns a count of tasks, which can be used in combination with task type options like --completed.

Sketchybar Integration

To display the number of tasks in sketchybar, copy the plugin from sketchybar/plugins/tomb-items.sh using one of the following commands:

# Using curl
curl -sSL https://raw.githubusercontent.com/erikjuhani/tomb/main/sketchybar/plugins/tomb-plugin.sh -o "${HOME}/.config/sketchybar/plugins/tomb-plugin.sh" && chmod +x "${HOME}/.config/sketchybar/plugins/tomb-plugin.sh"

# Using wget
wget -q https://raw.githubusercontent.com/erikjuhani/tomb/main/sketchybar/plugins/tomb-plugin.sh -O "${HOME}/.config/sketchybar/plugins/tomb-plugin.sh" && chmod +x "${HOME}/.config/sketchybar/plugins/tomb-plugin.sh"

Then, add the following configuration to your sketchybarrc file:

sketchybar --add item tomb right \
           --set tomb update_freq=300 script="$PLUGIN_DIR/tomb-plugin.sh" \
           --add item tomb.completed right \
           --add item tomb.progress right \
           --add item tomb.open right

The update frequency is set to five minutes (300 seconds). To see updates more quickly when modifying the file, set the update frequency to a smaller value, like 1 second.

Finally, reload sketchybar:

sketchybar --reload

You should now see something similar on your bar: