Mozeidon-Z

Mozeidon-Z is a macOS-focused hard fork of egovelox/mozeidon. It began as a fork but now diverges substantially and is maintained as its own project — see What's different in Mozeidon-Z.

What's different in Mozeidon-Z

tabs activate - Activate a tab AND bring its Firefox window to the foreground, even across macOS Spaces
tabs pick - Interactive TUI tab picker using bubbletea
AppleScript integration - Proper window activation on macOS that works with multiple windows/Spaces
just recipes - Simplified setup and development workflow (just setup-all, just package-firefox, etc.)

Firefox Extension

Install the Mozeidon-Z extension from AMO:

https://addons.mozilla.org/en-US/firefox/addon/mozeidon-z/

TLDR

Handle your tabs, groups, bookmarks and history from outside of your web-browser.
🤓 Installation guide
📖 CLI Reference Documentation
✨ Desktop applications

Intro

Mozeidon-Z is a CLI written in Go to handle Mozilla Firefox tabs, history, and bookmarks — plus a Raycast front-end for macOS.

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 fzf and fzf-tmux)
A Raycast extension built around Mozeidon CLI (for macOS only)

All the code is available here as open-source. You can be sure that:

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 addon extension will stop or remove all related processes on your machine.

Using the mozeidon CLI (see CLI reference), you can:

List all currently opened tabs
List recently-closed tabs
List, delete current history
List current bookmarks
Activate a tab and bring its window to foreground (new in this fork)
Pick a tab interactively with TUI (new in this fork)
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
Create, delete, update a bookmark


Example output showing tabs with `jq` formatting


Example output showing tabs with `--go-template` formatting


Example output showing tabs within custom `fzf-tmux` script

Architecture

Mozeidon is built on IPC and native-messaging protocols, using the following components:

Mozeidon-Z Firefox Extension - A TypeScript WebExtension running in Firefox that receives commands and sends back data (tabs, bookmarks, etc.) by leveraging browser APIs.
Mozeidon native-app - A Go program that acts as an IPC broker. It communicates with the browser extension via native-messaging protocol.
Mozeidon CLI - A Go CLI that communicates with the native-app via IPC protocol. This is what you use from the terminal.

Installation

You need to install 3 components:

Mozeidon-Z Firefox Extension - Install from AMO
Mozeidon native-app - Install via Homebrew
Mozeidon CLI - Install via Homebrew or build from source

