How to Check for Superpowers Plugin Updates: 3 Methods Explained

You can check for Superpowers plugin updates using the platform command /plugin update superpowers, manually running git pull in ~/.config/opencode/superpowers, or programmatically calling checkForUpdates() from lib/skills-core.js.

The Superpowers plugin for OpenCode and Claude Code maintains its codebase in a local Git repository. Knowing how to check for Superpowers plugin updates ensures you always have the latest skills and security patches. This guide covers the three supported methods to verify and apply updates, from simple CLI commands to programmatic hooks.

How Superpowers Checks for Updates Internally

When a session starts, the core utility checkForUpdates() (defined in lib/skills-core.js at lines 148-166) runs a non-blocking git fetch followed by git status on the plugin directory. If the local clone is behind the remote, the function returns true and the session-start hook injects a notice:

⚠️ **Updates available!** Run `cd ~/.config/opencode/superpowers && git pull` to update Superpowers.

The check uses a 3-second timeout to avoid hanging when offline, parsing the status output for ## … [behind …] to detect lagging branches.

Method 1: Use the Platform Update Command

The fastest way to check for and apply Superpowers plugin updates is through the host platform's built-in plugin manager.

For Claude Code or OpenCode, run:

/plugin update superpowers

This command calls the plugin manager which internally executes git pull inside ~/.config/opencode/superpowers. According to the README.md, this works across all supported operating systems and requires no manual Git intervention.

Method 2: Manual Git Pull

For explicit control over the update process—or when you need to inspect changes before merging—manually update the repository.

Open a terminal and run:

cd ~/.config/opencode/superpowers
git pull

As documented in docs/README.opencode.md, you must restart OpenCode or the Claude Code session after pulling to load the new code into memory.

This method is ideal when you have local modifications that might conflict with upstream changes, allowing you to resolve merge conflicts manually.

Method 3: Programmatic Check with checkForUpdates()

If you are building a custom skill or automation script that needs to verify update status before proceeding, import the internal helper from lib/skills-core.js.

import { checkForUpdates } from './lib/skills-core.js';
import path from 'path';

const pluginDir = path.join(process.env.HOME, '.config', 'opencode', 'superpowers');

if (checkForUpdates(pluginDir)) {
  console.log('⚠️ Updates available – run git pull in the plugin directory.');
}

The checkForUpdates() function:

• Executes git fetch origin && git status --porcelain=v1 --branch with a 3-second timeout
• Returns true only when the status output contains [behind …] indicating the local branch lags the remote
• Returns false if the repository is current, offline, or the check times out

You can also invoke this from a shell hook script, as implemented in hooks/session-start.sh (lines 17-44):

# Inside hooks/session-start.sh

if node -e "require('$PLUGIN_ROOT/lib/skills-core').checkForUpdates('$PLUGIN_ROOT')"; then
  echo "⚠️ Updates available – run git pull in $PLUGIN_ROOT"
fi

Where the Update Check Runs Automatically

Superpowers surfaces update notifications without manual intervention through the session-start hook defined in hooks/session-start.sh.

When OpenCode or Claude Code initializes a session, the hook:

1. Loads the core utilities from lib/skills-core.js
2. Calls checkForUpdates() on the plugin directory at ~/.config/opencode/superpowers
3. Injects a JSON payload containing the update notice into the agent context (lines 17-44 of hooks/session-start.sh)

This ensures you see the ⚠️ **Updates available!** warning at the start of every session if the local clone is behind the remote, prompting you to run git pull before beginning work.

Summary

• Automatic detection: The checkForUpdates() function in lib/skills-core.js runs at session start to detect if the local repository lags behind the remote.
• Platform command: Use /plugin update superpowers for a one-line update through Claude Code or OpenCode.
• Manual control: Run git pull inside ~/.config/opencode/superpowers when you need to inspect changes or resolve conflicts, then restart your session.
• Programmatic access: Import checkForUpdates() from lib/skills-core.js to embed update checks in custom skills or automation scripts.

Frequently Asked Questions

Where is the Superpowers plugin installed?

The Superpowers plugin lives in ~/.config/opencode/superpowers (or the equivalent XDG config directory on your system). This is a standard Git repository cloned from the remote source, allowing you to use standard Git commands like git pull, git log, and git diff to manage updates.

How does the automatic update check work?

When a session starts, the hooks/session-start.sh script executes checkForUpdates() from lib/skills-core.js (lines 148-166). This function runs git fetch followed by git status with a 3-second timeout. If the status output indicates the local branch is [behind …] the remote, the function returns true and the hook injects a warning message into the session context.

Can I disable automatic update checks?

There is no configuration flag exposed in the current codebase to disable the automatic check in hooks/session-start.sh. However, because the check uses a 3-second timeout and fails silently when offline, it does not block session startup. To effectively disable notifications, you could modify hooks/session-start.sh to comment out the checkForUpdates() call, though this would require maintaining a forked version of the plugin.

What happens if I'm offline when the check runs?

The checkForUpdates() function in lib/skills-core.js implements a 3-second timeout for the git fetch operation. If the network is unavailable or the remote is unreachable, the command times out and the function returns false, allowing the session to start normally without displaying an update notice. This ensures offline work is never blocked by the update mechanism.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}