Frogtab — Private, peaceful task management

Frogtab is a lightweight task manager that helps you stay focused on today's priorities.

In this README:

• Technical overview of Frogtab
• How your personal link works
• Customizing the placeholder text of your personal link
• Sending tasks via JavaScript
• Self-hosting Frogtab
• Acknowledgments
• License
• Changelog

From my dev blog:

• Running the Frogtab task manager on Ubuntu
• Making a command-line tool for your Frogtab personal link

Technical overview of Frogtab

Frogtab runs in your browser and stores your data in localStorage. You can export your data at any time. If your browser supports showSaveFilePicker(), you can also enable automatic backups.

You can use Frogtab offline by running Frogtab Local on your computer. Frogtab Local also enables automatic backups in any browser. If you use Linux, you can install Frogtab Local from the Snap Store. Otherwise, you can download and run the latest release.

Frogtab can't sync your data between devices. However, if you register your main device, the frogtab.com server creates a personal link that you can use to send tasks to your main device.

How your personal link works

1. When you register your device, Frogtab generates a PGP key pair in your browser. Your device then sends the public key to the server. The private key never leaves your device.

   See register() in help.html.

2. The server generates a user ID and an API key for your device:

   • User ID - The public "address" of your device
   • API key - A non-public "password" for your device

   See post-create-user.php.

   Your personal link is https://frogtab.com/send#{id}, where {id} is the user ID.

3. When you use your personal link to send a task, Frogtab first encrypts the task using the public key from step 1. Frogtab then sends the encrypted task to the server.

   See encryptAndSend() in send.html.

4. The server queues the encrypted task.

   See post-add-message.php.

5. Your device periodically checks for encrypted tasks.

   The server requires the API key from step 2. This ensures that other devices cannot check for encrypted tasks. If there are encrypted tasks in the queue, your device downloads the encrypted tasks.

   The server clears the queue as soon as your device has downloaded the encrypted tasks.

   See post-remove-messages.php.

6. Your device decrypts the tasks using the private key from step 1.

   See verifyUserAndAppendMessages() in main.js.

Customizing the placeholder text of your personal link

By default, the placeholder text of your personal link is "Send to your inbox…". You can override the default placeholder text to help you identify the device that you're sending tasks to.

To override the default placeholder text, add /{text} to the end of your personal link, where {text} is your preferred placeholder text. Make sure that any special characters in the placeholder text are correctly percent-encoded in your personal link. For example, to use "Send to Linux desktop…" as the placeholder text, add /Send%20to%20Linux%20desktop%E2%80%A6 to the end of your personal link.

To override the default placeholder text and automatically use the correct encoding, open your personal link in your browser, then enter setPlaceholder("Custom placeholder text") in the web console.

Sending tasks via JavaScript

After registering your device, you can use the JavaScript SDK to send tasks to your device:

let encryptAndSend = null;

async function send(task) {
  try {
    if (!encryptAndSend) {
      const frogtab = await import("https://frogtab.com/open/sdk.js");
      encryptAndSend = await frogtab.connectToInbox("YOUR_ID");
    }
    return await encryptAndSend(task);
  }
  catch (err) {
    return false;
  }
}

send("Record a demo of the latest product features").then(success => {
  console.log(success);
});

Replace YOUR_ID by the ID from your personal link.

For a detailed example, see Adding a private feedback box to Bear.

Self-hosting Frogtab

You'll need an Apache server that has PHP and Composer installed. Apache must have the following modules enabled:

• mod_mime
• mod_rewrite
• mod_headers

To install Frogtab on your own server:

1. Open a shell on your server, then navigate to a directory that is accessible to PHP scripts but not accessible via the web.

2. Enter the following commands:

   git clone https://github.com/dwilding/frogtab.git
   cd frogtab
   ./dev_build_server.sh
   

3. Copy the contents of frogtab/server/public to a directory that is accessible via the web. Make sure that the .htaccess files in frogtab/server/public and frogtab/server/public/open are copied.

Frogtab is ready!

To use Frogtab, open your browser, then navigate to the web-accessible directory from step 3.

The first time you register a device, Frogtab creates a SQLite database called frogtab.db in the directory from step 1. This database stores device credentials and the queue of encrypted tasks.

Acknowledgments

• Simple.css
• OpenPGP.js
• ramsey/uuid
• iconnoir
• mackwhyte

License

Frogtab is licensed under the MIT License. For details, see LICENSE.

Frogtab uses OpenPGP.js for PGP encryption. The source code of OpenPGP.js is available at https://github.com/openpgpjs/openpgpjs. OpenPGP.js is licensed under the GNU Lesser General Public License. For details, see LICENSE_openpgp.

Changelog

Date	Change	Available in Server	Frogtab Local Version
Nov 2, 2024	Sending tasks via a terminal now fails if the label has never been used by Frogtab	No	v1.08
Oct 27, 2024	You can now send tasks to Frogtab via a terminal, without registering for a personal link. See the help page	No	v1.07
Oct 18, 2024	You can now stop Frogtab Local via your browser. See the bottom of the help page	No	v1.06
Oct 18, 2024	Reorganized the menu to always show Achievements. Removed Send to Frogtab from the menu	Yes	v1.06
Oct 18, 2024	Reorganized the help page and explained Achievements in a more approachable way	Yes	v1.06
Oct 18, 2024	Improved keyboard accessibility	Yes	v1.06
Oct 18, 2024	Changed the ID format of generated key pairs, for better compatibility with GnuPG	Yes	v1.06
Oct 18, 2024	Improved portability by specifying the content type for .mjs files	Yes	Not applicable
Sep 25, 2024	You can now download public keys from the server. See code_samples.md	Yes	Not applicable
Jul 30, 2024	Fixed a registration bug that occurred after reinstalling Frogtab on the server	Yes	Not applicable
Jul 26, 2024	Added a variable in config.py that specifies the server to use for personal links	No	v1.05
Jul 26, 2024	Fixed a registration bug that occurred after importing an old backup file	Yes	v1.05
Jul 16, 2024	Changed the Flask app to run via Python instead of the flask command. The port is now specified in config.py	No	v1.04
Jul 16, 2024	Changed the name of the built-in backup method to show the backup directory instead of the filename	No	v1.04
Jul 16, 2024	Identified the registration server in "Registering for a personal link" on the help page	Yes	v1.04
Jul 16, 2024	Removed the data-vibe attribute and documented how to customize the placeholder text of your personal link	Yes	v1.04
Jul 4, 2024	Improved support & docs for self-hosted servers	Yes	v1.03
Jul 2, 2024	Fixed a bug with the registration button	Yes	v1.02