Guía

1 · Instalar y primer arranque

Tres instaladores, publicados en cada release etiquetada. Coge el tuyo de la última release.

No hay build para Mac Intel, ni .deb, .rpm o .msi. Tanto gh como glab van dentro de cada instalador, así que no hay nada más que descargar.

Pasar el aviso del primer arranque

Las builds no están firmadas, así que macOS y Windows las paran una vez. La descarga no tiene nada raro — el aviso existe porque no hay un certificado detrás.

macOS — arrastra la app a /Applications y luego haz clic derecho y elige Abrir, o quita la marca de cuarentena:

xattr -dr com.apple.quarantine /Applications/BeardGit.app

Windows — SmartScreen → Más información → Ejecutar de todas formas. No lo volverá a preguntar en ese equipo.

Linux — marca el AppImage como ejecutable y ábrelo:

chmod +x BeardGit-*.AppImage
./BeardGit-*.AppImage

Una cosa que conviene comprobar

BeardGit lee tus repositorios con libgit2, pero cada escritura — commit, push, rebase, merge — ejecuta tu propio git. Tiene que estar en el PATH, y la app no lo comprueba al arrancar: si falta, lo que falla es el primer commit, no el arranque. git --version en una terminal es toda la prueba. Lo que sí arregla BeardGit por su cuenta es el PATH vacío que un lanzador de escritorio le entrega a una app gráfica, así que abrirla desde Finder o desde el dock sigue encontrando tus herramientas.

2 · Abrir tu primer repositorio

La pantalla de bienvenida tiene tres entradas: abrir una carpeta, clonar una URL o elegir uno que ya tenías abierto. Cada repositorio es una pestaña, y solo la pestaña activa mantiene su estado pesado — el layout del grafo, el vigilante de ficheros — así que una docena de repos abiertos cuesta más o menos lo que uno.

• Abre una carpeta que todavía no sea un repositorio y BeardGit se ofrece a montarlo de una pasada: git init, poner un .gitignore, hacer el primer commit, crear el repo equivalente en GitHub o GitLab, conectar el remoto y hacer push. Cada paso es opcional, y si uno falla los anteriores se quedan hechos.
• Pestañas — ⌘Tab y ⌘⇧Tab se mueven entre ellas, ⌘W cierra la activa, y arrastrar una pestaña la reordena.
• Las secciones recuerdan dónde las dejaste durante la sesión: filtros, posiciones de scroll, anchos de panel, carpetas plegadas y borradores a medio escribir como un mensaje de commit o un comentario de review. Por pestaña de repositorio, se descarta al cerrarla y nunca se escribe en disco.

Los cambios externos se recogen solos. Un commit que hagas en una terminal, una rama que haya subido un compañero, un fichero que haya reescrito otro programa — un vigilante con rebote lo detecta y las vistas se refrescan, también dentro de worktrees enlazados y submódulos.

3 · Conectar GitHub o GitLab

BeardGit habla con los dos a través de gh y glab, y usa sus propias copias incluidas en vez de lo que tengas en el PATH — las mismas versiones para todo el mundo. Entrar es el flujo normal de la CLI:

1. Ajustes → Integraciones → el forge que quieras, y Log in. Se abre una pestaña de terminal que ejecuta auth login sobre el binario incluido, así que funciona incluso si nunca has instalado gh ni glab por tu cuenta.
2. Sigue lo que te pregunte la CLI. Tus credenciales van donde las guarda esa CLI — tu propia configuración y el keyring del sistema, indexadas por host — no a BeardGit.
3. Abre un repositorio cuyo origin apunte a ese host y aparecen las vistas del forge: pull o merge requests, issues, pipelines, releases, ajustes del repo.

Lo autoalojado funciona tal cual. GitHub Enterprise y GitLab on-prem son hosts normales aquí. La autenticación se comprueba por host, así que un forge que solo responde en la VPN no puede tapar a otro que sí, y un gitlab.com personal más un GitLab corporativo pueden estar conectados a la vez.

Si además guardas un token de acceso personal en BeardGit, se cifra en tu máquina — mira dónde viven tus datos. Apagar la integración en Ajustes hace que la app deje de validar esos tokens al arrancar y de resolver tu remoto contra la API del forge; no se borra nada, y al volver a encenderla se reconecta.

