Manual

Por que o mclovin existe?

O mclovin nasceu de três dores diárias: link do Spotify abrindo no navegador em vez do app, link de repositório do trabalho caindo no profile errado do Chrome, link de Google Meet do cliente abrindo onde a câmera do trabalho está. No macOS eu resolvia com o Finicky e achava que estava em paz.

Com IA pra acelerar o protótipo, a primeira versão saiu em alguns minutos e resolveu pro meu setup. Resolver só pra mim era pequeno demais. Passei mais tempo polindo até virar algo que qualquer pessoa que sofra com isso pode usar.

A missão é cobrir os três sistemas e, no caminho, expor o que os sistemas operacionais e os navegadores estão deixando de fazer há tempo demais. Linux x86_64 e macOS Apple Silicon já estão funcionando, Windows vem na sequência. Qualquer problema, abra uma issue no GitHub. Você clica num link e ele abre no lugar certo. Sem perguntar qual profile, sem fechar janela errada, sem perder dois minutos por clique.

Instalação

Linux x86_64 e macOS arm64 (Apple Silicon). Windows é o próximo.

curl -fsSL https://mclovin.org/install.sh | bash

O script detecta a sua plataforma e faz a coisa certa:

• Linux — baixa o binário pra ~/.local/bin/mclovin, registra o mclovin como navegador padrão do sistema, e instala o atalho mclovin.desktop no menu de apps. Abre o mclovin pelo launcher (Walker, rofi, menu de apps do GNOME/KDE).
• macOS — baixa o binário pra ~/.cargo/bin/mclovin, remove o xattr de quarentena do Gatekeeper, cria ~/Applications/mclovin.app e abre Ajustes do Sistema → Mesa e Dock. Selecione mclovin em "Navegador padrão" pra finalizar (macOS 26 não deixa apps unsigned setarem o default programaticamente). Depois disso, abre o mclovin pelo Spotlight ou Dock.

Como usar

O mclovin é a mesma coisa por dois caminhos: a GUI com setas + Enter, ou a CLI pra scriptar. As regras estão sempre no rules.toml, então o que muda é só como você chega lá.

Como funciona

[clique no link]
      ↓
[OS chama o handler http/https = mclovin]
      ↓
[mclovin lê ~/.config/mclovin/rules.toml]
      ↓
   ┌──────────────────────┐
   │ alguma regra bate?   │
   └──────────────────────┘
      sim ↓                 não ↓
[abre o browser/comando]   [picker pergunta]

O mclovin é um único binário Rust com dois frontends compartilhando o mesmo core: CLI (scripts) e GUI (mclovin settings). As regras vivem em disco no rules.toml, então qualquer frontend lê a mesma realidade.

Atualizações automáticas

O mclovin faz check de novas versões em background a cada 2 horas, contra o repositório mclovin-release. Pra desligar: auto_update_check = false em ~/.config/mclovin/preferences.toml.

Pra forçar um check, abre Atualizações e clica em "Verificar atualizações". O botão tem debounce de 10 segundos entre clicks consecutivos pra evitar spam na API do GitHub.

Quando há versão nova:

1. Tela mostra versão atual → versão nova em amarelo
2. Click em "Atualizar agora" baixa o binário, valida o sha256, e instala
3. Aparece um countdown Reiniciando em 5… 4… 3… 2… 1…
4. O mclovin reinicia sozinho na nova versão, voltando pra mesma tela onde você estava

Se você clica Ctrl+U no picker, o mclovin lembra disso através do restart e te traz de volta pro picker quando você dá Esc na tela de Atualizações.

Avançado — só pelo terminal

Coisas que a GUI não expõe e que moram direto no ~/.config/mclovin/rules.toml. Edite com mclovin settings → "Abrir arquivo de configuração" ou com o seu editor preferido.

Referência do rules.toml

Cada regra é um bloco [[handler]] no arquivo. As três formas de match abaixo são as mesmas que a GUI expõe — aqui você vê o equivalente em TOML.

