Skip to content

INSTALLING.md

Latest commit

 

History

History
346 lines (249 loc) · 7.93 KB

INSTALLING.md

File metadata and controls

346 lines (249 loc) · 7.93 KB

Installing schlock

The straight-forward installation guide. No fluff.

Prerequisites

  • Claude Code installed and running
  • Git (for GitHub marketplace)
  • Trust enabled for your repositories (for team installation)

That's it. No Python environment needed—schlock is a Claude Code plugin with vendored dependencies.

Individual Installation

Install schlock for your personal use across all projects.

Method 1: Quick Install (Recommended)

# Add the GitHub marketplace
/plugin marketplace add 27Bslash6/schlock

# Install the plugin
/plugin install schlock@schlock

# Run setup wizard
/schlock:setup

What just happened:

  1. Added 27Bslash6/schlock GitHub repo as a plugin marketplace
  2. Installed schlock from that marketplace
  3. Setup wizard configures advertising blocker and creates .claude/hooks/schlock-config.yaml

Method 2: Interactive Install

# Add the marketplace
/plugin marketplace add 27Bslash6/schlock

# Open plugin browser
/plugin

# Select "Browse Plugins" → find schlock → install

Then run /schlock:setup to configure.

Verify Installation

# Check available commands (should see /schlock:setup, /schlock:validate)
/help

# Check plugin status
/plugin
# → "Manage Plugins" → schlock should be listed and enabled

File created:

  • .claude/hooks/schlock-config.yaml (after running setup wizard)

What's working:

  • Safety validation (always on, automatic)
  • Audit logging (always on, automatic)
  • Advertising blocker (if enabled in wizard)

Team Installation

Ensure all team members get schlock automatically when they trust your repository.

Step 1: Configure Repository

Add to .claude/settings.json in your repository root:

{
  "extraKnownMarketplaces": {
    "schlock": {
      "source": {
        "source": "github",
        "repo": "27Bslash6/schlock"
      }
    }
  },
  "plugins": {
    "schlock@schlock": {
      "enabled": true
    }
  }
}

What this does:

  • extraKnownMarketplaces: Makes the schlock marketplace available
  • plugins: Automatically installs and enables schlock when repo is trusted

Step 2: Commit Settings

git add .claude/settings.json
git commit -m "Add schlock plugin for team"
git push

Step 3: Team Members Trust Repository

When team members clone/pull your repository:

  1. Claude Code prompts: "Do you trust this repository folder?"
  2. They click: "Trust folder"
  3. Automatic install: Claude Code installs schlock marketplace and plugin
  4. Run setup: Team members run /schlock:setup to configure preferences

Important: Each team member still runs /schlock:setup individually to set their preferences (e.g., advertising blocker on/off).

Optional: Shared Configuration

To enforce team-wide settings, commit .claude/hooks/schlock-config.yaml:

# Generate config via wizard
/schlock:setup

# Commit shared config
git add .claude/hooks/schlock-config.yaml
git commit -m "Add team schlock configuration"
git push

Team members inherit this config but can override in ~/.config/schlock/config.yaml.

Configuration Hierarchy

Schlock uses a three-layer configuration system (highest priority last):

  1. Plugin defaults: data/safety_rules.yaml (read-only, shipped with plugin)
  2. User overrides: ~/.config/schlock/config.yaml (personal preferences)
  3. Project overrides: .claude/hooks/schlock-config.yaml (per-project, shared with team)

Example workflow:

  • Plugin ships with advertising blocker enabled
  • User disables it globally in ~/.config/schlock/config.yaml
  • Project requires it in .claude/hooks/schlock-config.yaml (takes precedence)

See CONFIGURATION.md for advanced configuration options.

Post-Installation

Run Setup Wizard

/schlock:setup

Wizard configures:

  • Advertising blocker (enable/disable)
  • Generates .claude/hooks/schlock-config.yaml
  • Backs up previous config (if exists)

Wizard output:

# Auto-generated by /schlock:setup wizard
_metadata:
  generated_at: "2025-12-01T12:00:00Z"
  wizard_version: "0.2.1"
  last_modified_by: "setup-wizard"

commit_filter:
  enabled: true
  rules:
    advertising:
      enabled: true  # or false, based on your choice

Reconfigure Anytime

Re-run /schlock:setup to change settings. Previous config is backed up automatically:

  • Backup location: .claude/hooks/schlock-config.yaml.backup.YYYYMMDDTHHMMSS

Verification Checklist

After installation, verify schlock is working:

  • /help shows /schlock:setup and /schlock:validate commands
  • /plugin shows schlock as enabled
  • .claude/hooks/schlock-config.yaml exists (after wizard)
  • Test blocked command: Claude should refuse Bash(rm -rf /)
  • Audit log created: ~/.config/schlock/audit.jsonl exists after command validation
  • (If enabled) Advertising blocker works: Try committing with "Generated with Claude Code" in message

Troubleshooting

Plugin doesn't show up after installation

Check marketplace:

/plugin marketplace list
# Should see "schlock" (from 27Bslash6/schlock)

Re-add marketplace:

/plugin marketplace remove schlock
/plugin marketplace add 27Bslash6/schlock
/plugin install schlock@schlock

Commands not available

Verify plugin is enabled:

/plugin
# → "Manage Plugins" → check schlock status

Enable if disabled:

/plugin enable schlock@schlock

Setup wizard fails

Check directory permissions:

# Ensure .claude/hooks/ is writable
mkdir -p .claude/hooks
ls -la .claude/hooks/

Manual config: Create .claude/hooks/schlock-config.yaml manually:

_metadata:
  generated_at: "2025-12-01T12:00:00Z"
  wizard_version: "0.2.1"
  last_modified_by: "manual"

commit_filter:
  enabled: true
  rules:
    advertising:
      enabled: true

Team installation not automatic

Check .claude/settings.json syntax:

# Validate JSON
python -m json.tool .claude/settings.json

Ensure repository is trusted:

  • Claude Code must prompt to trust the repository
  • If already trusted, try closing/reopening the folder
  • Check Claude Code logs for trust-related errors

Validation not blocking commands

Check hook is registered:

# Verify hooks/pre_tool_use.py exists in plugin directory
/plugin
# → "Manage Plugins" → schlock → check hooks

Check audit log:

# Should show validation attempts
cat ~/.config/schlock/audit.jsonl

If empty, hook isn't running. File a bug at: https://github.com/27Bslash6/schlock/issues

Uninstallation

Remove Plugin

/plugin uninstall schlock@schlock

What's removed:

  • Plugin files from Claude Code
  • Slash commands (/schlock:setup, /schlock:validate)
  • Hooks (no more safety validation)

What's kept:

  • Configuration files: .claude/hooks/schlock-config.yaml, ~/.config/schlock/config.yaml
  • Audit logs: ~/.config/schlock/audit.jsonl

Clean Configuration

# Remove project config
rm .claude/hooks/schlock-config.yaml
rm .claude/hooks/schlock-config.yaml.backup.*

# Remove user config (optional)
rm ~/.config/schlock/config.yaml

# Remove audit logs (optional)
rm ~/.config/schlock/audit.jsonl

Remove Marketplace

/plugin marketplace remove schlock

Next Steps

After installation:

  1. Configure preferences: Run /schlock:setup
  2. Test blocking: Try Bash(rm -rf /) (Claude should refuse)
  3. Review rules: Check data/safety_rules.yaml for all 40 security rules
  4. Customize: See CONFIGURATION.md for advanced options
  5. Share with team: Add to .claude/settings.json for automatic team installation

Support