ccshelf

module

v0.1.0 Latest Latest Go to latest Published: Oct 7, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/yorch/ccshelf

Links

Open Source Insights

README ¶

ccshelf

Profiles and a plugin catalog for Claude Code. Unofficial: not affiliated with Anthropic.

Status: implemented and under adversarial review; not yet released. The launcher, catalog, Action and starter template build for all six targets; tests pass on macOS and Linux, and Windows runs in CI and is best-effort until proven; Phase 0 evidence items (routing eval, adopt-or-build, bundle prototype, Linux/Windows runs) are still open, see the roadmap. Start with docs/README.md and the decision log. The interactive report is docs/report.html, generated from the Markdown.

Install

Not released yet. From source (Go 1.27 or newer):

go install github.com/yorch/ccshelf/cmd/ccshelf@latest   # module path is provisional
ccshelf --version

Releases will ship signed archives for macOS, Linux and Windows (amd64 and arm64) and a reusable GitHub Action (action/).

Use

A profile is a named recipe of plugins, standalone skills and MCP servers. ccshelf run starts claude with exactly that set, so each terminal can run a different one.

ccshelf new sre-night --from base --plugin sre-kit@acme   # create a personal profile
ccshelf ls                                                # list profiles from every source
ccshelf show sre-night                                    # resolved plugins, MCP servers, trust closure
ccshelf dry-run sre-night                                 # print the exact claude command, run nothing
ccshelf run sre-night                                     # start claude with the profile
ccshelf run --account personal sre-night --resume         # ccshelf flags first, then claude's

Every command works with flags alone; on a terminal, missing values are asked for and the equivalent command is printed. Profiles from a shared source (a git repo of your organization) must be trusted first: ccshelf trust <profile> shows what the profile does, and nothing is ever accepted automatically (--yes does not accept trust). Exit codes: 0 ok, 1 failure, 2 usage, 3 policy, 4 trust required, 130 interrupted.

For organizations, ccshelf lint, compile, catalog build, search, recommend and doctor work on the org data repo (see examples/org-data-repo for a starter template). The design is in docs/.

The project website (static; the /docs pages are generated from the Markdown at build time) lives in site/; it is checked by make site-check and is deployed to GitHub Pages only by hand (.github/workflows/pages.yml, see site/README.md).

