Extensions

Maho Browser supports desktop Chrome-compatible extensions using the Manifest V3 standard (loaded via unpacked directories or CRX files). Manifest V2 is deprecated and not supported. Mobile shells (iOS and Android) do not support extensions.

[!NOTE] Extension compatibility depends on standard Chromium extension APIs. Third-party ad-blocking extensions (such as uBlock Origin Lite) operate using Declarative Net Request (DNR) in Extension Mode. Content Blocking Mode in Settings controls Maho’s native engine independently of installed extensions.

Overview

On desktop, extensions can be loaded from unpacked local directories containing a valid Manifest V3 manifest.json or imported from local CRX files.

When Maho loads an extension, it validates the manifest and activates supported background service workers and content scripts.

Manifest V3 reference

Maho supports the following Manifest V3 fields.

Field	Required	Notes
manifest_version	Yes	Must be 3
name	Yes	String
version	Yes	String in semver format
description	No	String
icons	No	Icon map, commonly 16, 48, and 128
action	No	Browser toolbar button configuration
background	No	Service worker configuration
content_scripts	No	Script and style injection rules
permissions	No	Extension permissions
host_permissions	No	URL pattern permissions
web_accessible_resources	No	Resources exposed to pages
content_security_policy	No	Extension page CSP
options_page	No	Extension options page
options_ui	No	Options UI configuration
devtools_page	No	DevTools integration page

Required fields

manifest_version

Must be set to 3. Maho only supports Manifest V3 extensions.

name

The extension name. This field is required and must be a string.

version

The extension version in semver format. Maho expects a standard version string.

Optional fields

description

A short human-readable summary of the extension.

icons

Icon paths keyed by size. Common sizes include:

• 16
• 48
• 128

action

Defines the browser toolbar button. Supported properties include:

• default_popup
• default_icon
• default_title

background

Declares the background service worker. Maho supports:

• service_worker
• type: "module"

content_scripts

Describes scripts and styles injected into matching pages.

Each entry may include:

• matches
• js
• css
• run_at
• all_frames

permissions

Declares extension permissions such as:

• storage
• tabs
• activeTab
• scripting

host_permissions

Declares URL patterns the extension can access, such as:

• *://*.example.com/*

web_accessible_resources

Lists resources that extension pages or content scripts expose to matching web pages.

content_security_policy

Defines the extension page content security policy. Maho supports the extension_pages property.

options_page and options_ui

Use these fields to provide settings pages.

• options_page points to a page path
• options_ui supports page and open_in_tab

devtools_page

Registers a DevTools page for the extension.

Installation & Intent

Desktop Maho supports Manifest V3 extensions via unpacked local directories, CRX package imports, and desktop Chrome Web Store navigation intent. Manifest V2 and mobile platforms (iOS / Android) are explicitly unsupported.

Installation Methods

1. Unpacked Directories: Point Maho to any local directory containing a valid manifest.json.
2. CRX Files: Import packaged .crx extension archives directly into desktop Maho.
3. Chrome Web Store: Desktop Maho supplies Chrome Web Store User-Agent compatibility headers for store browsing and package downloads.

Intent & Limitations

• Desktop Only: Extension support is exclusive to desktop builds (macOS / Linux / Windows). Mobile shells do not support extension execution.
• Manifest V3 Only: Manifest V2 extensions are deprecated and not supported.
• API Availability: Extension capabilities depend on standard Chromium extension APIs exposed on desktop.

Lifecycle

Maho follows the normal extension lifecycle for unpacked MV3 extensions.

Install

During install, Maho:

• Parses the manifest
• Validates supported fields
• Loads extension resources
• Starts the background service worker

Enable

When enabled, Maho:

• Injects content scripts into matching pages
• Shows the extension action button in the toolbar
• Makes extension APIs available to the extent they are bridged by Maho

Disable

When disabled, Maho:

• Removes content scripts from active use
• Hides the action button
• Stops the service worker

Uninstall

When uninstalled, Maho:

• Clears extension data
• Wipes extension storage
• Removes all installed resources for that extension

Content script matching

Content scripts use Chrome-style matching rules.

Match patterns

The matches field supports standard Chrome match patterns, including:

• <all_urls>
• *://*.example.com/*

Glob patterns

Maho also supports glob patterns for more fine-grained URL matching where applicable.

Run time

The run_at field supports the standard MV3 injection times:

• document_start
• document_end
• document_idle

Frame targeting

Use all_frames to control whether scripts inject into subframes.

• true injects into iframes as well as the top-level frame
• false injects only into the top-level frame

Storage API

Maho implements chrome.storage.local for extension storage.

Supported methods

Method	Behavior
get(keys)	Retrieve stored values
set(items)	Store key-value pairs
remove(keys)	Delete specific keys
clear()	Wipe all storage for the extension

Change events

Storage change events fire when values change. Change records include oldValue and newValue.

This lets extensions react to local state updates without polling.

Extension bridge

Maho provides bridge APIs for communication between extension scripts and the browser.

Supported bridge behavior

• chrome.tabs.query() for querying open tabs
• chrome.runtime.sendMessage() and onMessage for extension messaging
• Tab management APIs for creating, updating, and removing tabs

Scope limits

Only APIs that Maho explicitly bridges are available. Not every Chrome API is exposed.

If an extension depends on an unsupported API, it may install but fail when it tries to call that API.

Compatibility guidance

For best results, keep extensions within the supported MV3 surface area:

• Use manifest_version: 3
• Prefer APIs Maho explicitly supports
• Keep background logic in a service worker
• Declare all required permissions and host permissions up front

Troubleshooting

Manifest validation errors

If Maho rejects an extension at load time, check the manifest for:

• Missing required fields
• Invalid manifest_version
• Version strings that do not follow semver format
• Unsupported field shapes or values

Content scripts not running

Verify:

• The matches patterns are correct
• The page URL is covered by host_permissions where needed
• run_at is set appropriately
• all_frames matches the intended injection target

Storage behavior

If extension state does not persist as expected, confirm that the extension is using chrome.storage.local and not relying on an unavailable storage API.

Summary

Maho’s extension support is centered on unpacked Manifest V3 extensions, Chrome-style content script matching, local storage, and a limited bridge of browser APIs. Extensions that stay within that supported surface can run in Maho with little friction.