Better Plugins Manager

Better Add-on Manager

A more capable plugin manager for Obsidian.

Keep plugin-heavy Obsidian vaults fast and manageable with delayed startup, batch controls, groups and tags, GitHub installs, and guided conflict diagnosis.

🎯 What is BPM?

Better Add-on Manager (BPM) is a control center for Obsidian community plugins, designed for vaults that rely on many plugins and need more than simple enable/disable toggles.

It helps you keep startup responsive, organize plugins by workflow, install plugins from GitHub releases, and isolate conflicts when something breaks.

✨ Core Features

BPM is organized around five focused tabs. Each tab owns one workflow, so related controls stay together and the manager remains easy to scan across desktop and mobile.

🧩 Plugin View

The main tab for day-to-day plugin management.

📥 Install Hub

The Install Hub handles GitHub-based installation and the sources BPM can track after installation.

📦 Transfer Pack

The Transfer Pack tab moves plugin setups between vaults without turning the README into a manual checklist.

🎛️ Ribbon Order

The Ribbon Order tab keeps Obsidian's left ribbon predictable, especially when delayed plugins register icons after startup.

🔍 Conflict Diagnosis

The Conflict Diagnosis tab guides plugin conflict testing step by step, keeping the tested state and result in one place.

📦 Installation

Community Plugins

Recommended for most users.

1. Open Obsidian Settings → Community Plugins.
2. Search for Better Add-on Manager.
3. Install and enable the plugin.

Manual Install

Use this when you want to install a GitHub release directly.

1. Download the latest release.
2. Copy main.js, manifest.json, and styles.css into .obsidian/plugins/better-plugins-manager/.
3. Restart Obsidian.
4. Enable Better Add-on Manager from Settings → Community Plugins.

🚦 Quick Start

Open BPM

After enabling the plugin, open BPM in either way:

• Click the BPM icon in the left ribbon.
• Run Open the plugin manager from the command palette.

First Steps

1. Start in Plugin View to review installed plugins, filters, groups, tags, and delay settings.
2. Use Install Hub when installing plugins or themes from GitHub.
3. Use Transfer Pack when moving a plugin setup between vaults.
4. Use Conflict Diagnosis when a plugin issue needs guided isolation.

Interaction Tips

• Left-click primary controls to toggle, edit, install, import, or run an action.
• Right-click a plugin item to open its context menu.
• Hover toolbar buttons to see tooltips; on touch devices, use long press where supported.

Device management

Open Devices in the manager (on mobile: More → Devices). Enable Manage by device type, then check this device's type. Device types are fixed to Computer, Tablet and Phone; each type can hold several named presets and starts with one that inherits your current settings. Enabling this feature is optional.

Each preset stores plugin enabled states, assigned delay groups, appearance, and Ribbon visibility/order. The Devices page manages this device's type, preset creation/duplication/renaming/deletion, and which preset this device uses; any preset can reuse another preset's settings. When a type has not been configured yet and exactly one configured preset exists in another type, it is adopted automatically; with several candidates nothing is chosen for you — use Reuse another preset's settings on the Devices page. The device list is informational. The manager itself and BPM-ignored plugins are excluded from device-specific plugin switching. Group/tag metadata and delay definitions stay global. Desktop-only plugins are never started by the device manager on mobile.

The three scoped tabs — Plugins, Appearance and Ribbon — carry the same Configure for device selector, listing named presets grouped by device type. Editing the preset this device uses applies immediately; editing another preset only saves it, and the device using it picks the change up on its next start or reload. Plugin enable/delay, appearance (theme and CSS snippet states), and Ribbon visibility/order are stored per preset; install sources, import/export, troubleshoot, groups, tags and delay definitions stay global.

Device records are kept in one small file per device under the vault's config directory, so every device sees the others after syncing; the preset this device uses stays local. Names default to the desktop hostname or the mobile model and can be edited. The local identity stays in Obsidian's device-local storage. The device type is detected from Obsidian's platform information and can be corrected manually or with Detect again from platform. When the platform identifier refreshes (sync system or software update), the old device record is migrated to the new identifier and the locally stored preset choice is kept; if that preset was deleted elsewhere, the device falls back to the first preset of its type and says so. There is no per-device configuration: mobile has no stable long-lived device identifier, so per-device forks cannot be reconciled after syncing. To tell two devices of the same type apart, create multiple named presets and pick one on each device. Reinstalling or clearing local data can create a new device record; just pick a preset again. Other devices apply synced changes after reloading the plugin. Concurrent edits follow your sync provider's conflict handling; there is no live cross-device merge.

Why a mobile device can appear more than once

Mobile platforms do not give web or plugin code a stable hardware identifier:

