Pushary

Notificações push e aprovações com intervenção humana para agentes de IA: faça uma pergunta durante a execução e receba a resposta direto na tela de bloqueio do celular.

GitHub

Documentação

Pushary Agent Skill

Notificações push e humano-no-circuito para agentes de IA. Aprove pelo seu celular.
Começar · Diretório de skills · Reportar um bug

Comece aqui

Experimente uma aprovação sem se cadastrar → conecte uma página aberta no celular → aprove ou recuse → veja o agente continuar ou parar. Esta demonstração no navegador usa polling e estado temporário, não entrega push real nem o ledger de produção.

O que você quer construir	Comece com
Notificações e perguntas para um agente de codificação	As instruções de configuração abaixo
Uma aprovação de ferramenta obrigatória no Vercel AI SDK	Exemplo executável com AI SDK
Um fluxo LangGraph que ramifica com base em uma decisão humana	Exemplo executável com LangGraph
Outro framework de agentes	Todas as integrações Pushary

A skill e os adaptadores são licenciados sob MIT. A entrega hospedada no celular exige uma conta Pushary; incorporar aprovações para seus próprios usuários exige acesso Partner. Os dois exemplos de framework também rodam localmente com respostas simuladas e sem credenciais.

Se o Pushary ajudou você, dê uma estrela neste repositório. Quer ajudar? Issues públicas e patches são bem-vindos.

O Pushary permite que seu agente de codificação envie atualizações de tarefas e peça uma decisão no seu celular. Hooks de host compatíveis também impõem aprovações antes de uma ação ser executada.

A entrega hospedada exige um plano Pushary pago. Perguntas e notificações via MCP funcionam com qualquer cliente compatível; aprovações obrigatórias dependem da integração do host.

Como Funciona

AI Agent  ->  MCP Protocol  ->  Pushary API  ->  Push Notification  ->  Your Phone

O Pushary é um servidor MCP que conecta seu agente de codificação de IA a notificações push. O agente chama as ferramentas do Pushary pelo Model Context Protocol, e você recebe notificações instantaneamente em qualquer dispositivo.

Três tipos de pergunta - confirmações sim/não, múltipla escolha e texto livre. Seu agente escolhe o tipo certo para cada situação.

Notificações com contexto rico - os agentes podem incluir alterações de arquivos, detalhes de erros e próximos passos sugeridos em uma página de detalhes que você vê ao tocar na notificação.

Identificação do agente - quando você executa vários agentes, cada notificação mostra qual agente está perguntando, para você sempre saber a quem está respondendo.

Hooks de permissão - encaminhe os prompts de aprovação de ferramentas do Claude Code por notificações push para que você possa aprovar ou negar pelo celular.

Configuração pessoal: celular primeiro

Execute a configuração de pareamento no terminal do seu agente:

npx pushary@latest setup

Instale o Pushary no seu celular, escaneie o QR ou abra o link impresso, compare as impressões digitais e aprove. A configuração então ajusta as ferramentas do agente selecionado, hooks compatíveis e a skill. Você não precisa copiar uma chave de API primeiro. Contas pessoais exigem um plano pago. Credenciais existentes são reutilizadas.

Verifique a configuração:

npx pushary@latest doctor

Peça ao seu agente uma pergunta de teste inofensiva. Confirme se o dispositivo pretendido a recebe e se a resposta retorna para a mesma tarefa.

Especificamente para o Hermes:

npx pushary@latest setup --agents hermes

Isso instala o plugin nativo no interpretador do Hermes e o configura. O plugin fornece ferramentas de notificação, pergunta, espera, cancelamento e escopo, além de ferramentas de inscrição Partner e perguntas de clientes. Seus parâmetros usam snake_case; use a skill do Hermes, não os nomes de parâmetros MCP. O transporte de aprovação nativo preserva a sessão do Hermes e as aprovações permanentes.

Notch do Mac e outras superfícies de resposta

Instale o Pushary para Mac, entre com a mesma conta pessoal e conecte seus agentes pelo aplicativo. O notch oferece controles de confirmação, escolha, texto e conjuntos de perguntas com suporte a teclado. Mantenha o aplicativo em execução para presença e entrega; verifique uma pergunta inofensiva lá e, depois, use o fallback do celular quando estiver longe do Mac.