4 · Configurar un CLI de AI

BeardGit no tiene modelo ni clave de API propia. Ejecuta tu instalación de Claude Code, Codex u OpenCode, que ya tienen su propia autenticación. Instala uno, comprueba que funciona en una terminal y BeardGit lo encuentra: al arrancar busca los tres en tu PATH y les pide --version. En Ajustes → AI eliges el proveedor preferido y vuelves a lanzar esa detección.

Ejecuciones en segundo plano

Lo interesante son las ejecuciones en segundo plano. Le das un prompt y arranca en una rama nueva, ai/<proveedor>/<slug>, en un worktree de git propio — por defecto bajo .beardgit/ai-worktrees/, y puedes apuntarlo a otro sitio en Ajustes. Tu copia de trabajo no se toca mientras trabaja. Las ejecuciones se encolan contra un límite de concurrencia que tú fijas (tres por defecto).

Cuando termina puedes leer la transcripción, mirar el diff y luego mergear la rama, conservar el worktree para después o descartarlo. La ejecución también escribe un informe en Markdown en .beardgit/ai-reports/ del repositorio padre, así que descartar el worktree no se lleva el informe por delante.

Las acciones pequeñas de AI

Desde cualquier vista, el proveedor activo puede redactar un mensaje de commit, revisar lo que tienes preparado o revisar una pull request. Los prompts van por stdin, así que un diff grande se revisa completo en vez de cortarse en el límite de la línea de comandos, y una review guardada acaba en .beardgit/reviews/. Cada acción comprueba antes que haya algo de lo que hablar, así que nunca recibes una respuesta sobre un diff vacío.

Nada de esto tiene que estar encendido. Un interruptor en Ajustes → General → Integraciones apaga todo el lado de AI: sin sondear CLIs al arrancar, sin vistas de AI, sin acciones de AI y sin vigilar procesos. Lo que ya esté en marcha termina, y el historial sigue legible.

5 · El espacio .http

Las peticiones viven en el repositorio, como ficheros normales bajo .beardgit/requests/. Commitéalos y el resto del equipo los recibe con un git pull. El panel siembra una colección Quickstart pequeña la primera vez que lo abres, para que haya algo que ejecutar desde el minuto uno.

El formato del fichero

Una petición es un nombre, un método y una URL, cabeceras, una línea en blanco y el cuerpo:

# @name Create a post
POST {{base_url}}/posts
Content-Type: application/json
Authorization: Bearer {{api_token}}

{
  "title": "hello from BeardGit",
  "userId": 1
}

Lo que acepta el parser, exactamente:

• GET POST PUT PATCH DELETE HEAD OPTIONS, sin distinguir mayúsculas. Cualquier otra cosa es un error con su número de línea.
• Las cabeceras van hasta la primera línea en blanco, como Nombre: valor.
• Todo lo que hay tras esa línea en blanco es el cuerpo, tal cual — ahí los comentarios no se quitan.
• Las líneas que empiezan por # o // son comentarios, antes de la línea de petición y entre las cabeceras.
• # @name Algo nombra la petición. Solo así — // @name no hace nada.
• Una línea que empieza por ### separa bloques, y el resto de esa línea es un nombre.

Una petición por fichero, por ahora. El parser entiende varios bloques, pero el panel ejecuta el primero. No hay scripts, ni asserts, ni declaraciones @variable dentro de un fichero .http.

Variables y entornos

Un entorno es un fichero JSON en .beardgit/requests/_env/<nombre>.json, y el nombre del fichero es el nombre del entorno:

{
  "$schema": "beardgit-env/v1",
  "vars": {
    "base_url": "https://api.example.com",
    "post_id": "1"
  },
  "secrets": ["api_token"]
}

Las vars son texto plano y se pueden commitear. secrets lista solo nombres — los valores se cifran en tu máquina, nunca en el fichero. {{nombre}} se sustituye en la URL, en el nombre y el valor de cada cabecera y en el cuerpo, y se resuelve en este orden: primero un override que escribas en el panel para esa ejecución, luego un secreto, luego una variable. Un nombre que no resuelva hace fallar la petición en vez de mandar una cadena vacía sin decir nada.

