storyhub

One Storybook for all your git worktrees: opt-in branch sections that show only the stories each branch changes, for Vite and webpack, with a CLI and MCP server

View on GithubNew to Storybook?Get started

storyhub

npm license

One Storybook for all your git worktrees.

When you work on several UI changes at once, each in its own git worktree, storyhub puts them side by side in the Storybook you already run. Every worktree you opt in gets a section at the top of the sidebar that lists only the stories its changes affect. Your normal stories stay below under "Common".

There is still one dev server, one dependency install and one module cache. Branch stories render from the worktree's changed files layered over your main checkout's modules. An MCP endpoint lets coding agents see which stories each branch changes, why, and where to view them.

The same story in Common and in a branch that only changed Button.tsx. Plan Card shows up in the branch because it imports Button.

Requirements

  • Storybook 10.5 or newer with a Vite or webpack 5 based framework. Tested with @storybook/react-vite (Vite 6 and 8) and @storybook/react-webpack5 (webpack 5.112, SWC compiler). Other frameworks on those builders should work but are untested so far.
  • Node 20.19 or newer.
  • Your branches are worktrees of the repo that runs Storybook (git worktree add ../my-feature -b my-feature).

storyhub has no runtime dependencies.

Install

Install it in the package that runs Storybook. In a monorepo that is the app or workspace with the .storybook folder, not necessarily the repo root.

npm install --save-dev --save-exact storyhub
# or
yarn add --dev --exact storyhub
pnpm add --save-dev --save-exact storyhub
bun add --dev --exact storyhub

Register the addon:

// .storybook/main.ts
const config: StorybookConfig = {
  // ...
  addons: [
    // ...your other addons
    'storyhub',
  ],
};

Check the setup from that same package directory:

npx --no-install storyhub doctor

Then start Storybook the way you always do (npm run storybook), usually from your main checkout. Whichever checkout runs it becomes the Common section; storyhub list marks it ā˜… hub with its URL. Nothing new appears until you turn a branch on.

Turn branches on

Branches are opt-in. From inside a worktree:

npx --no-install storyhub on      # show the worktree you are in
npx --no-install storyhub off     # hide it again
npx --no-install storyhub list    # every worktree and whether it is on

From anywhere in the repo, including the main checkout, name what you want:

npx --no-install storyhub on feat/login        # a branch, worktree directory name or path
npx --no-install storyhub on 'feat/*'          # a glob, saved as a pattern so future worktrees match too
npx --no-install storyhub off feat/old-thing   # switch one off even when a glob matches it

The running Storybook picks changes up within a second, with no restart.

--no-install makes npx use the copy installed in your project and fail rather than download a package from the registry. If a worktree has no node_modules of its own, run the command from a checkout that has storyhub installed (usually the main checkout) and pass the branch name. Inside package.json scripts, plain storyhub on works.

The selection is stored as storyhub.include and storyhub.exclude entries in the repo's local .git/config. It is never committed, and every worktree of the repo sees the same selection.

Tailwind

Tailwind builds its CSS from the class names it finds in your source files, and the stylesheet Storybook loads belongs to your main checkout, so on its own it only scans that checkout. A class that appears only in a branch would never be generated, and the branch's stories would render without it. storyhub points Tailwind at your worktrees as well, but how that works depends on the version.

Tailwind 4 needs no setup. storyhub adds the enabled worktrees to any stylesheet that imports tailwindcss, using Tailwind's own @source directive, and covers both your automatic detection root and any @source paths you already list. Turning a branch on regenerates the stylesheet while Storybook keeps running. This works with @tailwindcss/vite and with @tailwindcss/postcss.

Tailwind 3 only reads its scan paths from its config file, so wrap that config in withStoryhub:

// tailwind.config.ts
import { withStoryhub } from 'storyhub/tailwind';

export default withStoryhub({
  content: ['./index.html', './src/**/*.{ts,tsx}'],
  theme: { extend: {} },
});

It adds the same globs inside every worktree of the repo, but only while storyhub's dev Storybook is running, so your app's builds and other tools see the config unchanged. It includes every worktree rather than only the enabled ones because Tailwind 3 reads its config once at startup, and a branch you turn on later should not need a restart. The extra classes only end up in Storybook's dev CSS. If your config sets content.relative: true, pass its directory as well: withStoryhub(config, { base: __dirname }).

