O teu projeto vira uma app do Mac

O que é e porque importa

Com o Claude fizeste uma ferramenta tua, e todas as manhãs é o mesmo ritual: abres o terminal, arrancas o servidor (o programa que põe a app a correr no teu computador), procuras o separador certo no browser. E se fechas o terminal sem querer, desliga-se tudo.

O app-it é um projeto gratuito e open source (licença MIT) que se junta ao Claude Code e transforma esse projeto numa app do Mac, com ícone na Dock e janela próprios. Duplo clique: a app liga o servidor sozinha e abre uma janela nativa (WebKit, o motor do Safari). Com ⌘Q desligas também o servidor e libertas a porta (o número, tipo 5173, em que responde).

Não reescreve a tua app: acrescenta alguns ficheiros e deixa-te um relatório para voltar atrás. É um projeto não oficial de um programador independente, não da Anthropic. E é para uso teu: não serve para pôr a app na App Store nem para a vender.

1. O que precisas antes

• Um Mac. Na prática o app-it é só para macOS: o ramo para Windows ainda é experimental e não o recomendo.
• As Xcode Command Line Tools, as ferramentas de desenvolvimento da Apple, que são precisas para construir a janela. Se não as tens: escreve xcode-select --install no Terminal.
• Aquilo que o teu projeto já usa para arrancar, instalado e a funcionar: por exemplo o Node e as suas dependências (npm install já feito). O app-it não instala nada por ti.
• O Claude Code, aberto na pasta do projeto.

O teste mais simples: se hoje arrancas o projeto à mão no terminal e funciona, estás pronto. Se à mão não arranca, o app-it não o resolve: trata primeiro disso.

2. Junta-o ao Claude Code

O app-it é um plugin, ou seja, um pacote de instruções e scripts para o Claude Code. Não está no marketplace oficial da Anthropic mas no do projeto, no GitHub: primeiro adicionas esse, depois instalas o plugin. Dentro de uma sessão do Claude Code:

1. Escreve /plugin marketplace add Christian-Katzmann/app-it. Adicionas o catálogo do projeto (o repositório é github.com/Christian-Katzmann/app-it).
2. Escreve /plugin install app-it@app-it. Não instala logo: abre-te a ficha do plugin com o que acrescenta. Lê-a e depois escolhe onde o instalar (para ti, em todos os projetos, está ótimo).
3. Se o Claude Code te pedir, escreve /reload-plugins. No terminal os mesmos passos são claude plugin marketplace add e claude plugin install.

Vale para qualquer plugin de terceiros: lê o que instalas, porque pode pôr scripts a correr no teu computador. O código do app-it é público e o projeto diz que não envia nada para a internet nem recolhe dados.

3. Corre o /app-it no projeto

Abre o Claude Code na pasta do projeto e escreve /app-it (o nome completo é /app-it:app-it). Olha para o projeto, escolhe como construir a app, constrói-a, instala-a e testa-a. Eu escrevo-lhe assim:

/app-it
Transforma este projeto numa app do Mac com o seu próprio ícone.
Não mexas na lógica da app.
No fim explica-me o relatório em palavras simples: que tipo de projeto encontraste, em que porta corre, que ícone usaste, que ficheiros acrescentaste e como se tira tudo.
Diz-me também o que tenho de verificar eu à mão.

A última linha conta: o Claude verifica sozinho que o servidor responde e que o ⌘Q o desliga, mas a janela e o ícone na Dock vês tu.

O que acrescenta ao teu projeto

• Uma pasta scripts/ com os scripts para construir, instalar e fechar a app, e o ficheiro scripts/app-it.config.json com o nome, a porta e o comando de arranque.
• Um ícone em assets/, o que encontra no projeto ou um provisório gerado no teu Mac.
• No package.json, os comandos desktop:build, desktop:install, desktop:quit, desktop:doctor e desktop:verify.
• docs/desktop-launcher.md, as instruções curtas, e docs/desktop-launcher.app-it-report.md, o relatório com cada alteração.

4. Usa-a todos os dias