Superfície	Respostas
Celular	Confirmação, escolha e texto no aplicativo. Notificações de confirmação compatíveis expõem aprovar/negar na tela de bloqueio; escolhas arbitrárias e texto abrem o aplicativo.
Notch do Mac	Perguntas de conta pessoal, incluindo resposta por teclado. Nenhuma caixa de entrada de cliente Partner é fornecida atualmente.
Slack	Botões, menus de escolha e modais de texto quando a integração e o destinatário estão configurados.
Navegador	Fallback de página de decisão e notificações do navegador quando a permissão está habilitada.

A entrega segue suas configurações e presença. push_first usa presença, push_only solicita push a cada vez, notify_only mantém decisões no cliente atual e terminal_only evita push. Uma chamada de API bem-sucedida por si só não prova que um dispositivo exibiu a solicitação.

Configuração Partner: seus próprios clientes

O pareamento pessoal conecta você, o operador. Integrações Partner inscrevem cada cliente do seu aplicativo por meio de um link de conexão com escopo e endereçam decisões usando seu ID de cliente estável. Os clientes usam o fluxo de inscrição móvel; não encaminhe as aprovações deles para sua caixa de entrada pessoal no Mac nem compartilhe uma chave de API do operador.

Comece com o guia de integração Partner e depois um exemplo de agente Mastra, exemplo com AI SDK ou exemplo com LangGraph. As ferramentas escolhem confirmação, escolha ou texto. Aprovar uma ação e fornecer uma resposta são operações diferentes; uma resposta em texto dizendo "sim" não é permissão para executar outra ferramenta.

Fallbacks de navegador e manuais

Para pareamento no navegador:

npx pushary@latest setup --connect browser

Para um cliente que precisa de configuração MCP manual, obtenha sua chave no painel do Pushary e configure:

