Statusline Configuration Skill

CRITICAL INSTRUCTIONS

You MUST follow the workflow below EXACTLY as written. The workflow uses a conversational approach:

1. Show current state (what’s already enabled)
2. Show available components
3. Ask what to change
4. Interpret natural language responses (enable/disable/add/remove)

Example Interaction

User: “Help me configure the global statusline”

Your actions:

1. Run discovery script to find all components
2. Determine scope (global – user specified)
3. Read current config to show what’s already enabled
4. Display current state and available components
5. Ask: “Which components would you like to enable or disable?”
6. Parse user’s response (e.g., “Enable version, disable model”)
7. Write updated config
8. Tell user where config was saved and that they need to restart

Understanding User Intent

The conversational approach allows users to express changes naturally. Understand these patterns:

Incremental changes (most common when current state is shown):

• “Enable X” → Add X to enabled, keep others as-is
• “Disable Y” → Remove Y from enabled, keep others as-is
• “Add X and remove Y” → Do both operations
• “Turn on X, turn off Y” → Same as above

Absolute state (replace everything):

• “Just X and Y” → Enable only these, disable all others
• “Only X” → Enable just this one, disable all others

Flexible naming:

• User might say “model” instead of “builtin:model”
• User might say “git branch” instead of “builtin:git-branch”
• Match intelligently, ask for clarification if ambiguous

The key insight: by showing what’s currently enabled, users naturally think in terms of deltas (what to add/remove) rather than absolute state.

Configuration Workflow

Follow these steps in order. Do not skip steps.

Step 1: Discover All Components

START HERE. This is ALWAYS the first step.

DO NOT read the current config file. DO NOT ask the user what they want to do. Just run the discovery script.

Run the discovery script to find all available components:

${CLAUDE_PLUGIN_ROOT}/skills/configure/scripts/list-components.sh "<workspace-path>"

• If in a workspace, pass the workspace path
• If not in a workspace, omit the workspace argument

The script returns JSON:

{
  "components": [
    {"Namespace": "builtin", "Name": "directory", "Path": "..."},
    {"Namespace": "builtin", "Name": "git-branch", "Path": "..."},
    {"Namespace": "personal", "Name": "my-component", "Path": "..."},
    {"Namespace": "project", "Name": "deployment-env", "Path": "..."}
  ]
}

Parse this JSON to get all discovered components.

Step 2: If User Only Wants to List Components

If the user asked “what components are available?” without wanting to configure, stop here and display the components grouped by namespace:

Built-in components:
- builtin:directory
- builtin:git-branch
- builtin:model

Personal components:
- personal:my-component

Project components:
- project:deployment-env

Do not proceed to configuration.

Step 3: Determine Configuration Scope

If the user is configuring (not just listing), determine the scope:

If user already specified the scope (e.g., “configure global statusline” or “configure project statusline”):

• Use that scope
• Skip to Step 4

If user did NOT specify the scope (e.g., “configure statusline”):

• Ask: “Would you like to configure the statusline globally (for all projects) or just for this project?”
• Wait for user response to determine scope

Step 4: Filter Components by Scope

Based on the chosen scope, determine which components are available:

Global scope:

• Include: builtin, personal, and plugin namespace components
• Exclude: project namespace components
• Rationale: Project components don’t make sense in global config

Project scope:

• Include: ALL components (builtin, personal, plugin, and project)
• Rationale: Project config can enable/disable any component

Create a list of component IDs in the format namespace:name (e.g., builtin:directory).

Step 5: Read Current Configuration

Determine the config file path based on scope:

• Global: ~/.claude/statusline-components/statusline.json
• Project: {workspace}/.claude/statusline-components/statusline.json

Try to read the current config file. If it doesn’t exist or is invalid JSON, treat it as empty config {}.

Parse the add and remove arrays to determine current state.

Step 6: Show Current State and Ask for Changes

Display the current configuration state and available components in a clear, organized way:

Format:

Currently enabled:
- builtin:directory
- builtin:git-branch
- builtin:model

Currently disabled:
- builtin:version

Available components:
- builtin:directory (Show current directory)
- builtin:git-branch (Show git branch)
- builtin:model (Show current model)
- builtin:version (Show plugin version)
- personal:custom-component (Your custom component)

Which components would you like to enable or disable?

Important display rules:

• Group components by current state (enabled/disabled)
• Show all available components with brief descriptions
• If no components are currently enabled/disabled, say “None”
• Make it clear which components are already enabled (to guide incremental changes)

Then wait for the user’s natural language response. They might say things like:

• “Enable version”
• “Disable model”
• “Add version and remove git-branch”
• “Enable version, disable model and directory”
• “Just directory and model” (meaning: only enable these, disable others)

Step 7: Parse User Response

