Plugins allow you to extend and modify Hugsy configurations dynamically. They can add permissions, environment variables, hooks, and more to your Claude Code setup.

Using Plugins

Plugins are specified in your .hugsyrc.json file. You can use local plugins or published npm packages:

{
  "extends": "@hugsylabs/hugsy-compiler/presets/development",
  "plugins": [
    "./plugins/my-custom-plugin.js",
    "./plugins/auto-format.js"
  ]
}

Plugin Loading Order

Plugins are loaded and applied in the order they appear in the configuration. Each plugin receives the config transformed by previous plugins.

Creating a Plugin

A Hugsy plugin is a JavaScript module that exports an object with a transform function:

/**
 * Example Hugsy Plugin
 * Adds custom permissions and hooks to your configuration
 */
const myPlugin = {
  name: 'my-custom-plugin',
  description: 'Adds custom development tools support',
  
  transform(config) {
    // Add custom permissions
    config.permissions = config.permissions || {};
    config.permissions.allow = config.permissions.allow || [];
    config.permissions.allow.push(
      'Bash(docker *)',
      'Bash(kubectl *)',
      'Write(**/*.test.js)'
    );
    
    // Add environment variables
    config.env = config.env || {};
    config.env.PLUGIN_ENABLED = 'true';
    config.env.ENVIRONMENT = 'development';
    
    // Add hooks for monitoring
    config.hooks = config.hooks || {};
    config.hooks['PreToolUse'] = config.hooks['PreToolUse'] || [];
    config.hooks['PreToolUse'].push({
      matcher: 'Write(**)',
      command: 'echo "File modification detected"'
    });
    
    return config;
  }
};

export default myPlugin;

Plugin Structure

  • name: Unique identifier for your plugin
  • description: Brief explanation of what the plugin does
  • transform(config): Function that modifies and returns the configuration

What Plugins Can Do

Add Permissions

Control which operations Claude Code can perform:

config.permissions.allow.push('Bash(npm run *)');
config.permissions.deny.push('Write(**/production/**)');

Set Environment Variables

Add environment variables to Claude Code sessions:

config.env.NODE_ENV = 'development';
config.env.API_URL = 'https://api.example.com';

Configure Hooks

Add hooks to monitor and react to Claude Code actions:

config.hooks['PreToolUse'].push({
  matcher: 'Bash(git commit *)',
  command: 'npm run pre-commit'
});

Add Slash Commands

Include slash command presets or custom commands:

config.commands = config.commands || {};
config.commands.presets = ['@hugsylabs/hugsy-compiler/presets/slash-commands-common'];

Publishing Plugins

To share your plugin with the community, publish it as an npm package:

  1. Create a package with your plugin code
  2. Add hugsy-plugin keyword to package.json
  3. Export your plugin as the default export
  4. Publish to npm with a scope (e.g., @yourname/hugsy-plugin-name)

Best Practices

  • Always check if config properties exist before modifying them
  • Use descriptive names for your plugins
  • Document what your plugin does and why
  • Test your plugin with different configurations
  • Consider making your plugin configurable through options