Archivist

Español

Archivist es un componente portable de Git hooks para registrar prompts de IA por commit.

Qué hace

• pre-commit
  • Ejecuta gga run si ARCHIVIST_RUN_GGA=true.
  • Captura un prompt opcional desde la terminal (Ctrl+D para terminar).
  • Si no hay TTY interactiva, continúa el commit sin prompt.
• commit-msg
  • Valida la primera línea real del mensaje con:
    • <type>: <mensaje>
    • <type>(<scope>): <mensaje>
  • Si está vacío o no cumple formato, intenta autocorregir con IA si ARCHIVIST_AUTOFIX_COMMIT_MESSAGE=true.
• post-commit
  • Si hubo prompt, crea un markdown en ARCHIVIST_PROMPT_DIR.
  • Incluye commit SHA, commit message, resumen IA y prompt.
  • Deja el archivo staged para el siguiente commit.

Requisitos

• Git
• opencode instalado y configurado (resumen IA y autocorrección de commit message)
• gga si ARCHIVIST_RUN_GGA=true

Instalación

Instalación recomendada (standalone, para cualquier proyecto):

bash archivist-installer.sh

Qué hace exactamente:

• extrae una carpeta archivist/ completa desde el payload embebido en el script
• si ya existe archivist/:
  • sin opciones: falla y muestra alternativas
  • con --force: borra archivist/ completo y reinstala
  • con --update: borra y reinstala archivist/, preservando prompts guardados.
• ejecuta archivist/core/install.sh (leer sección de instalación directa)

Instalación directa

Cuando ya tienes archivist/ en el repo actual.

bash archivist/core/install.sh

Esto:

• crea hooks de Archivist faltantes en .githooks/
• no sobrescribe hooks ajenos existentes en .githooks/
• configura core.hooksPath=.githooks (config local de Git)
• crea archivist/core/archivist.env desde el ejemplo si no existe
• utiliza --update para refrescar hooks de Archivist

Actualizaciones:

bash archivist-installer.sh --update

Reemplaza toda la carpeta archivist/, preservando ai-prompts y archivist.env.

bash archivist-installer.sh --force

Reemplaza toda la carpeta archivist/, igual que en una nueva instalación.

bash archivist/core/install.sh --update

Desinstalación

bash archivist/core/uninstall.sh

Esto elimina wrappers de .githooks/ y deshace core.hooksPath si estaba en .githooks. Solo elimina wrappers gestionados por Archivist; hooks ajenos se conservan. Si .githooks aún contiene hooks, mantiene core.hooksPath=.githooks. No elimina la carpeta archivist/ ni tus archivos de configuración.

Configuración

Archivo: archivist/core/archivist.env

• ARCHIVIST_PROMPT_DIR (default: archivist/ai-prompts)
• ARCHIVIST_RUN_GGA (default: true)
• ARCHIVIST_AUTOFIX_COMMIT_MESSAGE (default: true)
• ARCHIVIST_OPENCODE_BIN (default: opencode)
• ARCHIVIST_GGA_BIN (default: gga)

Override local opcional: archivist/core/archivist.local.env.

Formato de archivo generado

Nombre:

• YYYY-MM-DD_HH-MM-SS_<short-sha>.md

Contenido:

• # Commit: <full-sha>
• Capturado: <timestamp>
• # Commit Message
• # Resumen
• # Prompt

Más detalles de formato en ai-prompts/README.md.

Regenerar instalador

bash archivist/core/rebuild-installer.sh

Modo plantilla (sin archivist/core/archivist.env ni prompts históricos):

bash archivist/core/rebuild-installer.sh --template

Si archivist-installer.sh no existe, rebuild-installer.sh lo crea automáticamente.

English

Archivist is a portable Git hooks component that records AI prompts per commit.

What it does

• pre-commit
  • Runs gga run when ARCHIVIST_RUN_GGA=true.
  • Captures an optional prompt from the terminal (Ctrl+D to finish).
  • If no interactive TTY is available, the commit continues without a prompt.
• commit-msg
  • Validates the first real commit line using:
    • <type>: <message>
    • <type>(<scope>): <message>
  • If empty or invalid, it tries AI auto-fix when ARCHIVIST_AUTOFIX_COMMIT_MESSAGE=true.
• post-commit
  • If a prompt was captured, creates a markdown file in ARCHIVIST_PROMPT_DIR.
  • Includes commit SHA, commit message, AI summary, and prompt.
  • Stages that file for the next commit.

Requirements

• Git
• opencode installed and configured (AI summary and commit-message auto-fix)
• gga if ARCHIVIST_RUN_GGA=true

Install

Recommended install (standalone, for any repository):

bash archivist-installer.sh

What it does:

• extracts a full archivist/ directory from the script's embedded payload
• if archivist/ already exists:
  • with no option: fails and shows alternatives
  • with --force: deletes archivist/ and reinstalls from scratch
  • with --update: deletes and reinstalls archivist/, preserving saved prompts.
• runs archivist/core/install.sh (see direct install section)

Direct install

When archivist/ already exists in the current repository.

bash archivist/core/install.sh

This:

• creates missing Archivist hooks in .githooks/
• does not overwrite existing non-Archivist hooks in .githooks/
• sets core.hooksPath=.githooks (local Git config)
• creates archivist/core/archivist.env from the example if missing
• use --update to refresh Archivist hooks

Updates:

bash archivist-installer.sh --update

Replaces the entire archivist/ directory while preserving ai-prompts and archivist.env.

bash archivist-installer.sh --force

Replaces the entire archivist/ directory, same as in a fresh installation.

bash archivist/core/install.sh --update

Uninstall

bash archivist/core/uninstall.sh

This removes .githooks wrappers and unsets core.hooksPath when it is .githooks. It only removes Archivist-managed wrappers; non-Archivist hooks are preserved. If .githooks still has hooks, core.hooksPath=.githooks is kept. It does not remove archivist/ nor your local config files.

Configuration

File: archivist/core/archivist.env

• ARCHIVIST_PROMPT_DIR (default: archivist/ai-prompts)
• ARCHIVIST_RUN_GGA (default: true)
• ARCHIVIST_AUTOFIX_COMMIT_MESSAGE (default: true)
• ARCHIVIST_OPENCODE_BIN (default: opencode)
• ARCHIVIST_GGA_BIN (default: gga)

Optional local override: archivist/core/archivist.local.env.

Generated file format

Filename:

• YYYY-MM-DD_HH-MM-SS_<short-sha>.md

Content:

• # Commit: <full-sha>
• Capturado: <timestamp>
• # Commit Message
• # Resumen
• # Prompt

See ai-prompts/README.md for output details.

Rebuild installer

bash archivist/core/rebuild-installer.sh

Template mode (without archivist/core/archivist.env and historical prompts):

bash archivist/core/rebuild-installer.sh --template

If archivist-installer.sh is missing, rebuild-installer.sh creates it automatically.