Como criar comandos personalizados de IA e predefinições no Raycast AI para otimizar fluxos de trabalho no macOS

Ficar alternando constantemente entre o editor de código, o terminal e abas de navegadores para interagir com chatbots de IA fragmenta o foco do desenvolvedor. O Raycast AI resolve essa fricção ao integrar grandes modelos de linguagem diretamente ao macOS na forma de um inicializador de sistema. Em vez de copiar texto, abrir o navegador, formular o prompt e colar a resposta de volta, você pode disparar rotinas inteligentes sob medida em qualquer aplicativo ativo com apenas um atalho no teclado.

O ecossistema do Raycast AI divide essas tarefas frequentes em duas ferramentas essenciais:

1. Comandos personalizados de IA (Custom AI Commands): Ações diretas e imediatas que operam sobre o texto selecionado ou a área de transferência, exibindo o resultado em uma janela flutuante ou substituindo o texto selecionado no local.
2. Predefinições e agentes de IA (AI Presets / Agents): Instruções de sistema e personas persistentes para conversas contínuas em chat, configuradas com modelos específicos, níveis de raciocínio e ferramentas integradas.

Neste guia, você verá o passo a passo para criar comandos de IA, configurar agentes e presets personalizados, utilizar marcadores de posição dinâmicos e associar atalhos globais de teclado no seu dia a dia.

1. Criando comandos personalizados de IA

Os comandos de IA personalizados são ideais para etapas bem definidas, como refatoração de código, geração de tipos, revisão gramatical ou tradução.

Passo a passo de configuração

