Org-NewTab

Supercharge your browser's New Tab with Org-Agenda

🗃️ Org-NewTab is a browser extension which sets the org-agenda task you should be working on as your new tab page.

org-newtab-intro.mp4

Current Status: Initial release, ready for wider use, bug reports welcome!

🚀 Getting Started

Installation:

1. Install package from MELPA

Using `package.el`

You can install org-newtab from MELPA or MELPA Stable using package.el:

M-x package-install RET org-newtab RET

Using `straight.el`

Installation from MELPA or MELPA Stable using straight.el:

(straight-use-package 'org-newtab)

Or with use-package:

(use-package org-newtab
  :straight t
  ...)

If you need to install the package directly from the source repository, instead of from MELPA, the next sample shows how to do so:

(use-package org-newtab
  :straight (:host github :repo "Zweihander-Main/org-newtab"
             :files (:defaults))
  ...)

If you plan to use your own local fork for the development and contribution, the next sample will get you there:

(use-package org-newtab
  :straight (:local-repo "/path/to/org-newtab-fork"
             :files (:defaults)
             :build (:not compile))
  ...)

Using Doom Emacs

(package! org-newtab)

With the next sample you can install the package directly from the source repository:

(package! org-newtab
  :recipe (:host github :repo "Zweihander-Main/org-newtab"
           :files (:defaults)))

And if you plan to use your own local fork for the development or contribution, the next sample will get you there:

(package! org-newtab
  :recipe (:local-repo "/path/to/org-newtab-fork"
           :files (:defaults)
           :build (:not compile)))

Without a package manager

You will need to ensure that you have all the required dependencies. These include:

• websocket
• async

After installing the package, you will need to properly setup load-path to the package:

(add-to-list 'load-path "/path/to/org-newtab/lisp/")

After which you should be able to resolve (require 'org-newtab) call without any problems.

2. Install Chrome or Firefox extension
3. M-x org-newtab-mode

Usage:

To control what shows up when a task isn't clocked in, hit the menu button in the top left and change the Match Query under the Behavior tab. Instructions for creating match queries can be found here.

The background color of the item that shows up is controlled by the org-tag-faces variable and which tags apply to the item. When multiple colors apply to an item, they will all show up in a gradient.

🖥️ Dev Notes

Technologies used:

• Emacs side:
  • Eldev for project management
  • Buttercup for testing
  • websocket and async libs
• Extension side:
  • Plasmo Browser Extension framework
  • React + Redux Toolkit
  • TypeScript
  • Playwright for E2E integration testing
  • Jest+Runners, Husky+Lint-staged
  • pnpm, eslint, prettier, stylelint

Possible Future Additions

• Browser storage
• Persistent default match query
• Layout editor
• Display clock status in browser
• Hooks on Emacs actions (TODO change, clock change, ect.)
• Firefox compatibility
• Clock in and out from browser
• Mark items as done from browser
• Smart caching for match query lookups
• Sortable layout elements
• Allow moving layout elements left/right
• Display schedule/deadline info
• Display priority
• Match query builder
• Multiple match queries
• Render heading links
• Open heading links
• Vim keybindings
• Age countdown
• Icons for connection status
• Deeper agenda integration
• Multiple themes
• Built-out documentation (separate site)
• Provide sorting beyond what match query provides
• In-app tutorial/getting started

Development setup:

1. Add the lisp files into your Emacs as outlined above.
2. Clone this repo and run pnpm run build for Chrome, pnpm run build --target=firefox-mv3 for Firefox.
3. In Chrome, head to chrome://extensions/, enable Developer Mode, and Load unpacked the ./build/chrome-mv3-prod directory. In Firefox, head to about:debugging#/runtime/this-firefox and Load Temporary Add-on the ./build/firefox-mv3-prod directory. Note that you'll have to do this every time you restart Firefox.
4. M-x org-newtab-mode

Note that you can get hot reloading in Chrome using pnpm run dev and using the ./build/chrome-mv3-dev directory. The same (pnpm run dev --target=firefox-mv3) won't work in Firefox due to security limitations.

Misc

• chrome.storage.local.get(console.log) to get extension storage
• Development is done against Chrome -- there is some flaky behavior when using pnpm run dev --target=firefox-mv3 though a production build is manually checked against for every major release
• E2E testing is done against ./build/chrome-mv3-dev locally and ./build/chrome-mv3-prod in CI via pnpm run test:e2e.
• Designed around the limitations of Manifest V3; pnpm run build --target=firefox-mv2 is not supported and has flaky behavior around the storage and messaging APIs.

💼 Available for Hire

I'm available for freelance, contracts, and consulting both remotely and in the Hudson Valley, NY (USA) area. Some more about me and what I can do for you.

Feel free to drop me a message at:

hi [a+] zweisolutions {●} com

⚖️ License

AGPLv3

org-newtab
Copyright (C) 2023-2024 Zweihänder

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published
by the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.