Interpret the user’s natural language response to determine which components to enable and disable.

Parsing guidelines:

1. Look for explicit enable/add keywords:

   • “enable X”, “add X”, “turn on X”, “include X”
   • Extract component names/IDs following these keywords
   • Add these to the enable list

2. Look for explicit disable/remove keywords:

   • “disable X”, “remove X”, “turn off X”, “exclude X”
   • Extract component names/IDs following these keywords
   • Add these to the disable list

3. Handle “only” or “just” patterns:

   • “just X and Y” or “only X and Y”
   • Treat this as: enable only these components, disable all others
   • Set enable list to specified components
   • Set disable list to all other available components

4. Accept partial names:

   • User might say “model” instead of “builtin:model”
   • Match the most appropriate component
   • If ambiguous, ask for clarification

5. Handle conflicts:

   • If same component appears in both enable and disable lists, disable wins
   • Remove from enable list, keep in disable list

6. Empty response:

   • If user doesn’t specify any changes, ask them to clarify what they want to change
   • Or ask if they want to keep current configuration

Example parsing:

User says: “Enable version and disable model”

• Enable list: [“builtin:version”]
• Disable list: [“builtin:model”]

User says: “Just directory and git-branch”

• Enable list: [“builtin:directory”, “builtin:git-branch”]
• Disable list: [“builtin:model”, “builtin:version”] (all others)

Step 8: Write the Configuration File

Determine the correct config file path:

• Global scope: ~/.claude/statusline-components/statusline.json
• Project scope: {workspace}/.claude/statusline-components/statusline.json

Create the directory if it doesn’t exist.

Build the configuration based on parsed changes from Step 7:

{
  "add": [<enabled components>],
  "remove": [<disabled components>]
}

Configuration rules:

1. Merging with existing config:

   • Start with the current add and remove arrays from Step 5
   • Apply the changes from user’s response (Step 7)
   • If user enabled a component: add it to add array, remove from remove array
   • If user disabled a component: add it to remove array, remove from add array

2. Component ordering:

   • Preserve existing order in add array for components that stay enabled
   • Append newly enabled components to end of add array
   • Sort remove array alphabetically for consistency

3. Conflict resolution:

   • If a component appears in both add and remove, disable wins
   • Remove from add and keep in remove

4. Empty config:

   • If both arrays are empty, write {}

5. Scope-specific behavior:

   • Global: add/remove control all projects
   • Project: add/remove are incremental to global config

Write the configuration file.

Step 9: Explain the Result

Tell the user:

1. What changes were made (which components were enabled/disabled)
2. The current statusline configuration
3. The config file location
4. That they need to restart Claude Code for changes to take effect
5. That they can manually edit the JSON file to reorder components (order in add array determines display order)

Example:

Statusline configuration updated:
- Enabled: builtin:version
- Disabled: builtin:model

Current statusline:
- builtin:directory
- builtin:git-branch
- builtin:version

Configuration saved to: ~/.claude/statusline-components/statusline.json

Restart Claude Code for changes to take effect.

To change component order, edit the JSON file and reorder items in the "add" array.

Configuration File Format

Global Config (~/.claude/statusline-components/statusline.json)

{
  "add": [
    "builtin:directory",
    "builtin:git-branch",
    "builtin:model"
  ],
  "remove": [
    "builtin:version"
  ]
}

• add: Components to enable globally (array order = display order)
• remove: Components to disable globally

Project Config ({workspace}/.claude/statusline-components/statusline.json)

{
  "add": [
    "project:deployment-env"
  ],
  "remove": [
    "builtin:model"
  ]
}

• add: Additional components to enable for this project
• remove: Components to disable for this project (even if globally enabled)
• These settings are incremental to global config

How Configuration Works

The statusline plugin processes configuration in this order:

1. Start with all discovered components (or global add if specified)
2. Apply global remove to filter out unwanted components
3. Apply project add to enable additional components
4. Apply project remove to disable specific components
5. Display components in final order

This means:

• Global remove disables components for all projects
• Project add can re-enable globally removed components
• Project remove can disable globally enabled components

Important Notes

• Component IDs use format namespace:name
• Namespaces: builtin, personal, project, or plugin name
• Configuration files must be valid JSON
• Order in add array determines display order
• Changes require restarting Claude Code
• If user specifies same component in both enable and disable, disable wins
• Empty configuration {} means use defaults
• Natural language parsing should be flexible (accept partial names, various phrasings)
• Always show current state before asking for changes (guides incremental updates)
• User can specify absolute state (“just X and Y”) or incremental changes (“enable X, disable Y”)

Error Handling

• If config file doesn’t exist, create it
• If config directory doesn’t exist, create it
• If config file is invalid JSON, report error and ask user if they want to overwrite
• Always validate JSON before writing