Bisect Obsidian Extensions

A binary search tool to identify problematic Obsidian plugins that may be causing crashes, freezes, or other issues in your vault.

Features

Binary search algorithm: Efficiently narrows down the problematic plugin in O(log n) steps
Automatic backup: Creates timestamped backups of your plugin configuration before making changes
Safe operation: Restores original settings on completion or interruption
Step counter: Shows remaining steps in the search process (similar to git bisect)
Process management: Automatically closes running Obsidian instances before testing
Interactive testing: Prompts for user feedback after each test configuration

Installation

Ensure Python 3.6+ is installed on your system
Clone or download this repository
Make the script executable (if on macOS/Linux):
```
chmod +x bisect-obsidian-extensions.py
```

Usage

Run the script with your vault path as an argument:

python bisect-obsidian-extensions.py /path/to/your/vault

Or if made executable:

./bisect-obsidian-extensions.py /path/to/your/vault

Command Line Options

vault_path (required): Path to your Obsidian vault
--keep-lazy: Include the lazy-plugins extension in the search (see note below)

Note on lazy-plugins

By default, the script temporarily excludes the lazy-plugins extension from testing if it's enabled. This is because:

Interference with testing: lazy-plugins delays the loading of other plugins, making it difficult to reliably test whether a specific plugin configuration causes issues
Intermittent reproduction: When lazy-plugins is enabled, problems may appear intermittently based on timing, making binary search unreliable
False negatives: A problematic plugin might not cause issues immediately if lazy-plugins delays its loading

If you suspect lazy-plugins itself or its interaction with another plugin is causing issues, you can include it in the search:

python bisect-obsidian-extensions.py /path/to/your/vault --keep-lazy

Warning: Including lazy-plugins may result in intermittent test results. You may need to use the "[r] Retry" option multiple times to confirm whether a configuration is good or bad.

How It Works

Backup: The script backs up your current plugin configuration (community-plugins.json)
Binary Search: Uses proper binary search to isolate the problematic plugin:
- Assumes you've already confirmed the problem exists with all plugins enabled
- Tests with half the plugins enabled
- If problem occurs: the bad plugin is in the enabled half
- If no problem: the bad plugin is in the disabled half
- Continues bisecting the problematic group
Testing: For each test:
- Closes any running Obsidian instance
- Updates the plugin configuration
- Launches Obsidian with your vault
- Prompts for your feedback
Narrowing: Progressively narrows down to a single plugin
Confirmation: Tests with only the suspected plugin disabled to confirm
Restoration: Offers to keep the plugin disabled or restore original settings

Interactive Commands

During testing, you'll be prompted with these options:

[g] Good - The problem is NOT present with this configuration
[b] Bad - The problem IS present with this configuration
[r] Retry - Test the same configuration again
[q] Quit - Stop the search and restore original settings

Example Session

$ python bisect-obsidian-extensions.py ~/Documents/MyVault

Obsidian Extension Binary Search Tool
Vault: /Users/username/Documents/MyVault
✓ Configuration backed up to: /Users/username/Documents/MyVault/.obsidian/community-plugins.backup.20240115_143022.json

⚠ Note: 'lazy-plugins' has been temporarily disabled for testing
  (it delays plugin loading, making tests unreliable)
  Use --keep-lazy to include it in the search

Found 32 enabled plugins
Testing 31 plugins (excluding lazy-plugins)

Starting binary search with 31 enabled plugins
Note: 'lazy-plugins' has been temporarily excluded from testing
(Assuming you've already confirmed the problem exists with all plugins enabled)

Bisecting: 5 steps left to test after this

--- Testing with 16 plugins enabled ---
Testing group of 16 suspect plugins:
  • plugin-1
  • plugin-2
  ...

Closing existing Obsidian instance...
Launching Obsidian with vault: MyVault

==================================================
Test the current configuration and report:
  [g] Good - problem NOT present
  [b] Bad - problem IS present
  [r] Retry with same configuration
  [q] Quit and restore original settings
==================================================
Your response: b
✗ Problem found. Bad plugin is in this group of 16 plugins.
Bisecting: 4 steps left to test after this (roughly 4 steps)

[... continues until problematic plugin is found ...]

✓ Confirmed: The problematic plugin is 'problematic-plugin-name'

==================================================
RESULT: The problematic plugin is: problematic-plugin-name
==================================================

Keep this plugin disabled? [y/N]: y
✓ Configuration saved with 'problematic-plugin-name' disabled

Safety Features

Automatic Backup: Always creates a backup before making any changes
Graceful Interruption: Pressing Ctrl+C will restore your original configuration
Error Recovery: Any unexpected errors trigger automatic restoration
Confirmation Step: Tests the final result to confirm the problematic plugin

Requirements

Python 3.6 or higher
macOS (uses open command and osascript for process management)
Obsidian installed on your system

Troubleshooting

"Could not find config file"

Ensure the path points to a valid Obsidian vault (contains .obsidian folder)
Check that community plugins have been enabled at least once in the vault

Obsidian doesn't launch

Verify Obsidian is installed and can be launched manually
Check that the vault name matches what appears in Obsidian's vault switcher

Plugin still causes issues after bisect

There may be multiple problematic plugins
Try running the bisect again after disabling the first problematic plugin
Consider plugin interactions - some plugins may only cause issues when used together
If lazy-plugins was excluded and no problematic plugin was found, the issue might be caused by lazy-plugins interacting with another plugin

"No problem found" but issue persists

If the bisect doesn't find a problematic plugin but you still experience issues:

The problem might be caused by lazy-plugins (if it was excluded)
Run with --keep-lazy to include it in the search
The issue might be intermittent or related to plugin settings rather than the plugins themselves

License

MIT License - See LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Notes

Only searches among currently enabled plugins
Preserves plugin load order when testing
Works with Obsidian's community plugins only (not core plugins)

osteele / bisect-obsidian-extensions