# How to Check for Superpowers Plugin Updates: 3 Methods Explained

> Learn 3 easy methods to check for Superpowers plugin updates using console commands, git pull, or programmatic calls. Keep your Superpowers plugin current.

- Repository: [Jesse Vincent/superpowers](https://github.com/obra/superpowers)
- Tags: how-to-guide
- Published: 2026-02-16

---

**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`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/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:

```bash
/plugin update superpowers

```

This command calls the plugin manager which internally executes `git pull` inside `~/.config/opencode/superpowers`. According to the [README.md](https://github.com/obra/superpowers/blob/main/README.md#updating), 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:

```bash
cd ~/.config/opencode/superpowers
git pull

```

As documented in [docs/README.opencode.md](https://github.com/obra/superpowers/blob/main/docs/README.opencode.md#updating), 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`](https://github.com/obra/superpowers/blob/main/lib/skills-core.js).

```javascript
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`](https://github.com/obra/superpowers/blob/main/hooks/session-start.sh) (lines 17-44):

```bash

# 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`](https://github.com/obra/superpowers/blob/main/hooks/session-start.sh).

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

1. Loads the core utilities from [`lib/skills-core.js`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/hooks/session-start.sh) script executes `checkForUpdates()` from [`lib/skills-core.js`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/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.