Plugin Settings

Padrão de Plugin Settings para Claude Code Plugins

Visão Geral

Plugins podem armazenar configurações e estado configuráveis pelo usuário em arquivos .claude/plugin-name.local.md dentro do diretório do projeto. Este padrão usa YAML frontmatter para configuração estruturada e conteúdo markdown para prompts ou contexto adicional.

Características principais:

• Localização do arquivo: .claude/plugin-name.local.md na raiz do projeto
• Estrutura: YAML frontmatter + corpo markdown
• Propósito: Configuração e estado de plugin por projeto
• Uso: Leitura em hooks, comandos e agents
• Ciclo de vida: Gerenciado pelo usuário (não em git, deve estar em .gitignore)

Estrutura do Arquivo

Template Básico

---
enabled: true
setting1: value1
setting2: value2
numeric_setting: 42
list_setting: ["item1", "item2"]
---

# Contexto Adicional

O corpo markdown pode conter:
- Descrições de tarefas
- Instruções adicionais
- Prompts para feedback ao Claude
- Documentação ou notas

Exemplo: Arquivo de Estado do Plugin

.claude/my-plugin.local.md:

---
enabled: true
strict_mode: false
max_retries: 3
notification_level: info
coordinator_session: team-leader
---

# Configuração do Plugin

Este plugin está configurado para modo de validação padrão.
Contate @team-lead com dúvidas.

Leitura de Arquivos de Configuração

De Hooks (Scripts Bash)

Padrão: Verificar existência e fazer parse de frontmatter

#!/bin/bash
set -euo pipefail

# Definir caminho do arquivo de estado
STATE_FILE=".claude/my-plugin.local.md"

# Sair rápido se o arquivo não existir
if [[ ! -f "$STATE_FILE" ]]; then
  exit 0  # Plugin não configurado, ignorar
fi

# Fazer parse de YAML frontmatter (entre marcadores ---)
FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$STATE_FILE")

# Extrair campos individuais
ENABLED=$(echo "$FRONTMATTER" | grep '^enabled:' | sed 's/enabled: *//' | sed 's/^"\(.*\)"$/\1/')
STRICT_MODE=$(echo "$FRONTMATTER" | grep '^strict_mode:' | sed 's/strict_mode: *//' | sed 's/^"\(.*\)"$/\1/')

# Verificar se está habilitado
if [[ "$ENABLED" != "true" ]]; then
  exit 0  # Desabilitado
fi

# Usar configuração na lógica do hook
if [[ "$STRICT_MODE" == "true" ]]; then
  # Aplicar validação rigorosa
  # ...
fi

Veja examples/read-settings-hook.sh para exemplo completo funcionando.

De Comandos

Comandos podem ler arquivos de configuração para personalizar comportamento:

---
description: Processar dados com plugin
allowed-tools: ["Read", "Bash"]
---

# Comando de Processamento

Passos:
1. Verificar se configurações existem em `.claude/my-plugin.local.md`
2. Ler configuração usando ferramenta Read
3. Fazer parse de YAML frontmatter para extrair configurações
4. Aplicar configurações à lógica de processamento
5. Executar com comportamento configurado

De Agents

Agents podem fazer referência a configurações em suas instruções:

---
name: configured-agent
description: Agent que se adapta às configurações do projeto
---

Verificar se há configurações de plugin em `.claude/my-plugin.local.md`.
Se presente, fazer parse de YAML frontmatter e adaptar comportamento conforme:
- enabled: Se o plugin está ativo
- mode: Modo de processamento (strict, standard, lenient)
- Campos de configuração adicionais

Técnicas de Parsing

Extrair Frontmatter

# Extrair tudo entre marcadores ---
FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$FILE")

Ler Campos Individuais

Campos string:

VALUE=$(echo "$FRONTMATTER" | grep '^field_name:' | sed 's/field_name: *//' | sed 's/^"\(.*\)"$/\1/')

Campos booleanos:

ENABLED=$(echo "$FRONTMATTER" | grep '^enabled:' | sed 's/enabled: *//')
# Comparar: if [[ "$ENABLED" == "true" ]]; then

Campos numéricos:

MAX=$(echo "$FRONTMATTER" | grep '^max_value:' | sed 's/max_value: *//')
# Usar: if [[ $MAX -gt 100 ]]; then

Ler Corpo Markdown

Extrair conteúdo após o segundo ---:

# Obter tudo após o fechamento de ---
BODY=$(awk '/^---$/{i++; next} i>=2' "$FILE")

Padrões Comuns

Padrão 1: Hooks Temporariamente Ativos

Usar arquivo de configuração para controlar ativação de hook:

#!/bin/bash
STATE_FILE=".claude/security-scan.local.md"

# Sair rápido se não configurado
if [[ ! -f "$STATE_FILE" ]]; then
  exit 0
fi

# Ler flag enabled
FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$STATE_FILE")
ENABLED=$(echo "$FRONTMATTER" | grep '^enabled:' | sed 's/enabled: *//')

if [[ "$ENABLED" != "true" ]]; then
  exit 0  # Desabilitado
fi

# Executar lógica do hook
# ...

Caso de uso: Habilitar/desabilitar hooks sem editar hooks.json (requer reinicialização).

Padrão 2: Gerenciamento de Estado de Agent

Armazenar estado e configuração específicos do agent:

.claude/multi-agent-swarm.local.md:

---
agent_name: auth-agent
task_number: 3.5
pr_number: 1234
coordinator_session: team-leader
enabled: true
dependencies: ["Task 3.4"]
---

# Atribuição de Tarefa

Implementar autenticação JWT para a API.

**Critérios de Sucesso:**
- Endpoints de autenticação criados
- Testes passando
- PR criado e CI verde

Ler de hooks para coordenar agents:

AGENT_NAME=$(echo "$FRONTMATTER" | grep '^agent_name:' | sed 's/agent_name: *//')
COORDINATOR=$(echo "$FRONTMATTER" | grep '^coordinator_session:' | sed 's/coordinator_session: *//')

# Enviar notificação ao coordenador
tmux send-keys -t "$COORDINATOR" "Agent $AGENT_NAME completed task" Enter

Padrão 3: Comportamento Orientado por Configuração

.claude/my-plugin.local.md:

---
validation_level: strict
max_file_size: 1000000
allowed_extensions: [".js", ".ts", ".tsx"]
enable_logging: true
---

# Configuração de Validação

Modo rigoroso habilitado para este projeto.
Todas as escritas validadas contra políticas de segurança.

Usar em hooks ou comandos:

LEVEL=$(echo "$FRONTMATTER" | grep '^validation_level:' | sed 's/validation_level: *//')

case "$LEVEL" in
  strict)
    # Aplicar validação rigorosa
    ;;
  standard)
    # Aplicar validação padrão
    ;;
  lenient)
    # Aplicar validação permissiva
    ;;
esac

Criando Arquivos de Configuração

De Comandos

Comandos podem criar arquivos de configuração:

# Comando de Setup

Passos:
1. Perguntar ao usuário suas preferências de configuração
2. Criar `.claude/my-plugin.local.md` com YAML frontmatter
3. Definir valores apropriados baseado na entrada do usuário
4. Informar ao usuário que configurações foram salvas
5. Lembrar o usuário de reiniciar Claude Code para hooks reconhecerem mudanças

Geração de Template

Fornecer template na documentação do plugin:

## Configuração

Criar `.claude/my-plugin.local.md` em seu projeto:

