Mozeidon is a CLI to handle Firefox or Chrome tabs, history and bookmarks.
🔱 Mozeidon
TLDR;
- Handle your tabs, groups, bookmarks and history from outside of your web-browsers.
- 🤓 Install of the mozeidon cli
- 📖 CLI Reference Documentation
- ✨ Desktop applications based on mozeidon CLI
Intro
Mozeidon is essentially a CLI written in Go to handle Mozilla Firefox OR Google Chrome tabs, history, and bookmarks. Other web-browsers are also supported if derived from Firefox ( e.g Firefox Developer Edition, Zen ) or from Chromium ( e.g Edge, Arc ).Here you'll find :
- a guide to complete the installation of the mozeidon components (see architecture).
- advanced examples of the CLI usage (including integration with
fzfandfzf-tmux) - Swell UI (linux or macOS) built around Mozeidon CLI
- your browsing data (tabs, bookmarks, etc) will remain private and safe: mozeidon will never share anything outside of your system.
- at any time, stopping or removing the mozeidon firefox (or chrome) addon extension will stop or remove all related processes on your machine.
mozeidon CLI (see CLI reference), you can : - list all currently opened tabs
- list recently-closed tabs
- switch to a currently opened tab
- open a new tab (empty tab or with target url)
- close a currently opened tab
- pin/unpin a currently opened tab
- group/ungroup a currently opened tab
- bookmark a tab
- list current bookmarks
- create, delete, update a bookmark
- list current history
- delete a history item
- do all these actions above, choosing a specific browser or profile ( see profiles in the CLI Reference, since version 4.0.0 )
| <img width="1512" height="910" alt="mozeidon-cli" src="https://github.com/user-attachments/assets/32b49616-5129-479c-aea6-9490395464c9" /> | |:--:| | Example output showing tabs with jq formatting |
<br/>
| <img width="1512" height="910" alt="mozeidon-cli" src="https://github.com/user-attachments/assets/a3757c8b-652a-4a59-b0b7-5f7dc06a79a6" /> | |:--:| | Example output showing tabs with
--go-template formatting |
<br/>
| <img width="1512" alt="mozeidon-cli-2" src="https://github.com/egovelox/mozeidon/assets/56078155/9ba5c99b-0436-433c-9b73-427f2b3c897f"> | |:--:| | Example output showing tabs within custom
fzf-tmux script |
<br/>
Architecture
<img width="788" alt="mozeidon-architecture" src="https://github.com/egovelox/mozeidon/assets/56078155/15192276-e85f-4de0-956d-6eba0517303b"> <br/><br/>
Mozeidon is built on ipc and native-messaging protocols, using the following components :
- the Mozeidon firefox or chrome add-on, a JS script running in the Mozilla (or Chrome) browser, receives commands and sends back data (i.e tabs, bookmarks, etc) by leveraging various browser APIs.
- the Mozeidon native-app, a Go program, interacts with the Mozeidon firefox-addon. It sends commands to, and receive data from the browser addon - via native-messaging protocol.
- the Mozeidon CLI, another Go program, interacts with the Mozeidon native-app. It sends commands to and receive data from the native-app - via ipc protocol.
CLI Installation
You need to install at least 3 components :
- the Mozeidon firefox add-on or the Mozeidon chrome add-on
- the Mozeidon native-app
- the Mozeidon CLI
Alternatively, you can download our Swell UI, which bundles the last two components : then just install the browser add-on, and you will be able to use the bundled CLI.
📌 Important note : Please ensure you are using the same
major version (e.g 4.x.y) for the add-on and for the other components ( native-app and CLI ).
Mozeidon firefox-addon
The mozeidon addon for Mozilla Firefox can be found here :
https://addons.mozilla.org/en-US/firefox/addon/mozeidon
Latest version :
4.1 ( compatible with CLI >= 4.0.0 )
Mozeidon chrome-addon
The mozeidon addon for Google Chrome can be found here :
https://chromewebstore.google.com/detail/mozeidon/lipjcjopdojfmfjmnponpjkkccbjoipe
Latest version :
4.1 ( compatible with CLI >= 4.0.0 )
Mozeidon native-app
The mozeidon native-app, a very simple ipc server written in
go, will allow the mozeidon add-on to receive commands from and send responses to the mozeidon CLI (see below).
On MacOS or Linux, you can install it using
homebrew : <pre><code class="lang-bash">brew tap egovelox/homebrew-mozeidon ;
brew install egovelox/mozeidon/mozeidon-native-app ;</code></pre>
Otherwise, you may download the binary from the release page.
If no release matches your platform, you can build the binary yourself: <pre><code class="lang-bash">git clone https://github.com/egovelox/mozeidon-native-app.git ;
cd mozeidon-native-app && go build</code></pre> <br/> As a firefox native-app, it has to be referenced into your Firefox or Chrome configuration.
Referencing the native-app into your Firefox configuration
On
MacOS, first locate the ~/Library/Application Support/Mozilla/NativeMessagingHosts directory (or create it if missing).
Then create a
mozeidon.json file, and copy into it the following json.
Note: depending on your installation, you may need to replace the value in
"path" with the absolute path of the mozeidon-native-app.
<pre><code class="lang-json">{ "name": "mozeidon", "description": "Native messaging add-on to interact with your browser", "path": "/opt/homebrew/bin/mozeidon-native-app", "type": "stdio", "allowed_extensions": [ "mozeidon-addon@egovelox.com" ] }</code></pre>
Now the Mozeidon firefox-addon will be able to interact with the Mozeidon native-app.
Note : For other OS than
MacOS, please check the Mozilla documentation to find the correct location of the Firefox NativeMessagingHosts directory.
As a last step, you need to install the Mozeidon CLI.
Referencing the native-app into your Chrome configuration
On
MacOS, first locate the ~/Library/Application Support/Google/Chrome/NativeMessagingHosts directory (or create it if missing).
Then create a
mozeidon.json file, and copy into it the following json.
Note: depending on your installation, you may need to replace the value in
"path" with the absolute path of the mozeidon-native-app.
<pre><code class="lang-json">{ "name": "mozeidon", "description": "Native messaging add-on to interact with your browser", "path": "/opt/homebrew/bin/mozeidon-native-app", "type": "stdio", "allowed_origins": ["chrome-extension://lipjcjopdojfmfjmnponpjkkccbjoipe/"] }</code></pre>
Now the Mozeidon chrome-addon will be able to interact with the Mozeidon native-app.
Note : For other OS than
MacOS, please check the Chrome documentation to find the correct location of the Chrome NativeMessagingHosts directory.
As a last step, you need to install the Mozeidon CLI.
Mozeidon CLI
The Mozeidon CLI is a lightweight CLI written in
go.
📖 Complete CLI Reference Documentation
On MacOS or Linux, you can install it using
homebrew : <pre><code class="lang-bash">brew tap egovelox/homebrew-mozeidon ;
brew install egovelox/mozeidon/mozeidon ;</code></pre>
Otherwise, you may download the binary from the release page.
If no release matches your platform, you can build the binary yourself: <pre><code class="lang-bash">git clone https://github.com/egovelox/mozeidon.git ;
cd mozeidon/cli && go build</code></pre>
Examples
📖 Complete CLI Reference Documentation
How to use the Mozeidon CLI with
go-template syntax for customized output :
<pre><code class="lang-bash"># get maximum 10 of latest bookmarks, title and url
mozeidon bookmarks -m 10 --go-template '{{range .Items}}{{.Title}} {{.Url}}{{"\n"}}{{end}}'</code></pre>
<pre><code class="lang-bash"># get opened tabs, with 📌 icon if pinned
mozeidon tabs get --go-template '{{range .Items}}{{.WindowId}}:{{.Id}} {{.Url}} {{if .Pinned}}📌{{else}}🦊{{end}} {{"\\u001b38;5;109m"}} {{.Domain}}{{"\\033[0m"}} {{.Title}}{{"\n"}}{{end}}'</code></pre>
Customized tabs output with a pipe into
fzf
If you've installed [fzf you can use it as a kind of UI for mozeidon CLI.
The below
bash command shows how fzf can be used to select a tab, and to open it in your browser.
<pre><code class="lang-bash">mozeidon tabs get --go-template '{{range .Items}}{{.WindowId}}:{{.Id}} {{.Url}} {{if .Pinned}}📌{{else}}🦊{{end}} {{"\u001b[38;5;109m"}} {{.Domain}}{{"\033[0m"}} {{.Title}}{{"\n"}}{{end}}' \ | fzf --ansi --with-nth 3.. --bind=enter:accept-non-empty \ | cut -d ' ' -f1 \ | xargs -n1 -I % sh -c 'mozeidon tabs switch % && open -a firefox'</code></pre>
note :
xargs -n1 prevents to run any command if no tab was chosen with fzf ( say, for example, that you exited fzf with ctrl-c )
note :
mozeidon tabs switch is used to switch to the tab you chose in fzf
Same as previous, but tailored for tmux
As an example, let's bind our mozeidon script with the tmux shortcut
Prefix-t
<pre><code class="lang-bash"># in $HOME/.tmux.conf bind t run-shell -b "bash $HOME/.tmux/mozeidon_tabs.sh"</code></pre>
Now create the script
$HOME/.tmux/mozeidon_tabs.sh :
<pre><code class="lang-bash">#!/bin/bash mozeidon tabs get --go-template \ '{{range .Items}}{{.WindowId}}:{{.Id}} {{.Url}} {{if .Pinned}}📌{{else}}🦊{{end}} {{"\u001b[38;5;109m"}} {{.Domain}}{{"\033[0m"}} {{.Title}}{{"\n"}}{{end}}' \ | fzf-tmux -p 60% -- \ --no-bold --layout=reverse --margin 0% --no-separator --no-info --black --color bg+:black,hl:reverse,hl+:reverse,gutter:black --ansi --with-nth 3.. --bind=enter:accept-non-empty \ | cut -d ' ' -f1 \ | xargs -n1 -I % sh -c '$HOME/bin/mozeidon tabs switch % && open -a firefox'</code></pre>
Another advanced fzf-tmux script
This more advanced script will allow to :
- open a new tab (empty or with search query)
- switch to a currently open tab
- close one or many tabs
<pre><code class="lang-bash">#!/bin/bash $HOME/bin/mozeidon tabs get --go-template \ '{{range .Items}}{{.WindowId}}:{{.Id}} {{.Url}} {{if .Pinned}}📌{{else}}🦊{{end}} {{"\u001b[38;5;109m"}} {{.Domain}}{{"\033[0m"}} {{.Title}}{{"\n"}}{{end}}'\ | fzf-tmux -p 60% -- \ --border-label=TABS \ --no-bold \ --layout=reverse \ --margin 0% \ --no-separator \ --no-info \ --black \ --color bg+:black,hl:reverse,hl+:reverse,gutter:black \ --with-nth 3.. \ --bind="enter:accept+execute($HOME/bin/mozeidon tabs switch {1} && open -a firefox)" \ --multi \ --marker=❌ \ --bind="ctrl-p:accept-non-empty+execute($HOME/bin/mozeidon tabs close {+1})" \ --bind="ctrl-o:print-query" \ --header-first \ --color=header:#5e6b6b \ '--header=close tab(s) [C-p] open new tab [C-o]'\ | grep -v "[🦊📌]" \ | xargs -r -I {} sh -c '$HOME/bin/mozeidon tabs new "{}" && open -a firefox'</code></pre>
Desktop applications based on mozeidon CLI
Swell
Swell 🏄 🌊 is very fast and has plenty of features ( custom shortcuts, chromium or mozilla compatibility, profile-switch, tabs, groups, bookmarks, history ).
<img width="1141" height="686" alt="swelltabspanel" src="https://github.com/user-attachments/assets/ccfc7aac-dc02-4dba-97dd-25ee29da3957" />
Raycast extension
For MacOS and Firefox users only : see the Mozeidon Raycast extension.
This Raycast extension will not work with Chrome browser. Better see Swell.
Note that you'll first need to complete the installation of Mozeidon components (Mozeidon firefox add-on, Mozeidon native-app and Mozeidon CLI).
Note that you cannot list history items with this Raycast extension : only tabs, recently-closed tabs, and bookmarks.
MacOS swift app-agent
Not maintained anymore.
Please now switch to Swell 🏄 🌊
Not maintained anymore.
If you ask for something faster than Raycast ( which I find quite slow to trigger the search list ), you might take a look at this macOS app mozeidon-macos-ui
🆕 Quick install of the mozeidon-macos-ui brew cask
<img width="640" alt="mozeidon-macos-ui" src="https://github.com/user-attachments/assets/8590a296-3a4d-4287-b362-83804893710e" />
Releases
Various releases of the Mozeidon CLI can be found on the releases page.
Releases are managed with github-actions and goreleaser.
A release will be auto-published when a new git tag is pushed, e.g :
<pre><code class="lang-bash">git clone https://github.com/egovelox/mozeidon.git && cd mozeidon;
git tag -a v2.0.0 -m "A new mozeidon (CLI) release"
git push origin v2.0.0</code></pre>
Local development setup
We'll assume that you installed and followed the steps described in the
Mozeidon native-app paragraph above. In fact, you rarely need to modify this component, it's just a message broker (see the architecture paragraph above ).
First clone this repository.
Then, build the cli and the extensions locally :
<pre><code class="lang-bash">make all</code></pre> Now, before loading the local extension in your browser, don't forget to disable any running instance of the
mozeidon extension.
Then, in Firefox ( or any web-browser ), via
Extensions > Debug Addons > Load Temporary Add-on, select the manifest file in firefox-addon/manifest.json. This will load the local extension.
From there, you may want to go further and build the CLI also :
You should now be able to execute the CLI using the local binary :
<pre><code class="lang-bash">./cli/mozeidon tabs get</code></pre>
Notes and well-known limitations
mozeidon bookmark update --folder-path and browsers' default bookmark folder.
TLDR
By design, the
mozeidon cli can only move bookmarks ( e.g changing their folder location ) to places located under the Bookmarks Bar tree.
For
mozeidon cli, there is no valid --folder-path for places located outside of the Bookmarks Bar tree.
The cli still allows
get, update, delete operations for those bookmarks located outside of the Bookmarks Bar tree, but as for moving them, it can only move them inside the Bookmarks Bar tree.
This is by design : the cli uses a
folder-path model, with the root, represented as /, being actually the Bookmarks Bar itself.
Details
Each browser has a default bookmark folder, e.g
Other Bookmarks in Firefox, Other Favorites in Edge, etc. But internally, in the browser, this default bookmark folder IS NOT LOCATED INSIDE THE Bookmarks Bar tree ( though this folder may be displayed by the browser in the Bookmarks Bar ).
This default bookmark folder contravenes
mozeidon design for bookmarks folder locations (--folder-path): In mozeidon, a --folder-path value: - is always a path starting from the root of the Bookmarks Bar tree ( aka Favorites Bar ) represented as
/ should always start with / should always end with /
E.g in
mozeidon :
--folderPath "//surf/" represents a surf folder, inside a "" (no title) folder, inside the Bookmarks Bar --folderPath "//Other Bookmarks/" represents a Other Bookmarks folder, inside a "" (no title) folder, inside the Bookmarks Bar ( and it should not be confused with Firefox's default bookmark folder )
Because internally, inside the browser, this default bookmark folder is not located in the Bookmarks Bar tree - though this folder may be displayed by the browser in the Bookmarks Bar, the
--folder-path flag on the mozeidon bookmark commands cannot reference such default bookmark folder, meaning that : - You can create a bookmark in the default bookmark folder with
mozeidon bookmark new by omitting the --folder-path flag. Such created bookmark will appear in the results of mozeidon bookmarks with a parent field of "parent":"//Other Bookmarks/" You cannot move such bookmark in a child folder ( i.e inside the default bookmark folder ) with e.g (let's say our bookmark-id is 42) mozeidon bookmark update 42 --folder-path '//Other Bookmarks/surf/' Instead, that command will move the bookmark in a surf folder, inside a Other Bookmarks folder, inside a "" (no title) folder, inside the Bookmarks Bar But still, you can move such bookmark in a folder located inside the Bookmarks Bar, with e.g mozeidon bookmark update 42 --folder-path '/surf/'
Before version 4.0.0,
mozeidon could not work simultaneously in different web-browsers
For users who installed both the firefox-addon AND the chrome-addon, or for those who use multiple browsers, each loading the mozeidon extension :
mozeidon CLI ( only before version 4.0.0 ) will not work properly when multiple instances of the mozeidon browser-extension are activated at the same time. To overcome this limitation, keep one extension activated (e.g firefox-addon) and deactivate the other extension (e.g chrome-addon).
If you notice any error during this operation, try to deactivate/reactivate the browser extension 🙏.
---
Before version 4.0.0, for a given web-browser,
mozeidon could not work correctly if you used multiple browser windows.
Mozeidon cannot guess in which browser window a given tab-id is located. Consequently, if you have 2 browser windows,
mozeidon tabs switch [tab-id] will switch to the last active browser window, where, possibly, the tab-id you targeted is not located.
This is by design,
mozeidon` was precisely meant to facilitate browsing within a unique browser window.
