Getting Started

Prerequisites

bd must be installed before the plugin will work. The plugin registers hooks that call bd on every session start; if bd isn't present, those hooks fail silently and you lose persistent memory.

brew install beads          # macOS / Linux
# or
npm install -g @beads/bd    # any platform

Verify with bd version. Then install the plugin (see below), then run bd init in each project.

Note: Native plugin install (Tier 1) installs skills and hooks automatically. It does NOT run bd init — you must do that yourself per project.

Optional: A DoltHub account if you want cross-session sync via bd dolt push/pull. Without it, beads still works locally.

Go deeper — upstream Beads docs

Installation — every bd install channel (brew, npm, curl, go), platform notes, upgrades

Supported Platforms

Tier 1 — Verified

These paths are tested end-to-end. Prefer them.

CLI	Install method
Claude Code	Native plugin marketplace (see below)
Codex CLI	Native plugin marketplace + `codex_hooks = true` (see below)
OpenCode	git plugin spec in `opencode.json` (see below)

Tier 2 — Best-effort

Config validated; not E2E-tested by us. Use with that in mind.

CLI	Install	Update	Notes
Cursor	`/add-plugin beads-superpowers` (in Cursor Agent)	Marketplace UI	config validated by us; not E2E-tested
GitHub Copilot CLI	`copilot plugin marketplace add DollarDill/beads-superpowers` then `copilot plugin install beads-superpowers@beads-superpowers-marketplace`	`copilot plugin update beads-superpowers`	rides the Claude-plugin fallback (skills + session-start via the shared `hooks/hooks.json`), the same mechanism upstream ships; requires Copilot CLI v1.0.11+
Kimi Code	`/plugins install https://github.com/DollarDill/beads-superpowers` (run `/new` after)	—
Antigravity	`agy plugin install https://github.com/DollarDill/beads-superpowers`	—	reuses the Claude plugin manifest — the same mechanism upstream verified; not E2E-tested by us
Factory Droid	`droid plugin marketplace add https://github.com/DollarDill/beads-superpowers` then `droid plugin install beads-superpowers@beads-superpowers-marketplace`	—	reuses the Claude plugin manifest — the same mechanism upstream verified; not E2E-tested by us
Pi	`pi install git:github.com/DollarDill/beads-superpowers`	—	config validated by us; not E2E-tested

Install the plugin

⚠️ Coexistence warning: Do not install alongside obra/superpowers. Skill names collide — pick one or the other.

Claude Code

claude plugin marketplace add DollarDill/beads-superpowers
claude plugin install beads-superpowers@beads-superpowers-marketplace

Or as slash commands inside a Claude Code session: /plugin marketplace add DollarDill/beads-superpowers then /plugin install beads-superpowers@beads-superpowers-marketplace.

Codex CLI

codex plugin marketplace add DollarDill/beads-superpowers
codex plugin install beads-superpowers@beads-superpowers-marketplace

After installing, enable hooks in ~/.codex/config.toml:

[features]
codex_hooks = true

To get the SessionStart hook under Codex, use the scripted installer (install.sh) rather than the plugin channel — the plugin channel installs the skills but does not wire the hook.

OpenCode

Add to the plugin array in your opencode.json (global or project-level):

{
  "plugin": ["beads-superpowers@git+https://github.com/DollarDill/beads-superpowers.git"]
}

Restart OpenCode. Skills auto-register and the session bootstrap + beads context inject automatically — no other steps. Details, version pinning, migration from pre-0.12 installer copies, and troubleshooting: .opencode/INSTALL.md.

Scripted install (`curl | bash`)

The curl installer also works for Claude Code and Codex when you need more than a plain plugin install:

curl -fsSL https://raw.githubusercontent.com/DollarDill/beads-superpowers/main/install.sh | bash

The installer auto-detects which CLIs are on your system and installs skills and hooks for each:

CLI	Skills path	Hooks / Plugin
Claude Code	`~/.claude/skills/`	SessionStart hook in `settings.json`
Codex	`~/.codex/skills/`	Enable with `codex_hooks = true` in `~/.codex/config.toml`

Use the scripted install when you need any of:

Beads/Dolt bootstrap — auto-detects whether bd is installed and guides setup
Hook registration — writes the SessionStart entry to settings.json (required when using npx or manual install paths)
yegge.md orchestrator — optional add-on: installed only when you pass --with-yegge. The flag forces the scripted tarball/git install tier (the plugin and npx tiers are skipped for that run), so it can't be combined with a plugin-managed install in one command
Version pinning — --version X.Y.Z for reproducible CI installs
CI environments — use --yes --skip-checksum for unattended runs

Supports --yes (skip prompts), --version X.Y.Z, --with-yegge, --dry-run, --skip-checksum, and --uninstall.

npx (Vercel Skills CLI)

npx skills add DollarDill/beads-superpowers -a claude-code -g --copy -y
# Use -a codex to also install for Codex CLI.

Installs the skills only — no hooks. Skill activation relies on your harness's native skill discovery. For the full experience (session-start injection of skill context + a composed beads context), use the plugin install or the scripted install above. To get beads context on an npx install, run bd setup claude (beads' own hook installer).

First project setup

Initialise beads in your project:

cd your-project
bd init

