claudeup

Manage a Claude Code setup — plugins, MCP servers, skills, CLI tools and the binaries plugins depend on — from a TUI, a CLI, or a committed team manifest.

Install

bun add -g claudeup      # recommended
npm install -g claudeup  # also works

Updates go through claudeup itself, not the package manager:

claudeup update

You get a self-contained binary for your platform (an optionalDependencies package gated on os/cpu). On a platform without a prebuilt binary the launcher falls back to running from source under Bun, so the install still works.

Two ways to use it

Interactive — run claudeup with no arguments for the TUI. Good for exploring what is available and toggling things on one machine.

Declarative — commit a .claude/profiles.json and run claudeup install. Good for making a teammate's machine match yours. This is the team configuration guide.

Commands

claudeup                    Open the interactive TUI

install [profile]           Install a profile's plugins, binaries, skills and
                            env, then activate it. No argument = every profile.
  --check                   Report drift only, write nothing (CI gate)
  --yes, -y                 Skip the confirmation prompt
  --force                   Discard unsynced local edits instead of refusing
profile list                Show every profile; ● marks the active one
profile show <name>         Print a profile's fully resolved closure
profile switch <name>       Repoint the active profile — offline, no reinstall
profile sync                Promote local edits back into .claude/profiles.json
doctor [--fix]              Check binary deps, profile symlinks, conventions

claude [args...]            Check for plugin updates (1h cache), then run claude
  --force, -f               Force the update check
update                      Update claudeup itself
--version, -v               Version + update check
--help, -h                  This list

claudeup doctor exits non-zero when it finds a problem, so it works as a CI check. So does claudeup install --check.

What the TUI covers

| Screen | What it manages | |---|---| | Plugins | Install, enable, disable; shows version changes and newly installed plugins | | Skills | Browse and install skills from configured skill repos | | MCP | Add MCP servers from a curated catalog | | Settings | Claude Code settings, from a catalog of known keys | | Profiles | Saved plugin sets (the TUI's own, older profile concept) | | CLI Tools | Install claudish, mnemex and friends via the right package manager | | Git State | Gitignore conventions and repo hygiene | | Alias | Shell alias + flag management for launching claude |

Navigate with ↑/↓ or j/k, Enter to select, r to refresh, ? for help, q/Escape to go back. Number keys 1–8 jump straight to a screen.

Files claudeup touches

| Path | Owner | What claudeup does | |---|---|---| | .claude/profiles.json | you, committed | reads it; profile sync writes to it | | .claude/_profiles/<name>/ | claudeup, gitignored | generated build output | | .claude/settings.json | Claude Code | in profile mode, a symlink into _profiles/ | | .claude/settings.local.json | you, gitignored | env values collected during install | | .mcp.json | Claude Code | in profile mode, a symlink into _profiles/ | | ~/.claude/plugins/* | Claude Code | never written directly — always via the claude CLI |

claudeup never hand-edits Claude Code's own registries (installed_plugins.json, known_marketplaces.json, the plugin cache). Those go through claude plugin ... so Claude Code stays the single writer.

Development

bun install
bun test                # full suite
bun run typecheck
bun run lint
bun run src/main.tsx    # run from source
bun run build:binaries  # cross-compile all platform binaries + their packages

Tests run per-file isolated in CI (bun run test:ci) because mock.module leaks across files in a shared process.

Do not bump @opentui past 0.1.x. 0.4.x breaks bun build --compile: it resolves tree-sitter workers eagerly, bypassing the OTUI_ASSET_ROOT override, so a bare import "@opentui/core" crashes at import time in the compiled binary. Re-run the compile spike before changing that pin.

Releasing

Tag-driven. .github/workflows/claudeup-release.yml fires on tools/claudeup/v*:

1. verify — install, typecheck, test:ci, version and optional-deps gates
2. binaries — a matrix building each target on its native runner (bun --compile cannot cross-compile in CI because opentui ships a per-platform native library)
3. publish — platform packages first, main package last, so its optionalDependencies already resolve

# bump "version" AND the three optionalDependencies to match
bun run check:optional-deps
git commit -am "feat(claudeup): vX.Y.Z - description"
git tag -a tools/claudeup/vX.Y.Z -m "Release message"
git push origin main --tags

Auth is npm OIDC trusted publishing — the workflow references no secrets. Adding a new platform target needs a one-time manual publish to create the package name (OIDC can only authenticate against a package that already exists); see docs/npm-trusted-publishing-setup.md.

License

MIT