Qué entorno está activo no se guarda en el repositorio — vive en la base de datos local de BeardGit, así que dos personas que comparten los mismos ficheros pueden estar apuntando a entornos distintos.

Límites que conviene saber antes de culpar a la app

• Las direcciones de loopback y privadas se rechazan. Una petición a localhost, a un host 192.168.* o a una dirección link-local se bloquea salvo que abras la app con BEARDGIT_REQUESTS_ALLOW_PRIVATE=1. Es una protección para que un fichero de petición commiteado no alcance tu propia red, no un despiste.
• Timeout de 30 segundos, y los redirects no se siguen — ves el 301 y no lo que hay detrás.
• Los cuerpos de respuesta se guardan hasta 5 MiB y se marcan como truncados a partir de ahí.
• El historial guarda las últimas 50 ejecuciones por petición, con la petición tal como se envió — lo que significa que un secreto ya resuelto está en esa base de datos local en claro. No sale de tu máquina, pero está.
• El diff de respuestas compara cuerpos, no códigos de estado ni cabeceras.

6 · Temas, incluido el tuyo

Ajustes → Apariencia lista los 31 temas incluidos. Cada uno tiene una variante oscura y una clara que se emparejan, así que la app puede seguir a tu sistema. El tema colorea toda la app — incluidos la paleta de sintaxis del editor, los fondos de los diffs y los carriles del grafo.

Escribir uno

Pon un fichero .toml en la carpeta themes/ que está junto a tus ajustes (la ruta exacta está en § 9; la app escribe ahí un README con esta misma plantilla). El nombre del fichero da igual — el [meta] id es la identidad, y reutilizar el id de un tema incluido lo sustituye.

Solo hacen falta dos secciones: [meta] y los 18 colores de [colors].

[meta]
id = "mi-tema"
name = "Mi tema"
mode = "dark"            # "dark" o "light", nada más

[colors]
background = "#111111"
foreground = "#eeeeee"
black = "#333333"
red = "#ff0000"
green = "#00ff00"
yellow = "#ff8800"
blue = "#0000ff"
magenta = "#8800ff"
cyan = "#00ffff"
white = "#cccccc"
bright-black = "#999999"
bright-red = "#ff4444"
bright-green = "#44ff44"
bright-yellow = "#ffaa44"
bright-blue = "#4444ff"
bright-magenta = "#aa44ff"
bright-cyan = "#44ffff"
bright-white = "#ffffff"

Todo lo demás — acentos, niveles de texto, bordes, los diez carriles del grafo, los colores de sintaxis del editor — se deriva de esos. Puedes sobrescribir lo que quieras con las secciones opcionales [accents], [derived], [graph] y [editor], donde el valor que fijes se usa tal cual:

[accents]
primary = "cyan"          # un nombre ANSI (con guion bajo) o un hex

[derived]
text-secondary = "#969ead"

[graph]
lane-colors = ["#7aa2f7", "#9ece6a", "#ff9e64"]   # dos como mínimo
node-radius = 5.0

[editor]
added-bg = "#1b3829"
syntax-keyword = "#ff7b72"

Formatos de color: solo #RRGGBB, #RRGGBBAA y rgba(…). El hex corto (#abc) y rgb(…) se rechazan, y un fichero que no parsea se descarta sin decir nada — si tu tema no aparece en la lista, eso es lo primero que hay que mirar. Las dos formas, bright-black y bright_black, valen.

El informe de contraste

Al aplicar un tema, BeardGit mide cinco tokens — los tres niveles de texto y los dos de borde — contra cada superficie sobre la que se pintan, e informa de lo que quede por debajo del mínimo WCAG (4,5:1 para texto, 3,0:1 para el borde fuerte, 2,0:1 para el suave). Es solo informativo: el selector te dice qué tokens se quedan cortos y por cuánto, y aplica tu tema exactamente como lo escribiste. Los colores que no puede medir, como rgba(…), se listan como no auditados. Todos los temas incluidos superan el mínimo, y un test se encarga de que siga así.

7 · El teclado, completo

Esta es la lista completa de atajos registrados. ? dentro de la app muestra lo mismo, generado desde el mismo registro, y ⌘⇧P te permite ejecutar cualquiera por su nombre. En Linux y Windows, cada ⌘ de aquí es Ctrl.

