xfetch tiene un sistema de plugins que permite extender la funcionalidad a través de ejecutables independientes. Los plugins se comunican con el núcleo mediante un protocolo JSON sobre stdin/stdout.
Los plugins son ejecutables independientes llamados xfetch-plugin-<nombre> (o xfetch-plugin-<nombre>.exe en Windows). Son iniciados como procesos hijo por el núcleo de xfetch.
núcleo xfetch ---> stdin (petición JSON) ---> proceso plugin
núcleo xfetch <--- stdout (respuesta JSON) <--- proceso plugin
núcleo xfetch <--- stderr (mensajes error) <--- proceso plugin
Hay dos tipos de plugins:
| Tipo | Identificador | Propósito |
|---|---|---|
| Animación de Logo | logo_animation | Anima logos ASCII con efectos de color |
| Proveedor de Información | info_provider | Devuelve líneas de información del sistema o externas |
Versión del Protocolo: 1
Petición:
{
"version": 1,
"kind": "info_provider",
"args": {
"username": "xscriptor",
"max_lines": 3
}
}
El campo args contiene argumentos específicos del plugin provenientes de la configuración. Si no se configuran argumentos, args es null.
Respuesta:
{
"lines": [
"\uf09b X (@xscriptor)",
"\uf005 114 stars",
"\uf441 33 repos"
]
}
Petición:
{
"version": 1,
"kind": "logo_animation",
"lines": [
" __ __",
" \\ \\/ /",
" \\ /"
],
"frames": [
["frame 1 line 1", "frame 1 line 2"],
["frame 2 line 1", "frame 2 line 2"]
],
"args": {
"fps": 12,
"duration_ms": 1200,
"loop": false,
"style": "sweep"
}
}
El campo lines contiene el logo ASCII actual. El campo frames contiene conjuntos de fotogramas precargados opcionales. El campo args contiene parámetros de animación.
Respuesta:
{
"frames": [
{
"delay_ms": 83,
"lines": ["\u001b[31mcolored line\u001b[0m", "\u001b[32mnext line\u001b[0m"]
}
]
}
Cada fotograma tiene un delay_ms (cuánto tiempo mostrar el fotograma) y lines (el contenido del fotograma, potencialmente con códigos de escape ANSI para colores).
Los plugins deben escribir mensajes de error a stderr y salir con un código de estado distinto de cero en caso de fallo.
Al ejecutar un plugin, xfetch busca el binario en este orden:
xfetch-plugin-<nombre> en $PATH~/.config/xfetch/plugins/ (Linux/macOS) o %APPDATA%/xfetch/plugins/ (Windows)./plugins/<nombre>/target/release/# Instalar desde un directorio local
xfetch plugin install ./my-plugin
# Instalar desde el repositorio oficial de plugins
xfetch plugin install animate-logo
# Instalar desde un repositorio git personalizado
xfetch plugin install my-plugin --repo https://github.com/user/plugins.git
./<nombre>/, ./plugins/<nombre>/ o ./plugins/plugins/<nombre>/https://github.com/xfetch-cli/plugins.git por defecto)cargo build --release en el directorio del plugin~/.config/xfetch/plugins/xfetch-plugin-<nombre># Listar plugins instalados
xfetch plugin list
# Eliminar un plugin
xfetch plugin remove animate-logo
Cada plugin tiene su propia página de referencia con detalles completos de configuración, argumentos y ejemplos de salida.
| Plugin | Tipo | Descripción |
|---|---|---|
| animate-logo | logo_animation | Logos ASCII animados con efectos de color (sweep, wave, rainbow, sparkle, breathing, frame) |
| docker | info_provider | Estadísticas de contenedores Docker (total, running, paused, stopped) |
| github-stats | info_provider | Estadísticas de perfil de GitHub (stars, repos, PRs, issues, followers) |
| music-player | info_provider | Música reproduciéndose actualmente desde MPD y/o Spotify |
| weather | info_provider | Clima actual vía wttr.in (condición, temp, viento, humedad) |
| timezone | info_provider | Hora local, fecha, zona horaria y offset UTC |
| user-info | info_provider | Información de cuenta de usuario (UID, GID, home, shell, grupos) |
| display-resolution | info_provider | Resolución y tasa de refresco del monitor (multiplataforma) |
| theme-detection | info_provider | Detección de tema del escritorio (GTK, KDE Plasma) |
| theme-manager | info_provider | Explorador e instalador de temas del registro |
| chocolatey | info_provider | Conteo de paquetes de Chocolatey (Windows) |
| temperature | info_provider | Temperatura de CPU/SoC desde las zonas térmicas del kernel |
xfetch-plugin-<nombre> (Linux/macOS)
xfetch-plugin-<nombre>.exe (Windows)
[package]
name = "xfetch-plugin-my-plugin"
version = "0.1.0"
edition = "2024"
[dependencies]
serde = { version = "1", features = ["derive"] }
serde_json = "1"
xfetch-plugin-api = { git = "https://github.com/xfetch-cli/api", package = "xfetch-plugin-api" }
use xfetch_plugin_api::{
read_info_plugin_args_or_default,
write_info_lines,
};
#[derive(Debug, Default, serde::Deserialize)]
struct PluginArgs {}
fn main() {
let _args = match read_info_plugin_args_or_default::<PluginArgs>() {
Ok(value) => value,
Err(err) => {
eprintln!("{}", err);
std::process::exit(1);
}
};
if let Err(err) = write_info_lines(vec!["Hello from plugin".to_string()]) {
eprintln!("{}", err);
std::process::exit(1);
}
}
# Probar un plugin de información
echo '{"version":1,"kind":"info_provider","args":null}' \
| ./target/release/xfetch-plugin-my-plugin
# Probar un plugin de animación de logo
echo '{"version":1,"kind":"logo_animation","lines":["hello"],"args":{"fps":12}}' \
| ./target/release/xfetch-plugin-my-plugin
El crate xfetch-plugin-api (fuente en github.com/xfetch-cli/api) proporciona todos los tipos y ayudantes necesarios para el desarrollo de plugins:
AnimationFrame, EmptyArgs, InfoPluginRequest, InfoPluginResponse, LogoAnimationArgs, LogoAnimationRequest, LogoAnimationResponse, PluginKindread_logo_animation_request(), read_info_plugin_request(), read_info_plugin_args_or_default(), write_logo_animation_frames(), write_info_lines()read_json_from_stdin(), write_json_to_stdout()with_timeout() y el error TimedOut — ejecutan el trabajo del plugin bajo un presupuesto de tiempo y responden con elegancia cuando se agotaPluginApiError con variantes Io, Serialize, Deserialize, InvalidProtocolVersion, InvalidPluginKind, InvalidArgs, EmptyAnimationFramesLa clave de configuración opcional timeout_secs aplica a info_plugins, logo_animation y config_providers como red de seguridad en segundos: el núcleo mata el proceso del plugin si tarda más, mientras que el presupuesto with_timeout propio del plugin es el control principal.
xfetch-plugin-api para los tipos de protocolo