{
  "mcpServers": {
    "pushary": {
      "url": "https://pushary.com/api/mcp/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Mantenha a chave privada. Instale a skill com npx skills add Pushary/pushary-skill se o cliente suportar skills.sh. O MCP manual fornece perguntas e notificações cooperativas; aprovações obrigatórias exigem os hooks de host/integração de runtime compatíveis.

Usuários do Claude Code podem alternativamente instalar este repositório como um plugin:

/plugin marketplace add Pushary/pushary-skill
/plugin install pushary

Esse caminho lê PUSHARY_API_KEY do ambiente. Escolha um único caminho de instalação: instalar o plugin sobre hooks do Claude instalados via CLI pode executar hooks duas vezes. Use npx pushary@latest clean antes de trocar de caminho.

Configuração: Lovable

Lovable é um construtor de aplicativos hospedado, então não há etapa de instalação local (npx skills add não se aplica). Você conecta o servidor MCP na interface do Lovable e depois cola a skill no Knowledge do Lovable para que o agente a use por conta própria.

1. Conecte o servidor MCP. No Lovable, vá em Settings -> Connectors -> Personal connectors (planos Lovable pagos), clique em New MCP server, defina a URL como https://pushary.com/api/mcp/mcp, escolha Bearer token e cole sua chave de API (pk_xxx.sk_xxx).

2. Adicione a skill ao Knowledge. O Lovable não pode instalar skills via npx, então cole as orientações da skill em Settings -> Knowledge. Use a versão condensada SKILL-LITE.md como fonte. Isso faz o agente do Lovable notificar você quando um build termina e perguntar antes de mudanças arriscadas, sem você precisar solicitar a cada vez.

O Lovable recebe apenas notificações e perguntas (sem gate obrigatório, pois não tem hook de permissão). Passo a passo completo: Guia do Lovable.

Configuração: Claude Chat e Cowork

Para Claude Chat ou Claude Code, use o Pushary para Claude. No Chat, abra Customize > Plugins > Add > Add marketplace, adicione https://github.com/Pushary/claude-plugin e instale Pushary for Claude. No Claude Code, execute /plugin marketplace add Pushary/claude-plugin e depois /plugin install pushary@pushary-claude-plugin.

Para o Cowork, o plugin Pushary for Cowork existente continua disponível. Adicione https://github.com/Pushary/cowork-plugin como marketplace e instale Pushary for Cowork. O Cowork também suporta instruções permanentes em Settings > Cowork. Os identificadores de skill existentes do plugin, marketplace e pushary-cowork são preservados.

Ambos os pacotes usam o conector OAuth público e a mesma skill compartilhada. Conecte o Pushary pela aba Connectors do plugin no Chat ou Cowork, ou /mcp no Claude Code, e entre com a mesma conta Pushary usada no seu celular ou Mac. Nenhuma CLI ou chave de API é necessária para nenhum dos pacotes.

Se o conector estiver ausente, adicione https://pushary.com/api/mcp/mcp em Customize > Connectors > Add custom connector e deixe os campos OAuth Client ID e Secret vazios. Habilite o Pushary na conversa, faça uma pergunta de teste inofensiva e verifique se sua resposta retorna ao Claude.

Esses pacotes fornecem perguntas e notificações e não instalam hooks de permissão nativos. Para hooks de aprovação no Claude Code, use a configuração do Claude Code acima. Escolha um caminho de instalação por aplicativo para evitar conectores Pushary duplicados. Guia completo do Claude.

Ferramentas

A skill orienta estas ferramentas MCP:

Ferramenta	Descrição
`send_notification`	Envia uma notificação push com contexto rico opcional (alterações de arquivos, erros, próximos passos)
`ask_user`	Pergunta ao usuário via push - sim/não, múltipla escolha ou texto livre
`wait_for_answer`	Long-poll pela resposta do usuário a uma pergunta
`cancel_question`	Cancela uma pergunta pendente que não é mais relevante
`list_sessions`	Visualização somente leitura das suas sessões de agente ativas e perguntas pendentes
`propose_scope`	Ratifica o limite de uma execução: globs de arquivos, aplicados em hosts compatíveis, ou uma promessa registrada quando a execução não altera arquivos

Documentação completa das ferramentas com parâmetros, exemplos e diretrizes de uso está em skills/pushary/SKILL.md.

Humano no Circuito

O agente pode pedir decisões via push e esperar sua resposta:

Agent: "Which auth strategy should I use?"
  Options: JWT tokens / Session cookies / OAuth2 + PKCE
  -> push to your phone

You: tap "JWT tokens"

Agent: proceeds with JWT implementation

Suporta três tipos de pergunta:

Confirm - decisões binárias sim/não
Select - escolha entre 2 a 6 opções
Input - resposta em texto livre

Leia answered, status e handoffAction (ou nextAction) do resultado da ferramenta. Faça polling apenas conforme orientado; cancele uma pergunta ativa antes de passá-la para outra superfície e honre qualquer resposta vencedora. Expiração e esperas seguem a política do servidor. Silêncio não é aprovação, e uma resposta atrasada não pode reiniciar uma rodada do agente já encerrada.

Pacotes

Pacote	Registro	Descrição
`pushary`	npm	A CLI do Pushary: configuração, hooks de permissão e doctor. Também publicada como `@pushary/agent-hooks`, o mesmo pacote
`hermes-plugin-pushary`	PyPI	Plugin nativo do Hermes Agent

Agentes Compatíveis

Funciona com qualquer agente que suporte skills.sh ou o Model Context Protocol:

Claude Code (MCP + hooks de permissão)
Claude Cowork (conector personalizado + upload de skill)
Hermes Agent (plugin nativo ou MCP)
Cursor (MCP)
Windsurf (MCP)
Lovable (conector MCP + skill via Knowledge)
OpenAI Codex (MCP)
Outros clientes que suportam servidores MCP remotos

Publicando a entrada no registro MCP

server.json não é publicado ao fazer merge. O registro MCP serve um registro por versão, então uma edição aqui não alcança ninguém até que a nova versão seja enviada ao registro, e o texto antigo continua sendo o que todo agente lê.

Caminho do dia a dia: aumente version em server.json, faça merge em main e depois sincronize o espelho público da skill. O workflow de release dele publica a nova entrada no registro. O fluxo de trabalho de release publica a partir do repositório público Pushary para que o GitHub OIDC possa comprovar a propriedade do namespace io.github.Pushary/pushary. Verifique o fluxo de trabalho e o resultado do registro após o release.

Fallback manual, a partir deste diretório:

curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
./mcp-publisher login github
./mcp-publisher publish

Verifique o que o registro realmente serve, que é o único número que importa:

curl -s "https://registry.modelcontextprotocol.io/v0/servers?search=pushary"

Esse endpoint retorna todas as versões, da mais antiga para a mais recente. Leia a entrada cujo _meta."io.modelcontextprotocol.registry/official".isLatest é true; a primeira linha da lista é o registro mais antigo, não o atual.

Contribuindo

Contribuições são bem-vindas! Por favor, leia o guia de contribuição antes de enviar um pull request.

Segurança

Se você descobrir uma vulnerabilidade de segurança, por favor, reporte-a de forma responsável. Veja SECURITY.md para detalhes.

Financiamento

Este projeto é totalmente financiado pela RalphNex OU, uma agência de desenvolvimento de software estoniana.