Note: the extension, CLI, and native-app version independently (they're separate pieces with their own release cadences) — just install the latest of each. Their version numbers won't always match, and that's expected; the protocol between them is stable.

Quick Start (macOS)

# 1. Install the Mozeidon-Z CLI (Homebrew tap; also pulls the mozeidon-z-messaging bridge)
brew install colangelo/tap/mozeidon-z

# 2. Register native messaging (see "Configure Native Messaging" below) — e.g. clone the
#    repo and run `just setup-native-messaging`, or write the manifest manually.

# 3. Install the Mozeidon-Z extension from AMO, restart Firefox, then test
mozeidon-z tabs get

Prefer building from source? git clone https://github.com/colangelo/mozeidon-z.git && cd mozeidon-z && just install-cli (→ ~/.local/bin/mozeidon-z), plus brew install colangelo/tap/mozeidon-z-messaging for the bridge.

Mozeidon-Z Firefox Extension

The Mozeidon-Z addon for Mozilla Firefox can be found on AMO:

https://addons.mozilla.org/en-US/firefox/addon/mozeidon-z/

Installs auto-update once a new version is approved on AMO (publish with just submit-firefox).

Mozeidon native-app

The mozeidon native-app — packaged as mozeidon-z-messaging (a hard fork of egovelox/mozeidon-native-app) — is an IPC broker that connects the CLI to the browser extension.

Install via Homebrew (macOS/Linux):

brew install colangelo/tap/mozeidon-z-messaging

It's also pulled automatically as a dependency of brew install colangelo/tap/mozeidon-z. Or download from the release page, or build from source.

Configure Native Messaging (Required)

The native-app must be registered with Firefox.

Option 1: Use just (recommended)

just setup-native-messaging

Option 2: Manual setup

Create ~/Library/Application Support/Mozilla/NativeMessagingHosts/mozeidon_z.json (the host name uses an underscore — native-messaging host names can't contain hyphens):

{
  "name": "mozeidon_z",
  "description": "Mozeidon-Z native messaging host",
  "path": "/opt/homebrew/bin/mozeidon-z-messaging",
  "type": "stdio",
  "allowed_extensions": [
    "mozeidon-z@a-layer.io"
  ]
}

Important: Restart Firefox after creating this file.

For other OS, see the Mozilla documentation for the correct NativeMessagingHosts location.

Mozeidon CLI

The Mozeidon CLI is a lightweight CLI written in Go.

📖 Complete CLI Reference Documentation

New Commands in This Fork

# Activate a tab AND bring its window to foreground (works across macOS Spaces)
mozeidon tabs activate 3289:596

# Interactive TUI tab picker
mozeidon tabs pick

Install (Homebrew) or build from source

# Homebrew tap (recommended) — also installs the mozeidon-z-messaging bridge
brew install colangelo/tap/mozeidon-z

# …or build from this repo:
git clone https://github.com/colangelo/mozeidon-z.git
cd mozeidon-z && just install-cli      # builds cli/ → ~/.local/bin/mozeidon-z

Or build in place: cd cli && go build -o mozeidon-z (→ cli/mozeidon-z).

Examples

📖 Complete CLI Reference Documentation

How to use the Mozeidon CLI with `go-template` syntax for customized output :

# get maximum 10 of latest bookmarks, title and url

mozeidon bookmarks -m 10 --go-template '{{range .Items}}{{.Title}} {{.Url}}{{"\n"}}{{end}}'

# get opened tabs, with 📌 icon if pinned

mozeidon tabs get --go-template '{{range .Items}}{{.WindowId}}:{{.Id}} {{.Url}} {{if .Pinned}}📌{{else}}🦊{{end}} {{"\\u001b[38;5;109m"}} {{.Domain}}{{"\\033[0m"}} {{.Title}}{{"\n"}}{{end}}'

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.

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'

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

# in $HOME/.tmux.conf
bind t run-shell -b "bash $HOME/.tmux/mozeidon_tabs.sh"

Now create the script $HOME/.tmux/mozeidon_tabs.sh :

#!/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'

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

#!/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'

Desktop applications based on mozeidon CLI

Swell

Swell 🏄 🌊 is very fast and has plenty of features
( custom shortcuts, chromium or mozilla compatibility, tabs, groups, bookmarks, history ).

Raycast extension

macOS + Firefox only. The Mozeidon-Z Raycast extension lives in raycast/ and is the primary front-end. Install it in dev mode:

just raycast-dev        # or: cd raycast && npm run dev

First complete the component installation above (extension + native-app + CLI). The Raycast extension lists tabs, recently-closed tabs, and bookmarks (not history items).

Releases

CLI releases are on the releases page, managed with GitHub Actions + goreleaser. A release auto-publishes when a version tag is pushed:

git tag -a v5.0.0 -m "Mozeidon-Z 5.0.0"
git push origin v5.0.0

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.

Quick setup with just

If you have just installed, you can set up everything in one command:

just setup-all

This will build the CLI, extensions, Raycast extension, and configure native messaging.

Other useful just commands:

just --list - Show all available commands
just setup-native-messaging - Configure Firefox native messaging
just check-native-messaging - Verify native messaging is configured
just package-firefox - Package extension for AMO upload
just tabs-get - Test getting open tabs

Manual setup

Build the cli and the extensions locally :

just build-all

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 :

./cli/mozeidon tabs get

Notes and well-known limitations

`mozeidon` cannot 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 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 🙏.

This is currently not planned for resolution. Technically, to overcome this limitation, we would need a particular native-messaging-host (mozeidon-native-app) for each web-browser.
The installation would surely be too complex for most users. (see architecture),

For a given web-browser, `mozeidon` cannot work correctly if you use 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.

See egovelox/mozeidon#6

`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/'

Name		Name	Last commit message	Last commit date
.claude		.claude
.codex/skills		.codex/skills
.github/workflows		.github/workflows
chrome-addon		chrome-addon
cli		cli
docs/superpowers		docs/superpowers
firefox-addon		firefox-addon
openspec		openspec
raycast		raycast
.gitignore		.gitignore
.woodpecker.yml		.woodpecker.yml
ACTIVATE_TAB_IMPLEMENTATION.md		ACTIVATE_TAB_IMPLEMENTATION.md
AGENTS.md		AGENTS.md
CI_RELEASE_RUNBOOK.md		CI_RELEASE_RUNBOOK.md
CLAUDE.md		CLAUDE.md
CLI_REFERENCE.md		CLI_REFERENCE.md
README.md		README.md
WORKSTATION_SETUP.md		WORKSTATION_SETUP.md
justfile		justfile

Latest commit

History

Folders and files

Repository files navigation

Mozeidon-Z

What's different in Mozeidon-Z

Firefox Extension

TLDR

Intro

Architecture

Installation

Quick Start (macOS)

Mozeidon-Z Firefox Extension

Mozeidon native-app

Configure Native Messaging (Required)

Mozeidon CLI

New Commands in This Fork

Install (Homebrew) or build from source

Examples

How to use the Mozeidon CLI with go-template syntax for customized output :

Customized tabs output with a pipe into fzf

Same as previous, but tailored for tmux

Another advanced fzf-tmux script

Desktop applications based on mozeidon CLI

Swell

Raycast extension

Releases

Local development setup

Quick setup with just

Manual setup

Notes and well-known limitations

mozeidon cannot work simultaneously in different web-browsers

For a given web-browser, mozeidon cannot work correctly if you use multiple browser windows.

mozeidon bookmark update --folder-path and browsers' default bookmark folder.

TLDR

Details

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

How to use the Mozeidon CLI with `go-template` syntax for customized output :

Customized tabs output with a pipe into `fzf`

`mozeidon` cannot work simultaneously in different web-browsers

For a given web-browser, `mozeidon` cannot work correctly if you use multiple browser windows.

`mozeidon bookmark update --folder-path` and browsers' default bookmark folder.