Let your agents do it

Agents working in a worktree can opt their own work in. Add something like this to your CLAUDE.md or AGENTS.md:

## Storybook
This repo uses storyhub. When you change UI in a worktree, make it visible in the shared Storybook by
running `npx --no-install storyhub on` inside the worktree (or `npx --no-install storyhub on <branch>`
from the main checkout). Run `npx --no-install storyhub off` when you are done. Use the `storyhub`
MCP tools to find the stories your branch affects, preview them (pass your story file's absolute path
or `branch`), and run their tests against your branch, which also flags regressions against Common.

Connect MCP

storyhub serves an MCP endpoint from the running Storybook at /storyhub/mcp. It is the only Storybook MCP server your agents need: when @storybook/addon-mcp is installed, storyhub passes its tools, resources and prompts through and makes its preview and test tools branch-aware. With Claude Code, put this in .mcp.json (change the port to yours) and remove any separate storybook entry:

{
  "mcpServers": {
    "storyhub": { "type": "http", "url": "http://localhost:6006/storyhub/mcp" }
  }
}

storyhub's own tools:

Tool Returns
list-worktrees Every worktree, whether it is shown, and the commands to change that
list-branches Shown branches with changed file counts, affected story counts and drift notes
get-branch-changes A branch's changed files and every affected story, each with the import chain that explains why, plus URLs
get-story-variants For a story id, its URL in Common and in every branch that changes it, for side-by-side comparison

Branch-aware versions of addon-mcp's tools (they keep addon-mcp's names and inputs, so its instructions still apply):

Tool What storyhub adds
Story preview (preview-stories, or stories-preview in addon-mcp 10.6) Pass branch, or give a story by absoluteStoryPath inside a worktree, to get the branch's preview URL. It opens the story in its branch section, and addon-mcp's inline preview app renders the branch version.
run-story-tests With a branch (or a story path inside a worktree), renders each story in headless Chromium, runs its play function and reports pass/fail plus addon-a11y results. Each branch story also runs in Common, and failures that only happen in the branch are flagged as regressions. Omit stories to test every story the branch changes. Without a branch, the call goes to addon-vitest as before.

Every other addon-mcp tool (docs, story-writing instructions, changed stories and so on) is passed through unchanged. Without addon-mcp, storyhub still serves its own tools plus the preview and test tools. Branch tests use the Playwright your project already has for addon-vitest (npx playwright install chromium if Chromium is missing).

The tools never change your repo. Turning branches on and off goes through the CLI.

Clean up old worktrees

npx --no-install storyhub clean                          # dry run: what could go and why
npx --no-install storyhub clean --older-than 30          # also list worktrees idle for 30+ days
npx --no-install storyhub clean --yes                    # remove the removable ones
npx --no-install storyhub clean --yes --delete-branches  # and delete their merged branches

A worktree is a candidate when its branch is merged into the base (origin/HEAD, else main), when every file it changed already matches the base (squash or rebase merges), when it has no commits of its own, or when it is older than --older-than. These are always kept:

  • worktrees with uncommitted changes
  • locked worktrees
  • detached HEADs with commits that are not in the base

Removal uses git worktree remove without --force, and branch deletion uses git branch -d, so git refuses anything that would lose work. Removed worktrees are dropped from the opt-in list too. Pass --base <ref> to compare against another branch, or --json for scripts.

Options

All optional:

addons: [
  {
    name: 'storyhub',
    options: {
      mode: 'opt-in',            // or 'all': show every worktree unless excluded
      include: ['release/*'],    // patterns that are always on, for the whole team (merged with git config)
      exclude: ['*-scratch'],    // patterns that are always off
      branchesPosition: 'top',   // or 'bottom' to keep Storybook's default order
      commonLabel: 'Common',     // heading for the main checkout's stories
      upstreamMcp: '/mcp',       // addon-mcp endpoint to pass through, or false to turn that off
      allowedHosts: ['dev.box'], // extra hostnames that may reach storyhub's routes (see below)
    },
  },
],