Licensed under the MIT License.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
ccshelf command Command ccshelf runs Claude Code with a named profile and lints and publishes an organization's plugin catalog.	Command ccshelf runs Claude Code with a named profile and lints and publishes an organization's plugin catalog.
internal
account Package account manages named Claude Code accounts: a name that maps to a separate CLAUDE_CONFIG_DIR (launcher.md, "Combining profiles with accounts", way 2).	Package account manages named Claude Code accounts: a name that maps to a separate CLAUDE_CONFIG_DIR (launcher.md, "Combining profiles with accounts", way 2).
analytics Package analytics reads optional plugin usage data.	Package analytics reads optional plugin usage data.
bundles Package bundles compiles resolved profiles into generated profile bundles: dependency-only plugins that let a profile's plugins install natively from the org's marketplace (decision D-17).	Package bundles compiles resolved profiles into generated profile bundles: dependency-only plugins that let a profile's plugins install natively from the org's marketplace (decision D-17).
cache Package cache manages the launcher's private cache directory and the content-addressed files in it (security requirement SR4).	Package cache manages the launcher's private cache directory and the content-addressed files in it (security requirement SR4).
catalog Package catalog builds the plugin catalog of an org data repo: a merged, sanitized, deterministic view of the marketplace entries, their sidecar metadata, what inspecting the plugin directories found, and optional git history, plus renderers (catalog.json, CATALOG.md) and a text search.	Package catalog builds the plugin catalog of an org data repo: a merged, sanitized, deterministic view of the marketplace entries, their sidecar metadata, what inspecting the plugin directories found, and optional git history, plus renderers (catalog.json, CATALOG.md) and a text search.
catalog/catalogtest Package catalogtest holds helpers shared by the tests of the catalog packages: the fictional org data repo fixture and small file helpers.	Package catalogtest holds helpers shared by the tests of the catalog packages: the fictional org data repo fixture and small file helpers.
catalog/codeowners Package codeowners parses CODEOWNERS files and answers "who owns this path" with GitHub's semantics.	Package codeowners parses CODEOWNERS files and answers "who owns this path" with GitHub's semantics.
catalog/gitdata Package gitdata collects optional history data for the catalog by running the user's git: the last commit date and the number of distinct authors of each plugin directory, the latest tag, and which plugin directories changed since a tag.	Package gitdata collects optional history data for the catalog by running the user's git: the last commit date and the number of distinct authors of each plugin directory, the latest tag, and which plugin directories changed since a tag.
catalog/lint Package lint checks an org data repo against the catalog rules and reports stable, sorted findings.	Package lint checks an org data repo against the catalog rules and reports stable, sorted findings.
catalog/safepath Package safepath confines file access to a repository root.	Package safepath confines file access to a repository root.
catalog/sidecar Package sidecar reads the catalog-only metadata of plugins: one TOML sidecar file per plugin (catalog/plugins/<name>.toml), or, in single-file mode, the free-form "metadata" object of each marketplace entry, and the taxonomy file (catalog/taxonomy.toml).	Package sidecar reads the catalog-only metadata of plugins: one TOML sidecar file per plugin (catalog/plugins/<name>.toml), or, in single-file mode, the free-form "metadata" object of each marketplace entry, and the taxonomy file (catalog/taxonomy.toml).
catalog/site Package site writes the static catalog site: four plain files that a web server, GitHub Pages or an internal static host can serve as they are.	Package site writes the static catalog site: four plain files that a web server, GitHub Pages or an internal static host can serve as they are.
claude Package claude is everything ccshelf needs from the claude binary: finding it, asking it questions, parsing what it prints, and starting it.	Package claude is everything ccshelf needs from the claude binary: finding it, asking it questions, parsing what it prints, and starting it.
cli Package cli assembles the ccshelf command tree: the global flags, the launcher commands and the org and catalog commands.	Package cli assembles the ccshelf command tree: the global flags, the launcher commands and the org and catalog commands.
cli/clicore Package clicore holds the small, dependency-light pieces every ccshelf command shares: the global flags, the environment a command may touch, and the per-invocation Context that carries the terminal mode and the prompter.	Package clicore holds the small, dependency-light pieces every ccshelf command shares: the global flags, the environment a command may touch, and the per-invocation Context that carries the terminal mode and the prompter.
cli/launcher Package launcher implements the launcher commands of ccshelf: run, dry-run, show, ls, diff, new, edit, init, trust, account, shell-init, version and completion.	Package launcher implements the launcher commands of ccshelf: run, dry-run, show, ls, diff, new, edit, init, trust, account, shell-init, version and completion.
cli/orgcmd Package orgcmd implements the org and catalog commands of the ccshelf CLI: lint, compile, catalog build, search, recommend and doctor.	Package orgcmd implements the org and catalog commands of the ccshelf CLI: lint, compile, catalog build, search, recommend and doctor.
config Package config loads, validates and saves the user's ccshelf configuration file (config.toml) and resolves which Claude Code account a run uses.	Package config loads, validates and saves the user's ccshelf configuration file (config.toml) and resolves which Claude Code account a run uses.
config/tomlkeys Package tomlkeys closes a gap in the TOML decoder: go-toml matches struct tags case-insensitively, so "Inherit_User_Settings = false" written after "inherit_user_settings = true" would silently override it and a reviewer reading the file would see two different spellings of one setting.	Package tomlkeys closes a gap in the TOML decoder: go-toml matches struct tags case-insensitively, so "Inherit_User_Settings = false" written after "inherit_user_settings = true" would silently override it and a reviewer reading the file would see two different spellings of one setting.
doctor Package doctor analyzes an org's catalog, profiles and installed plugins and returns findings.	Package doctor analyzes an org's catalog, profiles and installed plugins and returns findings.
e2e Package e2e holds end-to-end tests of the real ccshelf binary.	Package e2e holds end-to-end tests of the real ccshelf binary.
envpolicy Package envpolicy decides which environment variable names a profile may set for a Claude Code session (security requirement SR1).	Package envpolicy decides which environment variable names a profile may set for a Claude Code session (security requirement SR1).
marketplace Package marketplace reads a Claude Code plugin marketplace repository without running the claude binary.	Package marketplace reads a Claude Code plugin marketplace repository without running the claude binary.
orgconfig Package orgconfig reads ccshelf.toml, the org config at the root of an organization's data repo.	Package orgconfig reads ccshelf.toml, the org config at the root of an organization's data repo.
policy Package policy detects Claude Code managed policy on this machine and turns it into a capability matrix for the launcher (requirement R3, decision D-06).	Package policy detects Claude Code managed policy on this machine and turns it into a capability matrix for the launcher (requirement R3, decision D-06).
profile Package profile parses profile manifests, resolves them across sources and computes the trust closure (SR1 to SR3).	Package profile parses profile manifests, resolves them across sources and computes the trust closure (SR1 to SR3).
profile/gitsource Package gitsource provides a profile.Source backed by a pinned git repository: the shared "org data repo" that holds profiles/, mcp/registry.toml and prompts/ (security requirements SR2 and SR4).	Package gitsource provides a profile.Source backed by a pinned git repository: the shared "org data repo" that holds profiles/, mcp/registry.toml and prompts/ (security requirements SR2 and SR4).
profile/pluginsource Package pluginsource provides a profile.Source that reads profiles from a Claude Code plugin that is already installed: the "data-only plugin" way of shipping an org's profiles.	Package pluginsource provides a profile.Source that reads profiles from a Claude Code plugin that is already installed: the "data-only plugin" way of shipping an org's profiles.
recommend Package recommend suggests plugins and profiles for a directory.	Package recommend suggests plugins and profiles for a directory.
settings Package settings generates and validates the --settings JSON that ccshelf hands to Claude Code (security requirement SR1: a closed schema).	Package settings generates and validates the --settings JSON that ccshelf hands to Claude Code (security requirement SR1: a closed schema).
shellinit Package shellinit generates the shell integration printed by "ccshelf shell-init <shell>": one small function per profile that runs "ccshelf run <profile>" with the rest of the command line passed through.	Package shellinit generates the shell integration printed by "ccshelf shell-init <shell>": one small function per profile that runs "ccshelf run <profile>" with the rest of the command line passed through.
testutil Package testutil holds helpers shared by ccshelf's tests: a build of the fake claude (internal/testutil/fakeclaude), an isolated environment that cannot touch the real home directory, and small file helpers.	Package testutil holds helpers shared by ccshelf's tests: a build of the fake claude (internal/testutil/fakeclaude), an isolated environment that cannot touch the real home directory, and small file helpers.
testutil/fakeclaude command Command fakeclaude is a test double of the claude binary, driven by environment variables and files, for ccshelf's tests.	Command fakeclaude is a test double of the claude binary, driven by environment variables and files, for ccshelf's tests.
trust Package trust decides whether a resolved profile may run (SR2): it keeps the trust lockfile, compares a closure with what the user accepted, explains differences in plain words and tracks per-repository trust for project profiles.	Package trust decides whether a resolved profile may run (SR2): it keeps the trust lockfile, compares a closure with what the user accepted, explains differences in plain words and tracks per-repository trust for project profiles.
ui Package ui is the terminal layer of ccshelf: how a command decides whether it may prompt, how it asks, how it prints, and how it exits (requirement R6).	Package ui is the terminal layer of ccshelf: how a command decides whether it may prompt, how it asks, how it prints, and how it exits (requirement R6).
version Package version reports the build identity of the ccshelf binary.	Package version reports the build identity of the ccshelf binary.
schema Package schema embeds the handwritten JSON Schema (draft 2020-12) files for ccshelf's three TOML formats: profile manifests, the user config and the MCP registry.	Package schema embeds the handwritten JSON Schema (draft 2020-12) files for ccshelf's three TOML formats: profile manifests, the user config and the MCP registry.