# Substring — mais comum
[[handler]]
match = "github.com"
browser = "brave"
description = "GitHub no Brave"

# Lista — qualquer item bate
[[handler]]
match = ["wa.me", "web.whatsapp.com", "api.whatsapp.com"]
command = "zapzap"
description = "WhatsApp via ZapZap"

# Regex — controle total + capture groups
[[handler]]
match_regex = '^https?://open\.spotify\.com/(\w+)/([^?#/]+)'
rewrite = "spotify --uri=spotify:{1}:{2}"
description = "Spotify desktop"

Browser vs comando

# Browser detectado pelo mclovin (lê o .desktop)
browser = "brave"

# Browser + profile específico
browser = { name = "google-chrome", profile = "Trabalho" }

# Comando shell raw (use {url} pra inserir a URL)
command = "firefox --new-window {url}"

Fallback e regra catch-all

fallback_browser = "brave"

# OU: regra catch-all (toda URL sem regra cai em Brave, sem picker)
[[handler]]
match_regex = '.*'
browser = "brave"

Picker externo (fuzzel, walker, wofi, rofi, bemenu)

Em vez do picker built-in (iced), você pode delegar pra um launcher do sistema:

[picker]
enabled = true
command = "fuzzel"
options = ["--dmenu"]

O launcher recebe as opções via stdin e retorna a escolha via stdout — convenção dmenu. Para desabilitar o picker totalmente (e jogar tudo no fallback_browser): enabled = false.

Regras dinâmicas com Lua (match_lua)

Quando o match não cabe em substring/regex — horário, host parseado, query string — escreva uma função Lua:

# Atlassian só no horário comercial
[[handler]]
match_lua = """
local h = ctx.now.hour
return (h >= 9 and h < 18) and ctx.url.host:match('atlassian') ~= nil
"""
browser = { name = "google-chrome", profile = "Trabalho" }
description = "Atlassian em horário comercial"

ctx carrega url (com .full, .host, .path, .query), now (.hour, .minute, .weekday) e source (app que originou o link, quando disponível).

Transformação complexa com rewrite_lua

Pra reescrever a URL de forma que regex+template não dão conta (assinaturas, decodificação, lookups):

[[handler]]
match = "internal.api.example"
rewrite_lua = """
return ctx.url.full:gsub('^http://', 'https://'):gsub('/v1/', '/v2/')
"""
browser = "brave"

Modo webapp (mclovin --app=URL)

Abre uma URL como aplicação dedicada (janela sem barra de endereço, ícone próprio na barra de tarefas) usando o [webapp].browser configurado:

mclovin --app=https://meet.google.com/abc-xyz

Útil pra criar atalhos .desktop de webapps. Em Omarchy, integre via mclovin webapp-fix (uma vez) pra que o launcher do Omarchy também reconheça o mclovin como handler de webapps.

Mais receitas

mclovin examples imprime três blocos prontos pra copiar/colar: substring/list básico, regex+rewrite, e cenários Lua mais elaborados.

Solução de problemas

Onde ficam os arquivos

Diagnosticar

mclovin doctor          # checagem completa
mclovin log -f          # acompanha o log em tempo real
mclovin --version       # versão do binário em $PATH
mclovin match https://github.com/foo/bar    # mostra qual regra bateria

"Versão errada" depois de atualizar

Pode ter dois binários no sistema (~/.local/bin/mclovin e ~/.cargo/bin/mclovin se você instalou com cargo install antes). O setup aponta tudo pro canônico em ~/.local/bin/, mas vale conferir:

which -a mclovin
ls -la ~/.local/bin/mclovin ~/.cargo/bin/mclovin 2>/dev/null

Se tiver dois, copia o mais novo por cima do antigo:

install -m 755 ~/.local/bin/mclovin ~/.cargo/bin/mclovin

Resetar o check de atualização

rm ~/.cache/mclovin/update_check.toml

Próxima vez que abrir, o mclovin re-checa o release público.

Qualquer problema, abra uma issue no GitHub.