This creates .beads/ (config, metadata, git hooks), CLAUDE.md, and AGENTS.md. The plugin's session-start hook automatically detects if bd setup claude hooks are present and skips its own beads-context section, so no manual cleanup is needed.

Dolt remote (optional)

For cross-session sync of your task history:

bd dolt remote add origin https://doltremoteapi.dolthub.com/your-org/your-repo
bd dolt push    # test the connection

Go deeper — upstream Beads docs

Core concepts — how the Dolt-backed database and sync model work
Recovery guides — when a sync fails or history diverges

Updating

Claude Code:

claude plugin marketplace update beads-superpowers-marketplace

Codex CLI:

codex plugin marketplace update beads-superpowers-marketplace

Copilot CLI:

copilot plugin update beads-superpowers

Scripted / npx:

curl -fsSL https://raw.githubusercontent.com/DollarDill/beads-superpowers/main/install.sh | bash
# or
npx skills add DollarDill/beads-superpowers -g --copy -y

Re-running the installer or npx skills add overwrites the existing installation. No bd init needed — your existing .beads/ database is untouched.

OpenCode:

Restart OpenCode to pick up the latest commit from the git plugin spec. Some OpenCode/Bun versions cache the resolved git dependency — clear OpenCode's package cache or reinstall the plugin if updates don't appear. To pin a specific version, append a #vX.Y.Z ref to the plugin spec. Details: .opencode/INSTALL.md.

Verify it works

Start a fresh session in your CLI of choice, then:

Check skills loaded: Type /skills (Claude Code/Codex) or check the skill list in OpenCode — you should see 22 skills prefixed with beads-superpowers:
Check beads works: Run bd ready and bd stats in the terminal

If skills aren't showing, the plugin may not be installed for your CLI. If bd ready fails, beads isn't initialised in this project (bd init).

How the hooks work

Claude Code and Codex share one hook script — SessionStart — registered via hooks/hooks.json for Claude Code and wired by install.sh for Codex. It fires on every session start, clear, and compact. It reads the using-superpowers skill (which routes to all other skills), then composes a lean beads context: a short bd command pointer plus curated core memories (salience ≥ 4 and the latest continuation, selected under a hard 8 KB byte ceiling), with a disclosure line stating how many of the store's memories made it in. The combined context is ~3–4k tokens — the hook no longer runs bd prime. If bd prime is already registered as a hook elsewhere, the beads section is skipped automatically.

sequenceDiagram
  participant CC as CLI (Claude Code / Codex)
  participant SH as SessionStart Hook
  participant Agent as Agent

  CC->>SH: Session begins
  SH->>SH: Read using-superpowers skill
  SH->>SH: Compose beads context (bd pointer + core memories)
  SH-->>Agent: Inject skills context + beads state
  Note over Agent: Agent is now skill-aware

Hold "Alt" / "Option" to enable pan & zoom

OpenCode uses its own JavaScript plugin (.opencode/plugins/beads-superpowers.js) instead of hooks/hooks.json, with three in-process hooks: a config hook auto-registers the skills, an experimental.chat.messages.transform hook injects the same bootstrap into the first user message once per session, and an experimental.session.compacting hook re-injects beads context after the context window compacts.

Configuration

Instruction priority when things conflict:

Your project's CLAUDE.md (highest)
Plugin skills
Default system prompt (lowest)

To override a skill's behaviour, add instructions to your project's CLAUDE.md — no need to fork the plugin.

Beads project config lives in .beads/config.yaml. The defaults work for most projects.

Troubleshooting

Skills not loading — Run /plugins to check the plugin is installed, then /skills to check skills are visible. If missing, reinstall: claude plugin marketplace update beads-superpowers-marketplace.

bd: command not found — Beads isn't installed or isn't on your PATH. Run brew install beads or npm install -g @beads/bd, then verify with bd version.

No .beads directory — Run bd init in your project directory. The plugin automatically handles duplicate hook detection.

Double context injection — The plugin detects bd setup claude hooks in project and global settings and automatically skips its own beads-context section; same-event double-firing under multi-scope hook registration is suppressed by a dedup marker. If you still see duplicates, run bd setup claude --remove.

A .beads/PRIME.md file appeared — that's the plugin's guarded safety net: it makes a stray bd prime call emit a lean pointer instead of the full memory dump. It is only written when .beads/ exists and never overwrites an existing file. Disable with bd config set custom.prime-safety-net false.

Stale plugin cache — The cache doesn't update when you edit skill files locally. Either symlink the cache to your checkout:

rm -rf ~/.claude/plugins/cache/beads-superpowers-marketplace/beads-superpowers/0.11.0
ln -s ~/workplace/beads-superpowers \
  ~/.claude/plugins/cache/beads-superpowers-marketplace/beads-superpowers/0.11.0

Or reinstall. Note: claude plugin update has a known cache bug — the symlink is more reliable.

Hook not firing — Check the hook is executable: chmod +x hooks/session-start.

Stale reminder hook after updating from ≤0.8.2 — Earlier versions registered a per-prompt superpowers-reminder.sh hook that no longer ships. See the migration one-liner in the README's npx section.

bd dolt push fails — You need a Dolt remote configured first (bd dolt remote add origin <url>). If you don't need remote sync, the failure is harmless — beads works fine locally.