Vistas

Git

Grafo

Pestañas, paneles y trabajo en segundo plano

Dentro de una lista

⌘Enter hace commit desde la caja del mensaje, pero ese está atado literalmente a la tecla Command, así que en Linux y Windows por ahora toca usar el botón.

8 · Un recorrido por Ajustes

• General → Integraciones — un interruptor para GitHub/GitLab y otro para la AI. Apagados, las superficies correspondientes desaparecen y no queda nada corriendo por detrás. Los dos apagados dejan un cliente solo de git. Tus cuentas y preferencias se conservan para cuando los vuelvas a encender.
• General → Actualizaciones — si se comprueban al arrancar, más el endpoint y la marca de la última comprobación, para distinguir un 404 de una falta de red.
• Apariencia — el tema, el emparejado para seguir al sistema y el informe de contraste del que esté aplicado.
• AI — qué proveedor preferir, cuántas ejecuciones en segundo plano pueden ir a la vez y dónde van sus worktrees.
• Git — el botón Probar firma, que firma un commit de usar y tirar y te muestra el error real si tu configuración de SSH, GPG o X.509 no está bien.
• Avanzado — el nivel de log (error, info o debug, aplicado en caliente), un botón para abrir la carpeta de logs y otro para vaciar los layouts de grafo en caché.
• Barra lateral — reordena la navegación, esconde lo que no usas, vuelve al orden original. Ese diseño es para toda la app.

9 · Dónde viven tus datos

En tu máquina

Una sola carpeta lo guarda todo:

Los logs están en otro sitio, un fichero por día llamado beardgit.<fecha>.log, y se purgan a la semana:

Los tokens, las cabeceras Authorization y las credenciales incrustadas en URLs se sustituyen por <redacted> al entrar en el fichero, así que un log que adjuntes a una issue no se lleva tus claves. La prosa, las URLs que pueden llevar una credencial y lo que escribes en la terminal se quedan fuera por diseño.

Cómo funciona el cifrado, y qué no hace

Los tokens se cifran con AES-256-GCM bajo una clave derivada de un identificador de la máquina — el UUID de plataforma en macOS, /etc/machine-id en Linux, el MachineGuid del registro en Windows. Eso significa que el fichero es inútil en otro ordenador: una copia perdida en un backup, en una carpeta sincronizada o en un commit por accidente no revela nada.

No es protección contra algo que se ejecute como tú en tu propia máquina: cualquier cosa con tu cuenta de usuario puede derivar la misma clave. Pasar al keychain del sistema es el siguiente paso previsto. Dicho claro, porque una afirmación de seguridad que hay que leerse el código para matizar no vale mucho.

Dentro de tu repositorio

Todo lo que BeardGit escribe en un proyecto va bajo .beardgit/:

El .gitignore que BeardGit puede escribir para un repositorio nuevo no menciona .beardgit/, así que las carpetas locales de arriba no quedan ignoradas por ti. Si quieres compartir tus peticiones pero no el espacio de trabajo de la AI, añade esto a mano:

.beardgit/ai-worktrees/
.beardgit/ai-reports/
.beardgit/reviews/

Qué manda la app por la red por su cuenta

Una cosa: la comprobación de actualizaciones, descrita en § 10. Con la integración de forge encendida también valida cada token guardado al arrancar y resuelve tu remoto origin contra la API del forge; con la AI encendida busca los tres CLIs en local, que es un subproceso, no una petición. Apaga las dos integraciones y la única salida que queda es el sondeo del updater — que tiene su propio interruptor. No hay telemetría, ni analítica, ni informes de errores en ninguna parte de la app.

10 · Actualizaciones

BeardGit comprueba una vez al arrancar, contra una única URL — el latest.json adjunto a la release más nueva de GitHub — y como mucho una vez por minuto entre reinicios. Nunca te pregunta en un diálogo que no hayas abierto: si hay una versión más nueva recibes un aviso discreto, e instalar es tu clic. Si la comprobación falla, falla en silencio en vez de darte la lata con tu red.

La numeración es año.mes.release, así que 26.9.1 es la segunda versión de septiembre de 2026. El updater solo ofrece algo estrictamente más nuevo, y Ajustes → General muestra el endpoint y la hora de la última comprobación para cuando necesites distinguir un 404 de un tropiezo del DNS. Si prefieres actualizar a mano, ahí mismo se apaga todo.

