hqtodo

= hqTodo :experimental: :toc: :toc-placement!: ifdef::env-github[] :tip-caption: :bulb: :note-caption: :information_source: :important-caption: :heavy_exclamation_mark: :caution-caption: :fire: :warning-caption: :warning: endif::[] ifndef::env-github[] :icons: font endif::[]

pass:[

If you enjoy working from the keyboard (keyboard shortcuts, vim, Emacs Org mode) you might like Fabio Spampinato's VS Code link:https://github.com/fabiospampinato/vscode-todo-plus[TODO+ extension] to capture todo items in a text file, with keyboard shortcuts to prioritize and close items. You can provide tags to each list item to indicate status, estimates, and categories. And because it's all in one central list, it's second nature to add items to it, ensuring you don't lose track of a thing. His extension is awesome!

But you can get lost staring at one long list. The list is a very fast and efficient way to enter and edit information. But to grok and act on the tasks, I needed something more.

That's why I created this li'l hqTodo web app. It further organizes the task information into manageable areas. It provides an easy visual for you (and your team if you want). The hqTodo app uses the provided tags to fit the information into an agile workflow. I've been using this method since about 2018 and much prefer it to dragging cards around.

pass:[

//// pass:[

The app provides a complete picture of where you're at, all from one launchpad. Using progressive disclosure, it provides you information in consumable chunks:

[verse]

From front page (ordered and categorized overview of all tasks) to project pages (focus on project-specific tasks) to project details pages (how project tasks fulfill each project vision)

From front page to optional task hyperlinks (to details elsewhere)

toc::[]

== Features

• Open items and their estimates are used to display a https://mermaid-js.github.io/mermaid/#/gantt[Mermaid] Gantt chart. Tasks shift with time, starting from now into the future, providing a quick glimpse of probable completion dates.
• https://apexcharts.com/[ApexCharts] is used to display cumulative story points you've knocked out to help keep track of your velocity.
• If you field support questions, you can also track those with the TODO+ extension and view the cumulative time spent in the chart.
• Completed items are displayed underneath. Great for weekly status reports.
• Tag your items to provide a detailed status page for each project.
• Because everyone else uses other forms of tracking, I use the link:https://marketplace.visualstudio.com/items?itemName=ragnoroct.linkme[Link Me extension] to include shortcuts to all those other resources in my Todo list. The hqTodo app exposes those links, too.

== Running the app

=== Option 1: Using Docker Compose (recommended)

. Create your own TODO file anywhere on the file system the app can access, a local folder or in a shared Cloud or Network mounted folder. . Copy the config/default.json file to a production.json file anywhere the app can access, or leave it in the config folder. Update the JSON file with your information. (For information on setting the Linkme links, watch the video.) Don't change the todoFile setting in the production.json file when running in a container because todo/TODO is the path as referenced from inside the container. . Copy compose.sample.yml to compose.yml, and in compose.yml, make the following changes:

• port::: Set the number before the colon to the port you want to use in the URL on your server. (Or leave the default of 3000.)

• volumes:::

• Set the path before the colon to the folder where your TODO file lives.
• Set the path before the colon to the folder where your production.json file lives (can be the same folder your TODO file is in). . link:https://docs.docker.com/engine/install/[Install Docker]. . Ensure Docker is set to run on system startup. For example, on Ubuntu run:

• [source, bash]

  systemctl enable docker

  . Run Docker Compose as follows to build the image and start a container in the background.

• [source, bash]

  docker compose up -d

• The restart: always setting in the compose file tells Docker to run the container on system startup.

As you change your TODO file, the app re-reads it every 40 seconds. But, if you change anything in the config file, you'll need to restart the container: [source, bash]

docker compose restart

=== Option 2: Using NodeJS on your computer

Prereq: NodeJS v24 or higher.

. Set things up. .. Copy the config/default.json file to config/production.json and add your info to the new file. Your own TODO file can be anywhere on the file system the app can access, such as a shared Cloud or Network mounted folder. .. Install server dependencies:

• [source, bash]

  npm install

  .. Install client dependencies and build it:

• [source, bash]

  cd client-react-carbon npm install npm run build cd ..

  . Thereafter, run the app with ...

• [source, bash]

  ./run

• ... and point your browser to http://localhost:3000.

• kbd:[Ctrl+C] stops the server.

One way to deploy the app in "production" is to run it on a server with pm2, systemctl, etc., and add your TODO file to a folder on the server that's synced with your local workstation with SyncThing or similar cloud folder sync application.

//// == Deploy

For example with systemd on Linux:

[source,bash]

vi misc/hqtodo.service # change the absolute paths and user sudo cp misc/hqtodo.service /etc/systemd/system/ sudo systemctl start hqtodo sudo journalctl -f # to verify. Also test in a browser sudo systemctl enable hqtodo

////

== Maintaining your TODO file

For the most part, link:https://marketplace.visualstudio.com/items?itemName=fabiospampinato.vscode-todo-plus#usage[update your TODO file] as you normally would as described in the TODO+ Readme documentation. There are a few conventions to use for the app to work. link:todo/TODO[See the sample TODO file] as an example.

Everything in your TODO file is ignored except ...

• the list in the optional Taginfo: section
• the todo items between the Todos: project and the next top-level project.
• the todo items after Archive:

... where a todo item is a line starting with ☐ or ✔.

=== Active todo items

Syntax:

[source,bash]

☐ [@today|@high|@low] [@Nh] [@custom ]*

• Priority tagging: Items prefixed with @today are placed in order in the In Progress section. Items with no priority label are listed in order in the Backlog section. Items prefixed with @high are colored red. Items prefixed with @low are not displayed. (This is your Icebox.)
• The optional @Nh tag indicates your estimated N hours. No tag gets the default of 2 hours.
• You can provide any number of @custom tags for your own custom filtering. They're displayed with the title.
• When you press kbd:[Super+D] to mark a task with a checkmark and a @done tag, it's listed in the "Recently closed todos" section of the web page.

Example:

[source,bash]

☐ @high Work with so-and-so on such-and-such @4h @prja @prjb

=== Interruptions

You can let folks know about vacations and other "interruptions" to your steady velocity. Specify the duration and start date as business days only.

Syntax:

[source,bash]

☐ [Nd starting YYYY-MM-DD]: