Feature Request: Unified Update Command - Sync Binary + Plugin Updates

[possebon]

Feature Request: Unified Update Command for Binary + Plugin Synchronization

Problem Statement

Plannotator has a two-component architecture that can become desynchronized during updates:

1. Binary: ~/.local/bin/plannotator (installed via curl -fsSL https://plannotator.ai/install.sh | bash)
2. Claude Code Plugin: ~/.claude/plugins/cache/plannotator/plannotator/{version}/ (installed via /plugin install plannotator@plannotator)

Current Update Flow (Broken)

When a new version is released:

1. User runs curl -fsSL https://plannotator.ai/install.sh | bash

   • ✅ Updates binary to v0.4.0
   • ❌ Plugin cache still at v0.3.1

2. Claude Code calls plannotator command (v0.4.0)

   • But uses hooks configuration from plugin cache (v0.3.1)
   • Potential version mismatches, missing features, broken functionality

Real-World Impact

• UI shows update message but updating only fixes half the system
• Hooks may be outdated while binary has new capabilities
• User confusion about which component needs updating
• No clear single command to update everything

Current State Analysis

# Binary location and version
$ which plannotator
~/.local/bin/plannotator

# Plugin cache location
$ ls ~/.claude/plugins/cache/plannotator/plannotator/
0.3.1/  # ← Out of sync after binary update

# Hooks are loaded from plugin cache
$ cat ~/.claude/plugins/cache/plannotator/plannotator/0.3.1/hooks/hooks.json

Proposed Solutions

Option 1: Post-Install Hook in install.sh (Recommended)

Implementation: Modify install.sh to trigger Claude Code plugin update after binary installation.

# At end of install.sh
echo "🔄 Updating Claude Code plugin..."

# Force plugin re-download
claude plugin update plannotator@plannotator 2>/dev/null || \
  echo "⚠️  Please restart Claude Code and run: /plugin update plannotator@plannotator"

Pros:

• Single command updates both components
• Familiar workflow (users already run install script)
• Backward compatible

Cons:

• Requires Claude Code to be installed
• Might need Claude Code CLI detection

---

Option 2: Claude Plugin Auto-Detection

Implementation: Binary checks plugin version on startup and warns if mismatched.

// In server/index.ts startup
const binaryVersion = "0.4.0"; // From build
const pluginVersion = process.env.PLANNOTATOR_PLUGIN_VERSION; // Set by Claude

if (binaryVersion !== pluginVersion) {
  console.error(`
⚠️  Version Mismatch Detected:
   Binary: v${binaryVersion}
   Plugin: v${pluginVersion}
   
   Please update the plugin:
   /plugin update plannotator@plannotator
  `);
}

Pros:

• Catches version drift immediately
• Clear user guidance
• No external dependencies

Cons:

• Reactive (shows warning after problem occurs)
• Doesn't auto-fix

---

Option 3: Plugin-Managed Binary

Implementation: Claude Code plugin downloads and manages its own binary copy.

~/.claude/plugins/cache/plannotator/plannotator/0.4.0/
├── bin/
│   └── plannotator         # Plugin's own binary
├── hooks/
│   └── hooks.json
└── server/
    └── index.ts

Update hooks.json to use plugin-local binary:

{
  "hooks": {
    "PermissionRequest": [{
      "matcher": "ExitPlanMode",
      "hooks": [{
        "type": "command",
        "command": "$PLUGIN_PATH/bin/plannotator",  // Plugin-relative path
        "timeout": 1800
      }]
    }]
  }
}

Pros:

• Perfect synchronization - plugin and binary always match
• Single update command: /plugin update plannotator@plannotator
• No PATH dependencies

Cons:

• Larger plugin download size
• Breaks standalone binary usage (if users rely on that)
• More complex build/release process

---

Option 4: Unified Update Command

Implementation: Create plannotator update subcommand that handles both.

$ plannotator update
🔄 Checking for updates...
📦 Downloading plannotator v0.4.0...
✅ Binary updated
🔌 Updating Claude Code plugin...
✅ Plugin updated
🎉 Update complete! Please restart Claude Code.

Pros:

• Clear, single command
• User-friendly UX
• Can check versions before updating

Cons:

• Requires the old binary to update itself (chicken-egg problem)
• Complex implementation

---

Recommended Approach: Hybrid Solution

Combine Option 1 (post-install hook) and Option 2 (version detection):

Phase 1: Immediate Fix

1. Modify install.sh to suggest plugin update after binary installation
2. Add version mismatch detection to binary startup

Phase 2: Long-term Solution

3. Transition to Option 3 (plugin-managed binary) for complete sync
4. Keep standalone binary for non-Claude-Code users

Implementation Checklist

• Add version check to binary (show warning on mismatch)
• Update install.sh to prompt for plugin update
• Document update process in README
• Consider plugin-managed binary for future versions
• Add /plugin update reminder to plannotator UI

Example User Experience (After Fix)

# User runs update
$ curl -fsSL https://plannotator.ai/install.sh | bash

✅ Plannotator binary updated to v0.4.0
⚠️  Claude Code plugin is out of date (v0.3.1)
   
   To complete the update, run:
   /plugin update plannotator@plannotator
   
   Or restart Claude Code and it will auto-update.

Additional Context

• Current version: v0.3.1
• Binary size: ~60MB (Bun compiled executable)
• Plugin contains: hooks config + TypeScript server code + UI assets
• Update frequency: Important for bug fixes and new features (like project tags!)

---

This issue blocks efficient workflows for users working across multiple projects who need the latest features without manual intervention.

[backnotprop]

Thanks for the detailed write-up! I want to clarify how the architecture actually works, since it might not be as fragile as it seems.

How it works:

The plugin only contains two things:

• plugin.json - metadata (name, version, description)
• hooks/hooks.json - tells Claude Code: "when ExitPlanMode triggers, run plannotator command"

That's it. The plugin doesn't contain any code or logic - it's just a hook trigger. The binary in ~/.local/bin/plannotator does all the actual work (server, UI, Obsidian/Bear integration, etc.).

So what happens with version mismatch?

If binary is v0.4.0 and plugin is v0.3.1... nothing breaks. The plugin's only job is to say "run plannotator" - which it does. The binary handles everything else.

The versions would only need to stay in sync if we changed the hooks.json structure (added new hooks, changed matchers, etc.). But that's rare - the hook config has been stable.

That said...

I understand the UX concern of seeing mismatched version numbers. A few options:

1. We could treat the plugin version as independent (it's just a hook trigger, could stay at 1.0 forever)
2. Document that only the binary version matters for features
3. Add a note in install.sh output clarifying this

Does this help clarify? Let me know if you've hit an actual functional issue with mismatched versions - that would be useful to know!

[backnotprop]

Option 3: Plugin-Managed Binary

This is why I'll keep this issue open. I need to investigate if Claude can just manage the binary for me, similar to how OpenCode works.