myfirst-addon/addon.json

{
  "$schema": "https://gitcaddy.com/schemas/addon-manifest.json",

  "_comment_id": "Unique identifier for your addon. Use reverse domain notation.",
  "id": "com.example.myfirst-addon",

  "_comment_name": "Display name shown in the Addon Manager",
  "name": "My First Addon",

  "_comment_version": "Semantic version (major.minor.patch)",
  "version": "1.0.0",

  "_comment_minAppVersion": "Minimum GitCaddy version required",
  "minAppVersion": "0.1.0",

  "_comment_description": "Short description for the addon list",
  "description": "A demo addon showcasing all GitCaddy addon features with detailed examples.",

  "_comment_author": "Author information (shown in addon details)",
  "author": {
    "name": "Your Name",
    "email": "you@example.com",
    "url": "https://example.com"
  },

  "_comment_main": "Path to the main process JavaScript module",
  "main": "main/index.js",

  "_comment_renderer": "Optional: Path to renderer process module for UI components",
  "renderer": "renderer/index.js",

  "_comment_host": "Optional: Native host process configuration (for .NET, Go, Rust, etc.)",
  "_comment_host_note": "Remove this section if your addon is pure JavaScript",

  "_comment_permissions": "Required permissions - user sees these before installing",
  "permissions": [
    "repository:read",
    "repository:write",
    "diff:read",
    "commit:read",
    "branch:read",
    "network:localhost",
    "network:external",
    "settings:store",
    "notifications:show"
  ],

  "_comment_capabilities": "What your addon can do - GitCaddy uses these to find addons",
  "capabilities": [
    "commit-message-generation",
    "repository-analysis",
    "custom-view"
  ],

  "_comment_contributes": "UI elements your addon adds to GitCaddy",
  "contributes": {

    "_comment_toolbarButtons": "Buttons in the main toolbar",
    "toolbarButtons": [
      {
        "id": "my-action-button",
        "tooltip": "My Action Button",
        "_comment_icon": "Use octicon names from https://primer.style/octicons/",
        "icon": { "type": "octicon", "value": "rocket" },
        "_comment_position": "Where to place: start, end, after-push-pull, after-branch",
        "position": "after-push-pull",
        "_comment_onClick": "Action when clicked",
        "onClick": {
          "_comment_action_options": "show-view, invoke-method, open-url",
          "action": "show-view",
          "target": "demo-view"
        },
        "_comment_badge": "Optional: Show a badge with dynamic content",
        "badge": {
          "method": "getBadgeContent"
        }
      },
      {
        "id": "quick-action",
        "tooltip": "Quick Action (invokes method directly)",
        "icon": { "type": "octicon", "value": "zap" },
        "position": "end",
        "onClick": {
          "action": "invoke-method",
          "method": "quickAction",
          "args": ["arg1", "arg2"]
        }
      }
    ],

    "_comment_menuItems": "Items added to GitCaddy menus",
    "menuItems": [
      {
        "id": "my-menu-item",
        "menu": "repository",
        "label": "My Addon Action",
        "accelerator": "CmdOrCtrl+Shift+M",
        "onClick": {
          "action": "invoke-method",
          "method": "menuAction"
        }
      }
    ],

    "_comment_repositoryViews": "Custom views shown in the repository panel",
    "repositoryViews": [
      {
        "id": "demo-view",
        "title": "Demo View",
        "icon": "rocket",
        "_comment_renderer_type": "iframe loads HTML, react uses React component",
        "renderer": {
          "type": "iframe",
          "source": "views/demo.html"
        },
        "_comment_context": "When to show: repository, diff, commit, always",
        "context": ["repository"]
      }
    ],

    "_comment_settings": "Settings panel for your addon",
    "settings": {
      "id": "settings",
      "title": "My First Addon Settings",
      "renderer": {
        "type": "iframe",
        "source": "views/settings.html"
      }
    },

    "_comment_settingsDefinitions": "Define settings schema for validation and defaults",
    "settingsDefinitions": [
      {
        "key": "enableFeature",
        "type": "boolean",
        "default": true,
        "description": "Enable the main feature"
      },
      {
        "key": "apiKey",
        "type": "string",
        "default": "",
        "description": "API key for external service"
      },
      {
        "key": "mode",
        "type": "select",
        "default": "normal",
        "description": "Operating mode",
        "options": [
          { "label": "Normal", "value": "normal" },
          { "label": "Advanced", "value": "advanced" },
          { "label": "Debug", "value": "debug" }
        ]
      },
      {
        "key": "maxItems",
        "type": "number",
        "default": 10,
        "description": "Maximum items to process"
      }
    ],

    "_comment_contextMenuItems": "Items added to right-click context menus",
    "contextMenuItems": [
      {
        "id": "file-context-action",
        "context": "file-list",
        "label": "Process with My Addon",
        "onClick": {
          "action": "invoke-method",
          "method": "processFiles"
        }
      },
      {
        "id": "commit-context-action",
        "context": "commit-list",
        "label": "Analyze Commit",
        "onClick": {
          "action": "invoke-method",
          "method": "analyzeCommit"
        }
      }
    ]
  }
}