1. Pressione ⌥ Espaço (ou o atalho configurado para abrir o Raycast).
2. Digite Create AI Command e tecle Enter. (Você também pode pesquisar em Search AI Commands, selecionar um comando padrão e pressionar ⌘D para duplicá-lo e editá-lo).
3. Preencha os campos da janela de configuração:
   • Name & Icon (Nome e ícone): Defina um nome claro (por exemplo, Refactor to TypeScript ou Explain SQL Query) e escolha um ícone.
   • Prompt (Instrução): Escreva as instruções para o modelo. Digite { para inserir marcadores dinâmicos e @ para anexar extensões de ferramentas.
   • Model (Modelo): Selecione o modelo responsável pela execução (como Claude 3.5 Sonnet, GPT-4o ou modelos de raciocínio profundo como o1/o3-mini). Se deixar em branco, o comando usará o modelo padrão definido em Settings → AI → Models & Providers.
   • Creativity (Criatividade / Temperatura): Escolha entre None, Low, Medium, High ou Maximum. Para tarefas de código e dados estruturados, utilize None ou Low.
   • Reasoning Effort (Esforço de raciocínio): Ajuste o tempo de reflexão caso utilize modelos com suporte a raciocínio estendido.
   • Output Behavior (Comportamento de saída):
     • Open in Raycast: Apresenta a resposta em uma janela flutuante do Raycast, facilitando a leitura e cópia, com a opção de teclar ⌘J para levar todo o histórico para o AI Chat.
     • Replace Selection: Substitui diretamente o texto selecionado no aplicativo ativo pelo conteúdo gerado pela IA.
   • Highlight Editing Changes (Destacar alterações): Quando ativo junto a Replace Selection, realça as diferenças para facilitar a revisão visual.
4. Pressione ⌘ Enter para salvar. O comando estará pronto para uso imediato no Raycast.

2. Aproveitando marcadores de posição dinâmicos (Dynamic Placeholders)

Os marcadores de posição do Raycast injetam o contexto do seu ambiente de trabalho no prompt em tempo de execução, dispensando a necessidade de copiar e colar manualmente.

Modificadores de formatação

Você pode encadear modificadores usando uma barra vertical para tratar os dados de entrada:

• {clipboard | trim}: Remove espaços em branco e quebras de linha no início e no final.
• {selection | lowercase} ou {selection | uppercase}: Padroniza o texto em minúsculas ou maiúsculas.
• {selection | json-stringify}: Escapa aspas e caracteres especiais para inclusão segura em payloads JSON.
• {clipboard | raw}: Desativa a adição automática de aspas pelo Raycast.

Exemplos práticos de comandos de IA

Exemplo 1: Geração in loco de tipos TypeScript e documentação JSDoc

• Comportamento de saída: Replace Selection
• Creativity: Low
• Prompt:

Analyze the following code selection:
{selection}

Add strict TypeScript types, explicit interface definitions, and JSDoc documentation. Return only the updated code block without surrounding explanations or markdown wrappers.

Exemplo 2: Gerador interativo de mensagens de commit para Git

• Comportamento de saída: Open in Raycast
• Prompt:

Write a concise, conventional git commit message based on the following diff or staged summary:
{clipboard}

Focus on type: {argument name="Commit Type" default="feat"}.
Format as:
<type>(<scope>): <summary>

- Optional body explaining the why behind the change.

3. Configurando predefinições e agentes de IA personalizados

Enquanto comandos de IA focam em tarefas rápidas de disparo único, fluxos de engenharia mais complexos demandam chats com personas fixas, regras de arquitetura e acesso a ferramentas específicas.

No Raycast v1, essa funcionalidade era chamada de AI Chat Presets; no Raycast v2, ela evoluiu para Agents (Agentes), mantendo total compatibilidade com predefinições existentes e com a galeria pública Preset Explorer.

Criando um novo agente

1. Acesse Settings → AI → Agents (ou pesquise Search Agents e selecione Create Agent).
2. Configure os parâmetros do agente:
   • Name & Icon: Um identificador claro (por exemplo, Otimizador de Consultas PostgreSQL ou Revisor de Código Sênior).
   • Model: Vincule um modelo específico ou selecione Inherit para seguir a seleção ativa da janela de chat.
   • Instructions (Prompt de sistema): Defina a persona, restrições arquiteturais, diretrizes de código e estilo de resposta.
   • AI Extensions (Extensões de IA): Atribua as ferramentas que o agente tem permissão para acionar (como @calendar, @github, @file-search).
3. Pressione ⌘ Enter para salvar.

Acionando e alternando agentes

• No AI Chat: Digite / no campo de mensagem para abrir o seletor rápido ou pressione ⌘K → Change Agent.
• Direto pelo inicializador: Digite o nome do agente no campo de busca do Raycast e tecle Enter para abrir uma nova conversa com aquela persona.
• Importação comunitária: Navegue pelo presets.ray.so para instalar predefinições criadas pela comunidade com um clique.

4. Atalhos globais e correção instantânea com o Quick Fix

Para eliminar qualquer interrupção, associe seus comandos e agentes a atalhos de teclado do macOS:

1. Configurando Hotkeys exclusivos:

   • Vá em Settings → Extensions → AI (ou pressione ⌘K → Configure Command sobre o comando desejado).
   • Clique no campo Hotkey correspondente e registre a combinação (ex.: ⌃⌥C para gerar commits ou ⌃⌥R para refatorar código).
   • Ao destacar código no VS Code ou Xcode, basta pressionar ⌃⌥R para que a refatoração ocorra no local, sem nem abrir a barra de busca.

2. Utilizando o Quick Fix:

   • O Raycast conta com o recurso nativo Quick Fix, voltado para correções ortográficas e gramaticais rápidas.
   • Por padrão, dar dois toques rápidos na tecla Shift direita (Double Right Shift) analisa e corrige o texto no campo atual.
   • Em Settings → AI → Quick Fix, ative a opção Preserve Formatting para manter formatações em negrito e links ao corrigir textos em editores ricos como Slack e Notion.

5. Permissões, planos de assinatura e integração de modelos

Permissões de Acessibilidade no macOS

A substituição de texto no local (Replace Selection) e o Quick Fix exigem permissões de acessibilidade do macOS:

• Vá em Ajustes do Sistema → Privacidade e Segurança → Acessibilidade (ou "Controle de dispositivos e acesso a dados" em versões recentes).
• Conceda permissão de controle para o Raycast.

Assinaturas e opção BYOK (Bring Your Own Key)

• Raycast Free: Acesso a utilitários essenciais do inicializador (calculadora, snippets, histórico de transferência e extensões da loja).
• Raycast Pro (US$ 10/mês ou US$ 96/ano): Desbloqueia o Raycast AI com créditos mensais de IA, sincronização em nuvem e comandos de IA personalizados.
• Planos Pro+ e Max: Planos com cotas maiores de créditos para uso intensivo de modelos de última geração.
• BYOK e assinaturas vinculadas: Assinantes dos planos pagos podem inserir suas próprias chaves de API da OpenAI, Anthropic, Google e OpenRouter, ou vincular diretamente assinaturas ativas do ChatGPT e do Claude, combinando a ergonomia do Raycast com o controle direto de seus custos.

Unindo comandos de execução rápida a predefinições estruturadas de chat, desenvolvedores e profissionais no macOS conseguem incorporar assistência de IA nativa em cada detalhe de sua rotina.

Referências

• AI Commands | Raycast Manual
• Dynamic Placeholders | Raycast Manual
• Agents | Raycast Manual
• AI Chat | Raycast Manual