https://github.com/osteele/bisect-obsidian-extensions
A binary search tool to identify problematic Obsidian plugins that may be causing crashes, freezes, or other issues in your vault
https://github.com/osteele/bisect-obsidian-extensions
obsidian obsidian-plugins troubleshooting
Last synced: about 1 month ago
JSON representation
A binary search tool to identify problematic Obsidian plugins that may be causing crashes, freezes, or other issues in your vault
- Host: GitHub
- URL: https://github.com/osteele/bisect-obsidian-extensions
- Owner: osteele
- License: mit
- Created: 2025-08-30T02:46:39.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-08-30T02:51:51.000Z (10 months ago)
- Last Synced: 2025-10-19T15:41:19.279Z (8 months ago)
- Topics: obsidian, obsidian-plugins, troubleshooting
- Language: Python
- Homepage:
- Size: 10.7 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Roadmap: ROADMAP.md
Awesome Lists containing this project
README
# 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
1. Ensure Python 3.6+ is installed on your system
2. Clone or download this repository
3. Make the script executable (if on macOS/Linux):
```bash
chmod +x bisect-obsidian-extensions.py
```
## Usage
Run the script with your vault path as an argument:
```bash
python bisect-obsidian-extensions.py /path/to/your/vault
```
Or if made executable:
```bash
./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:
1. **Interference with testing**: lazy-plugins delays the loading of other plugins, making it difficult to reliably test whether a specific plugin configuration causes issues
2. **Intermittent reproduction**: When lazy-plugins is enabled, problems may appear intermittently based on timing, making binary search unreliable
3. **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:
```bash
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
1. **Backup**: The script backs up your current plugin configuration (`community-plugins.json`)
2. **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
3. **Testing**: For each test:
- Closes any running Obsidian instance
- Updates the plugin configuration
- Launches Obsidian with your vault
- Prompts for your feedback
4. **Narrowing**: Progressively narrows down to a single plugin
5. **Confirmation**: Tests with only the suspected plugin disabled to confirm
6. **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)