\`\`\`markdown
---
enabled: true
mode: standard
max_retries: 3
---

# Configuração do Plugin

Suas configurações estão ativas.
\`\`\`

Após criar ou editar, reiniciar Claude Code para que as mudanças tenham efeito.

Melhores Práticas

Nomenclatura de Arquivo

✅ FAZER:

• Usar formato .claude/plugin-name.local.md
• Corresponder nome do plugin exatamente
• Usar sufixo .local.md para arquivos locais do usuário

❌ NÃO FAZER:

• Usar diretório diferente (não .claude/)
• Usar nomenclatura inconsistente
• Usar .md sem .local (pode ser commitado)

Gitignore

Sempre adicionar ao .gitignore:

.claude/*.local.md
.claude/*.local.json

Documentar isso no README do plugin.

Padrões Padrão

Fornecer padrões sensatos quando arquivo de configuração não existe:

if [[ ! -f "$STATE_FILE" ]]; then
  # Usar padrões
  ENABLED=true
  MODE=standard
else
  # Ler do arquivo
  # ...
fi

Validação

Validar valores de configuração:

MAX=$(echo "$FRONTMATTER" | grep '^max_value:' | sed 's/max_value: *//')

# Validar intervalo numérico
if ! [[ "$MAX" =~ ^[0-9]+$ ]] || [[ $MAX -lt 1 ]] || [[ $MAX -gt 100 ]]; then
  echo "⚠️  max_value inválido em configurações (deve ser 1-100)" >&2
  MAX=10  # Usar padrão
fi

Requisito de Reinicialização

Importante: Mudanças de configuração requerem reinicialização do Claude Code.

Documentar no seu README:

## Alterando Configurações

Após editar `.claude/my-plugin.local.md`:
1. Salvar o arquivo
2. Sair do Claude Code
3. Reiniciar: `claude` ou `cc`
4. Novas configurações serão carregadas

Hooks não podem ser trocados a quente dentro de uma sessão.

Considerações de Segurança

Sanitizar Entrada do Usuário

Ao escrever arquivos de configuração a partir de entrada do usuário:

# Escapar aspas na entrada do usuário
SAFE_VALUE=$(echo "$USER_INPUT" | sed 's/"/\\"/g')

# Escrever no arquivo
cat > "$STATE_FILE" <<EOF
---
user_setting: "$SAFE_VALUE"
---
EOF

Validar Caminhos de Arquivo

Se configurações contêm caminhos de arquivo:

FILE_PATH=$(echo "$FRONTMATTER" | grep '^data_file:' | sed 's/data_file: *//')

# Verificar travessia de diretório
if [[ "$FILE_PATH" == *".."* ]]; then
  echo "⚠️  Caminho inválido em configurações (travessia de diretório)" >&2
  exit 2
fi

Permissões

Arquivos de configuração devem ser:

• Legíveis apenas pelo usuário (chmod 600)
• Não commitados em git
• Não compartilhados entre usuários

Exemplos do Mundo Real

Plugin multi-agent-swarm

.claude/multi-agent-swarm.local.md:

---
agent_name: auth-implementation
task_number: 3.5
pr_number: 1234
coordinator_session: team-leader
enabled: true
dependencies: ["Task 3.4"]
additional_instructions: Usar tokens JWT, não sessões
---

# Tarefa: Implementar Autenticação

Construir autenticação baseada em JWT para a API REST.
Coordenar com auth-agent em tipos compartilhados.

Uso do hook (agent-stop-notification.sh):

• Verifica se arquivo existe (linhas 15-18: sair rápido se não)
• Faz parse de frontmatter para obter coordinator_session, agent_name, enabled
• Envia notificações ao coordenador se habilitado
• Permite ativação/desativação rápida via enabled: true/false

Plugin ralph-wiggum

.claude/ralph-loop.local.md:

---
iteration: 1
max_iterations: 10
completion_promise: "Todos os testes passando e build bem-sucedido"
---

Corrigir todos os erros de lint no projeto.
Certificar que testes passam após cada correção.

Uso do hook (stop-hook.sh):

• Verifica se arquivo existe (linhas 15-18: sair rápido se não ativo)
• Lê contagem de iteração e max_iterations
• Extrai completion_promise para terminação do loop
• Lê corpo como prompt para fazer feedback
• Atualiza contagem de iteração a cada loop

Referência Rápida

Localização do Arquivo

project-root/
└── .claude/
    └── plugin-name.local.md

Parsing de Frontmatter

# Extrair frontmatter
FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$FILE")

# Ler campo
VALUE=$(echo "$FRONTMATTER" | grep '^field:' | sed 's/field: *//' | sed 's/^"\(.*\)"$/\1/')

Parsing de Corpo

# Extrair corpo (após o segundo ---)
BODY=$(awk '/^---$/{i++; next} i>=2' "$FILE")

Padrão de Saída Rápida

if [[ ! -f ".claude/my-plugin.local.md" ]]; then
  exit 0  # Não configurado
fi

Recursos Adicionais

Arquivos de Referência

Para padrões de implementação detalhados:

• references/parsing-techniques.md - Guia completo para fazer parse de YAML frontmatter e corpos markdown
• references/real-world-examples.md - Deep dive em implementações de multi-agent-swarm e ralph-wiggum

Arquivos de Exemplo

Exemplos funcionando em examples/:

• read-settings-hook.sh - Hook que lê e usa configurações
• create-settings-command.md - Comando que cria arquivo de configuração
• example-settings.md - Template de arquivo de configuração

Scripts Utilitários

Ferramentas de desenvolvimento em scripts/:

• validate-settings.sh - Validar estrutura do arquivo de configuração
• parse-frontmatter.sh - Extrair campos de frontmatter

Workflow de Implementação

Para adicionar configurações a um plugin:

1. Projetar schema de configurações (quais campos, tipos, padrões)
2. Criar arquivo template na documentação do plugin
3. Adicionar entrada gitignore para .claude/*.local.md
4. Implementar parsing de configurações em hooks/comandos
5. Usar padrão de saída rápida (verificar existência do arquivo, verificar campo enabled)
6. Documentar configurações no README do plugin com template
7. Lembrar usuários que mudanças requerem reinicialização do Claude Code

Focar em manter configurações simples e fornecer bons padrões quando arquivo de configuração não existe.