Manual

¿Por qué existe mclovin?

mclovin nació de tres molestias diarias: links de Spotify abriéndose en el navegador en vez de la app, links del repo del trabajo cayendo en el profile equivocado de Chrome, links de Google Meet del cliente abriéndose donde está la cámara del trabajo. En macOS lo resolvía con Finicky y creía que estaba en paz.

Con IA acelerando el prototipo, la primera versión funcionó en pocos minutos y resolvió mi propio setup. Resolverlo solo para mí era poco. Pasé más tiempo puliéndolo hasta convertirlo en algo que cualquier persona con el mismo problema puede usar.

La misión es cubrir los tres sistemas y, en el camino, exponer lo que los sistemas operativos y los navegadores llevan demasiado tiempo sin resolver. Linux x86_64 y macOS Apple Silicon ya están funcionando; Windows es el siguiente. ¿Algún problema? Abre una issue en GitHub. Haces clic en un link y se abre en el lugar correcto. Sin preguntar qué profile, sin cerrar la ventana incorrecta, sin perder dos minutos por cada link.

Instalación

Linux x86_64 y macOS arm64 (Apple Silicon). Windows es el siguiente.

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

El script detecta tu plataforma y hace lo correcto:

• Linux — descarga el binario a ~/.local/bin/mclovin, registra mclovin como navegador predeterminado del sistema, e instala el atajo mclovin.desktop en el menú de apps. Abre mclovin desde el launcher (Walker, rofi, menú de apps de GNOME/KDE).
• macOS — descarga el binario a ~/.cargo/bin/mclovin, elimina el xattr de cuarentena de Gatekeeper, crea ~/Applications/mclovin.app y abre Configuración del Sistema → Escritorio y Dock. Selecciona mclovin en "Navegador web predeterminado" para terminar (macOS 26 no permite que apps sin firma establezcan el predeterminado programáticamente). Después, abre mclovin desde Spotlight o el Dock.

Cómo usar

mclovin es lo mismo por dos caminos: la GUI con flechas + Enter, o la CLI para scriptar. Las reglas viven siempre en rules.toml, así que lo único que cambia es cómo llegas a ellas.

Cómo funciona

[clic en un link]
        ↓
[el SO entrega el http/https a mclovin]
        ↓
[mclovin lee ~/.config/mclovin/rules.toml]
        ↓
   ┌──────────────────────┐
   │ ¿alguna regla coincide? │
   └──────────────────────┘
       sí ↓                 no ↓
[abre el browser/comando]   [el picker pregunta]

mclovin es un único binario Rust con dos frontends que comparten el mismo core: CLI (scripts) y GUI (mclovin settings). Las reglas viven en disco en rules.toml, así que cualquier frontend lee la misma realidad.

Actualizaciones automáticas

mclovin verifica nuevas versiones en background cada 2 horas, contra el repo mclovin-release. Para apagarlo: auto_update_check = false en ~/.config/mclovin/preferences.toml.

Para forzar una verificación, abre Actualizaciones y haz clic en "Buscar actualizaciones". El botón tiene debounce de 10 segundos entre clics consecutivos para no saturar la API de GitHub.

Cuando hay versión nueva:

1. La pantalla muestra versión actual → versión nueva en amarillo
2. Clic en "Instalar ahora" descarga el binario, valida el sha256 e instala
3. Aparece una cuenta regresiva: Reiniciando en 5… 4… 3… 2… 1…
4. mclovin se reinicia solo en la nueva versión, volviendo a la misma pantalla

Si llegaste a Actualizaciones por Ctrl+U desde el picker, mclovin recuerda eso a través del reinicio y te devuelve al picker al presionar Esc en Actualizaciones.

Avanzado — solo terminal

Cosas que la GUI no expone, todas en ~/.config/mclovin/rules.toml. Edítalo vía mclovin settings → "Abrir archivo de configuración" o con tu editor.

Referencia de rules.toml

Cada regla es un bloque [[handler]]. Los tres tipos de match abajo son los mismos que la GUI expone — aquí el equivalente en TOML.

# Substring — el más común
[[handler]]
match = "github.com"
browser = "brave"
description = "GitHub en Brave"

# Lista — cualquier elemento coincide
[[handler]]
match = ["wa.me", "web.whatsapp.com", "api.whatsapp.com"]
command = "zapzap"
description = "WhatsApp vía ZapZap"

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

Browser vs comando

# Browser detectado por mclovin (lee el .desktop)
browser = "brave"

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

# Comando shell raw (usa {url} para insertar la URL)
command = "firefox --new-window {url}"

Fallback y catch-all

fallback_browser = "brave"

# O: regla catch-all (toda URL sin regla cae en Brave, sin picker)
[[handler]]
match_regex = '.*'
browser = "brave"

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

En vez del picker built-in (iced), puedes delegar a un launcher del sistema:

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

El launcher recibe opciones por stdin y devuelve la elección por stdout — convención dmenu. Para deshabilitar el picker totalmente (y mandar todo a fallback_browser): enabled = false.

Reglas dinámicas con Lua (match_lua)

Cuando el match no encaja en substring/regex — horario, host parseado, query string — escribe un snippet Lua:

# Atlassian solo en horario laboral
[[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 = "Trabajo" }
description = "Atlassian en horario laboral"

ctx carga url (con .full, .host, .path, .query), now (.hour, .minute, .weekday) y source (la app que originó el link, cuando disponible).

Transformaciones complejas con rewrite_lua

Para reescribir URLs de formas que regex + template no resuelven (firmar, decodificar, 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 una URL como app dedicada (ventana sin barra de direcciones, ícono propio en la barra de tareas) usando el [webapp].browser configurado:

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

Útil para crear .desktop shortcuts. En Omarchy, integra con mclovin webapp-fix (una vez) para que el launcher del Omarchy también reconozca mclovin como handler de webapps.

Más recetas

mclovin examples imprime tres bloques copy-paste: substring/list básico, regex + rewrite, y escenarios Lua más elaborados.

Solución de problemas

Dónde viven los archivos

Diagnosticar

mclovin doctor          # chequeo completo
mclovin log -f          # sigue el log del día en vivo
mclovin --version       # binario en $PATH
mclovin match https://github.com/foo/bar    # qué regla coincidiría

"Versión equivocada" después de actualizar

Puedes tener dos binarios en el sistema (~/.local/bin/mclovin y ~/.cargo/bin/mclovin si instalaste con cargo install antes). setup apunta todo al canónico ~/.local/bin/, pero vale revisar:

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

Si hay dos, copia el más nuevo sobre el viejo:

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

Resetear el cache de actualización

rm ~/.cache/mclovin/update_check.toml

En el siguiente arranque, mclovin re-consulta el release público.

¿Algún problema? Abre una issue en GitHub.