En macOS y Windows el instalador sustituye la app, y en Windows cierra BeardGit a mitad de la instalación — nada de lo que se muestre después de la descarga se llega a leer, y por eso el aviso de build sin firmar aparece antes de empezar.

11 · Cuando algo se porta mal

«BeardGit está dañado y no se puede abrir»

Es Gatekeeper, no una descarga mala. xattr -dr com.apple.quarantine /Applications/BeardGit.app, una vez.

Un commit, un push o un rebase falla pero las lecturas van bien

Las escrituras usan tu git del sistema. Comprueba git --version en una terminal — la app no lo verifica al arrancar.

Falla la firma de commits

Ajustes → Git → Probar firma. Firma un commit de usar y tirar y te muestra el error real de tu firmante, que casi siempre es una clave que falta o un agente que no está corriendo.

Las acciones de GitLab fallan y las de GitHub van bien

Desde 26.9.1 BeardGit usa su propio glab incluido, que arregló justo esto: un glab viejo en tu PATH no podía leer la configuración que escribe uno actual. Actualiza a la última versión.

La terminal destroza los acentos, o Ctrl+R y fzf dejan basura en pantalla

Corregido en 26.9.1. Abrir la app desde un lanzador dejaba al shell sin TERM ni locale, así que todo lo que dibuja en modo raw se rompía. Actualiza.

Una petición a localhost se rechaza

Es a propósito. Abre la app con BEARDGIT_REQUESTS_ALLOW_PRIVATE=1 para permitir loopback y direcciones privadas.

Mi tema no aparece en la lista

Un fichero de tema que no parsea se descarta sin mensaje. Las causas habituales son un hex corto tipo #abc, un valor rgb(…), un color que falta, o un mode que no sea exactamente dark o light.

El grafo se queda desactualizado tras un cambio hecho fuera de la app

Ajustes → Avanzado → vacía los layouts en caché y vuelve a abrir el repositorio. Si pasa dos veces, merece una issue.

Cualquier otra cosa

Ajustes → Avanzado → pon el nivel de log en debug, reprodúcelo y abre la carpeta de logs desde la misma página. Adjunta el fichero — está redactado — a una issue, con tu sistema y la versión que sale en Ayuda → Acerca de.

12 · Compilar desde el código

Necesitas Rust (la versión está fijada en rust-toolchain.toml), Node 22 y git.

git clone https://github.com/The3eard/BeardGit.git
cd BeardGit
npm install
npm run tauri dev

La primera build compila todos los crates de Rust y tarda unos minutos; a partir de ahí es rápido. npm run tauri build genera el instalador de tu plataforma.

Requisitos por plataforma:

• macOS — xcode-select --install
• Debian / Ubuntu — libwebkit2gtk-4.1-dev build-essential curl wget file libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev
• Arch — webkit2gtk-4.1 base-devel curl wget file openssl appmenu-gtk-module libappindicator-gtk3 librsvg xdotool
• Fedora — webkit2gtk4.1-devel openssl-devel curl wget file libappindicator-gtk3-devel librsvg2-devel libxdo-devel más el grupo de desarrollo de C
• Windows — MSVC Build Tools con «Desarrollo para el escritorio con C++», y el WebView2 Runtime

Las contribuciones son bienvenidas — CONTRIBUTING.md tiene las convenciones de ramas y los checks que tiene que pasar un cambio.

13 · Desinstalar

Quita la app como lo hace tu sistema: sácala de /Applications, borra el AppImage o usa Agregar o quitar programas. Eso deja tus datos a propósito. Para borrarlos también, elimina la carpeta de configuración y la de logs del § 9.

Dos cosas que conviene recordar antes: credentials.enc guarda tus tokens de forge y los secretos de las peticiones, y esos tokens siguen siendo válidos en el forge — revócalos allí si eso es lo que querías. Y todo lo que haya bajo .beardgit/ en un repositorio se queda con el repositorio hasta que lo borres, incluidos los worktrees de AI, que son worktrees de git de verdad. Quitarlos desde la vista de Worktrees deja la contabilidad de git en orden.