hqTodo

If you love keyboard shortcuts and things like Org mode, you might like hqTodo to present your complete agile workflow from one easily editable Todo list in VS Code. Rather than drag cards around and click and open various windows, use Fabio Spampinato’s TODO+ extension to capture status, categories, and estimates as individual todo items in a text file, with keyboard shortcuts to prioritize and close issues. His extension is awesome, and with this li’l hqTodo web app, all that information is summarized in an easily consumable report for you (and your team if you want).

I have a complete picture of where I’m at, all from one launchpad, and with little mental effort because of the progressive disclosure model, from front page (active daily tasks) → optional task hyperlinks (to task details) → project pages (project-specific overview of tasks) → project details pages (how project tasks fulfill each project vision).

Table of Contents

• Features
• Running the app
  • Option 1: Using Docker Compose (recommended)
  • Option 2: Using NodeJS on your computer
• Maintaining your TODO file
  • Active todo items
  • Interruptions
  • Milestones
  • Referencing a GitHub repo
  • Archived todos
  • The taginfo section
  • A support section
• What’s next?

Features

• Open items and their estimates are used to display a Mermaid Gantt chart. Tasks shift with time, starting from now into the future, providing a quick glimpse of probable completion dates.

• 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 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)

1. 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.

2. 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.

3. 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).

4. Install Docker.

5. Ensure Docker is set to run on system startup. For example, on Ubuntu run:

   systemctl enable docker

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

   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:

docker compose restart

Option 2: Using NodeJS on your computer

Prereq: NodeJS v24 or higher.

1. Set things up.

   1. 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.

   2. Install server dependencies:

      npm install

   3. Install client dependencies and build it:

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

2. Thereafter, run the app with …​

   ./run

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

   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.

Maintaining your TODO file

For the most part, 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. 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:

☐ [@today|@high|@low] <todo description> [@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 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:

☐ @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:

☐ [Nd starting YYYY-MM-DD]: <title>

Example:

☐ [5d starting 2020-05-18]: Whiz-Bang-Boom conference

Milestones

Milestones have the same form as an interrupt, but with a length of zero days (0d).

Example:

☐ [0d starting 2020-06-15]: Complete Project A @proja

Milestones show up in their own section above the others.

Referencing a GitHub repo

If you reference a particular issue in your todo text (for example if you use the linkme VS Code extension), the Gantt chart will link to the issue from the task bar and todo text.

Edit the config file repo URL to point to your own repo. As set up now, it has two patterns:

• one pattern that links to the default repo that you specify in the config file ghihq•4

• one pattern that links to whatever repo you specify in the todo file itself ghi•ragnoroct/linkme•9

You can of course change the patterns to link to whatever you want.

Archived todos

If you archive your done items (e.g. Cmd+Shift+A]), they will be available at the bottom along with a graph of the cumulative story points you’ve knocked out over time. Marvel at your progress!

💡	Use category tags in your todo items to see them grouped and totaled by category.

The taginfo section

Use this section if you want to provide a more descriptive title and link to more information on the project.

The structure of each entry:

☐ @tagname full title of the project or category - url or linkme link

Example:

☐ @prja Project A - den•bRNzBMOVaqYl6i7C.html

I personally link to pages published with Dendron, because I like to also use VS Code for my note taking, and Dendron has a cool feature where you can publish Notes to a web site.

A support section

Like interrupts, support questions disrupt your velocity, so you might want to keep track of them as well. To do so, Add a Support: project with todo items. For these items, use the TODO+ extension’s time tracking feature:

• Super+S to start the timer

• Super+D to stop the timer and mark the item done

When you archive your todos, the support items will have the following form, and the time you spent on them is graphed with a yellow line in the UI.

  ✔ ticket324: Help debug website3 @started(2023-08-20 15:46) @done(2023-08-20 16:46) @lasted(1h) @project(Support)
  ✔ ticket323: Help debug website2 @started(2023-08-20 13:56) @done(2023-08-20 14:56) @lasted(1h) @project(Support)
  ✔ ticket322: Help debug website1 @started(2023-08-19 10:56) @done(2023-08-19 11:26) @lasted(30m) @project(Support)

Items of that form are exposed with following endpoints as well:

• /todos/supportdata

• /todos/supportondate/YYYY-MM-DD

What’s next?

See the @hq project in the Classic-styled hqTodo file.