Sidebar Customization

Sidebar Customization

Customize the Alex sidebar tabs for your project — add buttons and tailor workflows to your team's needs.

For full welcome experience customization (loop menu + taglines + identity + North Star in one pass), see the welcome-experience-customization skill.

Quick Reference

Loop Tab Customization

The Loop tab displays workflow buttons organized into collapsible groups. Everything is config-driven.

Config Location

.github/config/loop-menu.json

Minimal Example

{
  "$schema": "../../../heir/.github/config/loop-config.schema.json",
  "version": "1.0",
  "projectType": "generic",
  "projectPhase": "active-development",
  "groups": [
    {
      "id": "my-workflows",
      "label": "My Workflows",
      "icon": "rocket",
      "collapsed": false,
      "buttons": [
        {
          "icon": "lightbulb",
          "label": "Brainstorm",
          "command": "openChat",
          "prompt": "Help me brainstorm ideas for this feature"
        }
      ]
    }
  ]
}

Group Schema

Button Schema

Command Types

Using Prompt Files

For complex prompts, use external .prompt.md files:

{
  "icon": "beaker",
  "label": "Run Tests",
  "command": "openChat",
  "promptFile": "test.prompt.md"
}

The file is loaded from .github/prompts/loop/{promptFile}.

Phase-Based Visibility

Show buttons only during specific project phases:

{
  "icon": "rocket",
  "label": "Release",
  "command": "openChat",
  "prompt": "@alex /release",
  "phase": ["testing", "release"]
}

Live Reload

The sidebar watches loop-menu.json for changes. Save the file and buttons update immediately — no reload needed.

Common Customization Patterns

Add a Project-Specific Button Group

{
  "id": "health-research",
  "label": "Health Research",
  "icon": "heart",
  "accent": "#ef4444",
  "collapsed": false,
  "source": "type",
  "buttons": [
    {
      "icon": "search",
      "label": "Literature Search",
      "command": "openChat",
      "prompt": "@Health Researcher Search for recent studies on {topic}"
    },
    {
      "icon": "note",
      "label": "Summarize Paper",
      "command": "openChat",
      "promptFile": "summarize-paper.prompt.md"
    }
  ]
}

Use Agent Routing in Buttons

Route to specific Alex agents:

{
  "icon": "beaker",
  "label": "Test Plan",
  "command": "openChat",
  "prompt": "@Validator Create a test plan for the current feature"
}

Available agents: @Alex, @Builder, @Researcher, @Validator, @Planner, @Documentarian, @Presenter, @Frontend, @Backend, @Infrastructure, etc.

Limitations

What You CAN Customize

• Loop tab button groups, labels, icons, prompts
• Button visibility by project phase
• Group ordering and collapse state

What You CANNOT Customize

• VS Code Copilot's @ agent dropdown (built-in feature)
• Setup tab contents (core Alex features)
• Health Pulse display format
• Creative Loop button order (always 1-6)

To hide agents from the @ dropdown, delete or rename their .github/agents/*.agent.md files.

Troubleshooting

Loop Tab Issues

Validate Config

The schema is at .github/config/loop-config.schema.json. Most editors provide validation when $schema is set:

{
  "$schema": "./../loop-config.schema.json",
  ...
}