• Obsidian may not expose Capacitor's Device bridge at all. When it does, getId() is an app/vendor-scoped value, not a physical-device serial; it can change after clearing app data, reinstalling the app, moving to a new WebView data directory, or an OS/vendor migration.
• The fallback is a UUID kept in Obsidian's device-local storage. It survives normal restarts, reloads and software updates, but not clearing app storage or reinstalling the app.
• Device-local storage belongs to one installation, not to the physical device, and is never synced.
• BPM stores only a hash of the platform identifier, uses it for the device list and to remember this installation's preset choice, and never keys configuration by device id. A duplicate or removed record therefore does not change presets, their contents, or which preset another installation uses.
• To treat two installations as the same device, rename or remove the stale record manually and pick the same named preset on each installation. Per-device configuration is intentionally absent because it cannot be reconciled reliably after syncing.

Native Obsidian plugins can start before the manager applies a preset. Use the existing delayed-start mode and startup takeover if you need the manager to control startup ordering. Missing plugins and unavailable Ribbon icons retain their saved choices. Reorder Ribbon items using the up/down buttons on touch devices.

Validation: bun run build, node --test tests/device-management.test.mjs. UI validation uses an isolated empty vault; physical touch scrolling still requires mobile-device testing.

Security and Disclosure

BPM is a local Obsidian plugin manager, but some features intentionally use external services or browser APIs:

• External network requests: BPM contacts GitHub only for user-visible plugin management features such as fetching community plugin metadata, resolving repositories, checking releases, and installing or updating plugins/themes from GitHub. These requests may use github.com, api.github.com, and raw.githubusercontent.com. BPM also opens github.com repository pages and the project tutorial link on www.bilibili.com only when the user clicks the related buttons.
• Clipboard access: BPM writes to the system clipboard only when the user clicks Copy ID for a plugin.
• Vault file access: BPM reads plugin/theme metadata, selected plugin configuration files, transfer packages, and legacy export folders for management, migration, backup, import/export, and troubleshooting features. It does not upload vault notes to a remote service.
• Device records: When device management is used, BPM writes one small JSON file per device into the vault's config directory (.obsidian/better-plugins-manager-device-<id>.json) so devices can list each other after syncing. These files contain only a device id, display name, device type, and last-seen timestamp — no notes, plugin settings, or credentials. They are written with Obsidian's vault adapter, never outside the vault, and removed when the device is removed from the list.
• Base64 encoding/decoding: BPM uses runtime btoa/atob only to pack and restore binary/text files inside local Transfer Pack JSON data. It is not used to hide API keys, URLs, remote code, or executable payloads.
• Scanning limitations: If a plugin catalog or marketplace reports that malware, obfuscation, or network scanning is unavailable, review the source code in this repository and the release assets before installing. BPM does not intentionally obfuscate its source.

🔍 Conflict Diagnosis Tutorial

Use Conflict Diagnosis when a problem appears after enabling community plugins and you need a structured way to narrow down the cause.

Workflow

1. Open the Conflict Diagnosis tab, or run Troubleshoot plugin conflicts from the command palette.
2. Start a diagnosis session. BPM records the current plugin state before changing anything.
3. Test your vault after each step, then choose Problem Still Exists or Problem Gone.
4. Continue through the guided split tests until BPM narrows the result to a plugin or plugin pair.
5. Review the result, restore the original plugin state or keep the current state, then generate a Markdown report if needed.

Notes

• Diagnosis depends on your feedback at each step; use the same test action every time.
• Intermittent bugs, load-order issues, configuration-specific bugs, or conflicts involving three or more plugins may still need manual verification.
• You can undo the previous step, restart Obsidian during testing, exit the session, restore the original state, or keep the current state.

🛡️ Startup Takeover

When Delayed Startup is enabled, BPM checks .obsidian/community-plugins.json to make sure Obsidian and BPM are not trying to control the same plugins at startup.

Taking over keeps delayed startup, enabled state, and BPM's plugin records consistent. After a successful takeover, restart Obsidian so the startup list is applied cleanly.

📦 Transfer & Legacy Export

For current versions, use the Transfer Pack tab to move setups between vaults. It exports and imports plugin lists, themes, selected plugin configs, groups, tags, delay presets, layout data, ribbon order, source subscriptions, install history, and workspace preferences.

The older Markdown/frontmatter export for Obsidian Base is kept only for legacy data compatibility. New setups should use Transfer Pack instead of configuring a Base export folder.

⚙️ Settings

BPM settings are split into focused pages:

⌨️ Commands

📱 Compatibility

The plugin automatically switches between desktop/mobile layouts based on the platform.

🤝 Contributing

Issues and PRs are welcome!

• Bug Reports: Please include logs and reproduction steps
• Feature Requests: Consider opening a discussion or issue first

🙏 Acknowledgments

• The ribbon sorting feature is inspired by Obsidian-ribbon-sort

📄 License

MIT