WorkflowyExt

WorkflowyExt is a lightweight, pluggable background worker for Workflowy. It connects to the Workflowy API and runs automation plugins on your tree.

Included plugin: Time Tracker

• Tracks time on individual items
• Aggregates time to parent items

How it works

1. Tag items you want to track (for example, using a pattern like T<...> #on).
2. Start a timer by adding a “started” tag (for example, #focus).
3. The worker polls Workflowy, calculates elapsed time, and updates the tagged item and its parents.

Prerequisites

• Docker Desktop installed and running
• A Workflowy API token

Quick start: run the published image

1. Open a command prompt.
2. Replace the placeholders below with your configuration variables (see Configuration below) and run:

docker run --name workflowy-ext -d ^
    -e WORKFLOWY_API_TOKEN="YOUR_WORKFLOWY_API_TOKEN" ^
    -e TRACKABLE_NODE_ID="YOUR_TRACKABLE_NODE_ID" ^
    -e MEMORY_NODE_ID="YOUR_MEMORY_NODE_ID" ^
    -e TRACKABLE_NODE_REGEX="T(?<TIMER>[^ ]*) #on" ^
    -e STARTED_TIMER_NODE_REGEX="#focus" ^
    -e REFRESH_INTERVAL_SECONDS=15 ^
    minmode/workflowy-ext:1.0.0

3. Use Docker Desktop (or docker logs) to verify the container is healthy.
4. Confirm timers are updating in your Workflowy document.

Alternative: run via build_and_run.bat

1. Download this repository.
2. Open a command prompt and navigate to the repository folder.
3. Open build_and_run.bat and set the configuration variables (see Configuration below).
4. Run build_and_run.bat.
5. Check Docker Desktop for logs/errors.
6. Verify timers in Workflowy.

Configuration

• WORKFLOWY_API_TOKEN (required)

  • Your Workflowy API token for authentication.
  • Example: WORKFLOWY_API_TOKEN="abcdef1234567890"

• TRACKABLE_NODE_ID (required)

  • The ID of the Workflowy node whose subtree contains items to track.
  • Example: TRACKABLE_NODE_ID="5b8c576e-5cb3-8a05-f53f-5c9ec0f1c387"

• MEMORY_NODE_ID (required)

  • The ID of a node where the plugin can store timing/memory data.
  • Example: MEMORY_NODE_ID="5ff5e676-4212-19cc-fcd3-79d025069fc8"

• TRACKABLE_NODE_REGEX (required)

  • A regular expression used to identify items to track within the subtree. It MUST contain a named capturing group TIMER.
  • Example: T(?<TIMER>[^ ]*) #on
  • Notes:
    • The named group TIMER is validated at startup; without it the app will fail.
    • Use https://regex101.com/ to validate your regex.

• STARTED_TIMER_NODE_REGEX (required)

  • A regular expression that identifies the currently active/started item.
  • Example: #focus
  • Notes:
    • Use https://regex101.com/ to validate your regex.

• REFRESH_INTERVAL_SECONDS (required)

  • How often the worker polls and updates, in seconds.
  • Example: REFRESH_INTERVAL_SECONDS=15
  • Notes:
    • Workflowy API has rate limits. The more nodes you have, the longer updates may take. When you hit a limit, updates pause until the limit resets.

Step-by-step example setup

For demo purposes:

• TRACKABLE_NODE_REGEX: T(?<TIMER>[^ ]*) #on
• STARTED_TIMER_NODE_REGEX: #focus

1. Create a Workflowy document similar to the example:

2. Find TRACKABLE_NODE_ID - Tasks node:

3. Find MEMORY_NODE_ID - node under Memory node:

4. Run the container with found values:

docker run --name workflowy-ext -d ^
    -e WORKFLOWY_API_TOKEN="..." ^
    -e TRACKABLE_NODE_ID="073e0f78-3b8c-eb6b-c2a3-17890a3a5a6c" ^
    -e MEMORY_NODE_ID="0bab1993-ee7e-0637-8a49-22bbedc55a96" ^
    -e TRACKABLE_NODE_REGEX="T(?<TIMER>[^ ]*) #on" ^
    -e STARTED_TIMER_NODE_REGEX="#focus" ^
    -e REFRESH_INTERVAL_SECONDS=15 ^
    minmode/workflowy-ext:1.0.0

5. Watch Docker logs and confirm timers update in Workflowy:

License

This project is licensed under the PolyForm Noncommercial License 1.0.0.
You may use, modify, and share the code for noncommercial purposes only.
Commercial use requires a separate license from the author.

See the LICENSE file for the full text.

Contributing

See CONTRIBUTING.md for how to propose changes.

Tips / Support

If WorkflowyExt saves you time or you enjoy using it, here are a few great ways to support the project:

• Star the repository to help others discover it.
• Report bugs or request features via GitHub Issues.
• Open a PR if you spot an improvement—docs tweaks are welcome too.
• Watch releases to get updates.
• Tell a friend or share on social.

Want to leave a tip? Thank you!

• https://coindrop.to/workflowy-ext