storyhub's routes (/storyhub/mcp and /__storyhub/*) only answer requests addressed to an IP address, localhost or a *.localhost name, and refuse requests sent by pages on other sites. This keeps a web page you visit from reaching them through your browser. If you open Storybook under another hostname (for example with --host on a shared machine), list it in allowedHosts; an entry starting with . also allows its subdomains, and true turns the check off. The name passed to Storybook's --host is allowed automatically.

CLI reference

Command What it does
storyhub on [target...] Show worktrees. No target means the worktree you are in.
storyhub off [target...] Hide worktrees.
storyhub list [--json] List every worktree and whether it is on.
storyhub clean [--base <ref>] [--older-than <days>] [--delete-branches] [--yes] [--json] Find and remove merged or idle worktrees. Dry run unless --yes.
storyhub status [--url <storybook url>] [--json] Affected stories and drift per branch, from the running Storybook (found automatically; --url overrides).
storyhub doctor [-c <config dir>] Check that this package is set up correctly.
storyhub --version Print the installed version.

How it works

For each branch that is on, storyhub:

  1. Diffs the worktree, including uncommitted and untracked files, against its merge base with your main checkout.
  2. Walks the import graph from every story file, using your builder's own resolver (Vite's or webpack's), so aliases, tsconfig paths and workspace packages behave as they do in your app.
  3. Marks a file dirty when it changed or imports something that did. The dirty story files are what the branch's section shows.
  4. Serves the branch as a Storybook composition ref from the same dev server. Imports from branch modules resolve as they would in your main checkout. A target loads from the worktree only if it is dirty; otherwise the main checkout's module is shared. Unchanged code is never transformed twice, and React contexts stay single instances. With webpack, loader rules (include, exclude, test) are evaluated against the main checkout's path for worktree files, so they get the same loaders.
  5. If a branch dirties something your .storybook/preview imports, such as a context provider, that branch's iframe loads the worktree's copy of the preview so providers and consumers match.

Edits in a worktree hot-reload in its section. Adding stories, changing imports, or turning a branch on or off updates the sidebar live.

Notes on branch titles

Note Meaning
deps changed package.json or a lockfile changed in the branch. The branch still renders with your main checkout's dependencies.
.storybook changed Storybook config other than preview files changed. Your main checkout's config is used.
diverged Some files changed on both sides since the branch split. The branch's version is used.
behind main Main changed files that sit between a story and the branch's changes. The branch renders its own older copy of those files. Rebase or merge main to see them current.
missing deps The branch imports packages your main checkout cannot resolve. Those stories will error.
no story changes The branch changes nothing a story imports.

Limitations

See ROADMAP.md for what is planned for each of these.

  • A story that main added after a branch split does not appear in that branch, because the worktree does not have it.
  • @storybook/addon-mcp logs a "Skipping composed ref" warning at startup for each branch. It keeps working, and storyhub's MCP endpoint covers branches.
  • The sidebar is reordered visually. Keyboard focus order follows Storybook's DOM order, which puts Common first.

Contributing

pnpm install
pnpm lint           # oxlint, warnings fail the run (pnpm lint:fix applies safe fixes)
pnpm test           # unit tests against a generated fixture repo with real worktrees
pnpm test:e2e       # builds, runs a real Storybook dev server, drives it with Playwright and the MCP SDK client
pnpm fixture        # generate the fixture repo to explore by hand
pnpm screenshots    # regenerate the README screenshots in docs/images from a demo design system

This repo's own installs refuse package versions published less than 7 days ago and always save exact versions (see pnpm-workspace.yaml).

Releasing

npm run release              # or: pnpm release
npm run release -- --full    # also run the browser E2E suite first
npm run release -- --dry-run # walk through every step without changing anything

It checks you are on an up-to-date main and logged in to npm, offers git commit -p for any pending changes, runs the linter, typecheck and unit tests, asks for patch, minor or major, drafts the CHANGELOG.md entry from commit subjects since the last release tag (you can edit it), then bumps the version, commits, tags, pushes and runs pnpm publish. Nothing changes until you confirm the plan. If your npm account uses two-factor auth, pnpm prompts for the code.

The script is called release, not publish, because pnpm publish runs a script named publish itself.

License

MIT