• Primeiro arranque: se o macOS não a abrir, clique direito no ícone, Abrir, e confirma. O primeiro arranque é mais lento, porque o servidor tem de começar do zero.
• Fechar a janela com ⌘W ou com o botão vermelho não desliga o servidor: fica ligado, para que da próxima vez reabra logo. Para desligar tudo e libertar a porta precisas de ⌘Q, ou Sair no menu do ícone na Dock.
• Se a porta preferida estiver ocupada, normalmente a app escolhe uma livre um pouco acima e regista-a no ficheiro ~/Library/Application Support/app-it/<nome-app>/server.port.
• A app põe o servidor a correr a partir da pasta do projeto, e lembra-se de onde ela está. Se a mudares de sítio ou a apagares, a app deixa de funcionar: volta a pô-la onde estava, ou corre outra vez o /app-it no sítio novo.

Um truque: arrasta a pasta ~/Applications/App It/ para a direita da Dock. Fica uma pilha, e cada app que criares depois aparece lá sozinha. Para uma verificação, ou para mudar o ícone:

Verifica a app que criaste com o app-it.
Corre npm run desktop:doctor e diz-me em palavras simples: em que porta corre mesmo o servidor, se o ícone instalado é o certo e se há alguma coisa a corrigir.
Depois usa como ícone esta imagem: [caminho da imagem], volta a construir e a instalar a app.
Não mexas no código da app.

5. Quando a app está acabada: app-it-static

O app-it mantém ligado o servidor de desenvolvimento: dá jeito enquanto trabalhas nele, mas pesa na memória do Mac. Para uma ferramenta acabada há um irmão mais leve no mesmo marketplace, o app-it-static: constrói a app uma vez (o build, a versão final dos ficheiros) e serve isso. A mesma janela, a mesma pilha na Dock.

Instala-se com /plugin install app-it-static@app-it e corre-se com /app-it-static. O limite a saber: mostra uma fotografia do build. Se depois mudares o código, a app não o vê até correres npm run desktop:rebuild.

/app-it-static
Este projeto está acabado: quero uma app do Mac leve que sirva o build, sem servidor de desenvolvimento.
Antes de começares diz-me que comando de build vais usar e em que pasta fica o resultado, e espera pelo meu ok.

Extra: uma app que já está online, como um Artifact do Claude

O app-it também consegue pôr um endereço web numa janela da Dock, como um Artifact do Claude publicado. A janela carrega o link, entras com a tua conta e o uso fica no teu plano. Dá ao Claude o link publicado, não o código copiado.

6. Como voltar atrás

Tudo o que o app-it acrescenta pode ser tirado, e o relatório diz o quê. Põe o Claude a fazê-lo a partir daí, vendo primeiro a lista.

Quero tirar o app-it deste projeto.
Lê docs/desktop-launcher.app-it-report.md e mostra-me a lista de ficheiros, pastas e linhas do package.json que o app-it acrescentou, mais a app instalada em ~/Applications/App It/.
Primeiro desliga a app com npm run desktop:quit.
Não apagues nada até eu te dar o ok, e não mexas no código da app.

Os erros mais comuns

• Correr o /app-it num projeto que à mão não arranca. Se a janela mostra um erro do servidor, normalmente é o projeto: corrige-o no terminal e depois reconstrói a app.
• Fechar com o botão vermelho e achar que desligaste tudo. O servidor fica ligado: para o desligar precisas de ⌘Q.
• Mudar de sítio ou de nome a pasta do projeto depois de criar a app. A app procura-a onde estava.
• Mandar o ficheiro .app a um amigo como se fosse uma app a sério. Está assinada só para o teu Mac, não é notarizada pela Apple, e sem a pasta do projeto e o seu servidor não funciona.

Checklist

• O projeto arranca à mão no terminal
• As Xcode Command Line Tools estão instaladas (xcode-select --install)
• Li a ficha do plugin app-it antes de o instalar
• O Claude explicou-me o relatório do app-it e o que verificar à mão
• A janela mostra a minha app e o ícone dela está na Dock
• O ⌘Q desliga o servidor e liberta a porta
• A pasta ~/Applications/App It/ está na Dock

Perguntas frequentes