pl-claude-settings

Shareable global Claude Code settings (~/.claude/) — agents, skills, hooks, rules, statuslines — distributed as an npm CLI (plcc).

CK version:

• CLI Version: 4.3.1
• Global Kit Version: [email protected]

Project Goal

Sync my personal ~/.claude/ configuration across machines (and share it publicly) without leaking any sensitive information.

What is intentionally excluded from the repository:

| Type | Where it goes | How | |------|---------------|-----| | API keys (Gemini, OpenAI, Anthropic, Context7, ClaudeKit, …) | .claude/.env | .gitignore'd; shape in .env.example | | Personal hooks (Telegram bot token, Discord webhook, Slack URL, …) | .claude/.env | .gitignore'd; shape in .env.example | | MCP server credentials (Jira/Confluence tokens, etc.) | .claude/.mcp.json | .gitignore'd; shape in .mcp.json.example | | Machine-local overrides | *.local.json | .gitignore'd | | In-flight plans / workspaces | plans/ | .gitignore'd |

The committed settings.json ships with an empty mcpServers: {} block — local MCP servers live in .mcp.json and never enter the repo.

Prerequisites

This tool clones a private GitHub repository. You need the GitHub CLI authenticated:

# Install gh CLI (if not already installed)
brew install gh          # macOS
# or: https://cli.github.com/ for other platforms

# Authenticate with GitHub
gh auth login

# Verify access
gh auth status

Without gh CLI, the tool falls back to git clone which requires SSH keys or a personal access token configured for the private repo.

Installation

# Using bun
bun add -g pl-claude-settings

# Using npm
npm install -g pl-claude-settings

# Using pnpm
pnpm add -g pl-claude-settings

Commands

plcc init

Install .claude settings from repository.

plcc init                # Install to ./.claude/ (current directory)
plcc init -g             # Install to ~/.claude/ (global)
plcc init --force        # Overwrite all files including protected ones
plcc init --full         # Also install Python dependencies
plcc init --branch dev   # Use specific branch

plcc update

Update settings to latest version.

plcc update              # Pull latest and merge changes
plcc update --full       # Also install Python dependencies
plcc update --dry-run    # Preview changes without applying
plcc update --branch dev # Update from specific branch

plcc doctor

Health check for .claude installation.

plcc doctor

Checks: installation manifest, .claude/ directory, git, gh CLI auth, hooks, Python venv, settings.json validity.

plcc config

View and edit .ck.json configuration.

plcc config              # List all settings
plcc config list         # Same as above
plcc config get docs.maxLoc       # Get a value (dot-notation)
plcc config set docs.maxLoc 1000  # Set a value

File Categories

During init and update, files are handled by category:

| Category | Behavior | Examples | |----------|----------|---------| | Managed | Always overwritten | hooks/, skills/, rules/, agents/, scripts/, settings.json | | Protected | Never overwritten if exists | .env, settings.local.json, .mcp.json | | Ignored | Never copied | .git/, node_modules/, .venv/ |

After install, copy .env.example → .env and .mcp.json.example → .mcp.json and fill in your own secrets.

Release Workflow

Global settings releases start from the live ~/.claude directory, but that directory is not safe to commit directly. Use the sanitizer-driven Make targets so protected files, local state, caches, and plugin clones are excluded before any branch or PR is created.

make sync-global-settings-dry-run
make sync-global-settings
make set-release-version VERSION=x.y.z
make validate-release-safety
make prepare-release-pr VERSION=x.y.z
make publish-release VERSION=x.y.z

• make sync-global-settings-dry-run previews copied, skipped, removed, and sanitized paths without changing the repo.
• make sync-global-settings copies from CLAUDE_HOME (default: $(HOME)/.claude) into repo .claude/, removes denied target paths, and forces .claude/settings.json mcpServers to {}.
• make set-release-version VERSION=x.y.z updates cli/package.json to the release version; prepare-release-pr calls this automatically after its clean-worktree guard passes.
• make validate-release-safety runs sanitizer tests, checks committable paths for protected files, verifies README sync, then runs CLI typecheck, tests, and build.
• make prepare-release-pr VERSION=x.y.z requires a clean worktree, creates release/global-settings-vx.y.z, syncs settings, bumps cli/package.json, validates, commits, pushes, and opens a GitHub PR.
• make publish-release VERSION=x.y.z is explicit and separate; it reruns validation and publishes from cli/.

What's Included

• 14 agent configurations
• 70+ skills
• 18 hooks (session-init, privacy-block, notification router, …)
• 5 rule sets (development, orchestration, documentation, …)
• Statusline scripts (cjs, sh, ps1)
• Utility scripts

Security

Never commit secrets to this repository. Before pushing:

• Verify .claude/settings.json has no inline tokens (the mcpServers block must stay empty — put real MCP configs in the gitignored .claude/.mcp.json).
• Verify no .env, .env.* (other than .env.example), *.local.json, or .mcp.json is staged.
• Hook scripts must read secrets from environment variables only — never hard-code Telegram bot tokens, Discord webhooks, or API keys.

If you accidentally commit a secret, rotate it immediately — the value is in git history even after a follow-up commit removes it.

Development

cd cli
bun install
bun run dev -- --help    # Run CLI in dev mode
bun test                 # Run tests
bun run build            # Build for distribution

License

MIT