Skip to main content

Install the bewith plugin

What this runbook does: sets up Claude Code to load the bewith plugin from the bewith-dev/bewith-docs GitHub marketplace, so every Claude Code session in every repo on your machine sees the platform's agents, skills, commands, hooks, and policies. One-time per developer — not per repo.

Always-latest: the plugin carries no explicit version, so Claude Code tracks the repo's latest commit (the git SHA is the version) and auto-updates at session start. You install once and never manually bump (see consumption-model.md, INS-2).

When to use:

  • First-time install on a new machine.
  • Re-install after wiping ~/.claude/ or switching machines.

Per-developer vs per-repo. This runbook is the per-developer machine setup (the plugin + the git hooks + the token). Putting a repo on the platform (its CLAUDE.md, the CI caller, retiring .cursor) is a separate, per-repo procedure — the repo-migration runbook, automated by /claude-init.

Prerequisites​

  • macOS or Linux. Windows is not supported yet — the plugin's root component directories are git symlinks that don't materialize on Windows without Developer Mode, so the plugin would load with no components.
  • Claude Code installed and running.
  • Git access to the private bewith-dev/bewith-docs repo — gh auth login done, or an SSH key / credential helper that can clone it.

Procedure​

Fast path (recommended). If you have the bewith CLI, just run bewith platform install — it does steps 1–2 (registers the marketplace, enables the plugin), sets the capability status line, and checks for the token, backing up your ~/.claude/settings.json first. The permission allowlist is not applied automatically — run bewith platform permissions to review and opt in (it prints the rules and asks before writing). Then restart Claude Code. The steps below are the under-the-hood reference and the fallback if you don't have the CLI yet.

The one thing the CLI can't do for you is set the token in step 3 — it never edits your dotfiles. It prints the same gh-backed one-liner shown there for you to add.

1. Add the GitHub marketplace​

claude plugin marketplace add bewith-dev/bewith-docs

This clones the repo and reads .claude-plugin/marketplace.json, which declares one plugin — bewith, source: "./" (the whole repo). You'll see Successfully added marketplace: bewith-dev.

2. Install the plugin​

claude plugin install bewith@bewith-dev

Installs at user scope by default — the plugin loads in every Claude Code session in every project, which is what you want for a team-wide platform. (claude plugin install bewith@bewith-dev --scope project would scope it to one repo; only for piloting.)

3. Enable startup auto-update for the private repo​

Because bewith-docs is private, the background auto-update that runs at session start needs a token in the environment — it can't use interactive git prompts. Interactive add/install/update use your git credentials; the startup refresh does not. Add to your shell profile (~/.zshrc):

export GH_TOKEN="$(gh auth token 2>/dev/null)"   # derived from gh's keychain — no literal secret in the file

(GITHUB_TOKEN works too.) Without this, the plugin still installs and updates manually, but it won't silently pick up new commits at startup. Reload your shell (exec zsh) after adding it.

4. Restart Claude Code​

Restart so the plugin's hooks and slash commands register. (claude plugin update changes also say "Restart to apply changes.")

Verification​

claude plugin list                 # bewith@bewith-dev — enabled
cd /tmp && claude plugin details bewith   # run OUTSIDE bewith-docs (see note)

details should show the real component inventory — Agents (26), Skills, Commands, Hooks (7) — and no README/index/_template entries. In a session, confirm a few artifacts resolve: /share-rule, /new-artifact, @code-reviewer, @process-guardian.

Run details from outside bewith-docs. Inside the platform repo, Claude Code reads .claude/ as the project's own config, which masks the installed-plugin view.

Updating​

Automatic (default). With GH_TOKEN set (step 3), each session start pulls the latest commit. Every merge to master reaches you on your next session — no command, no version bump.

Manual (when you want it now):

claude plugin update bewith@bewith-dev   # the @marketplace qualifier is REQUIRED

A bare claude plugin update bewith reports Plugin "bewith" not found — always include @bewith-dev. The command prints the SHA it moved to (e.g. updated from 0.1.1 to eb317f03e536); restart to apply.

Uninstall​

claude plugin uninstall bewith
claude plugin marketplace remove bewith-dev

Platform developers — testing local changes before merge​

If you develop the plugin itself in a local bewith-docs clone, two facts matter:

  • Inside bewith-docs, Claude Code auto-loads .claude/ as project config (agents/skills/commands/rules from your working tree, live) — and since PR #161 the repo no longer wires hooks in .claude/settings.json, so it dogfoods the plugin's hooks. Your working-tree edits to agents/skills/commands are live here; hook edits are not live until the plugin updates.
  • To test a working-tree change as the plugin (e.g. before merge, or to see it in other repos), register a directory marketplace instead of the GitHub one: 
    claude plugin marketplace remove bewith-dev
    claude plugin marketplace add /Users/<you>/workspace/bewith-docs
    claude plugin marketplace update bewith-dev   # re-reads the working tree
    claude plugin uninstall bewith && claude plugin install bewith@bewith-dev
    A directory source does not auto-update; refresh it with marketplace update + reinstall. Switch back to claude plugin marketplace add bewith-dev/bewith-docs for always-latest.

Troubleshooting​

SymptomCauseFix
Marketplace not foundRepo not accessiblegh auth login; confirm access to bewith-dev/bewith-docs
Plugin not found: bewith on updateMissing marketplace qualifierUse claude plugin update bewith@bewith-dev
New commits don't show up at startupGH_TOKEN/GITHUB_TOKEN not in the environment (private repo)Step 3, then reload your shell
details shows no/odd componentsRun inside bewith-docsRun from /tmp or another repo
Slash command from plugin doesn't showAutocomplete cache staleRestart Claude Code

Pointers​