If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/unhappychoice/gitlogue shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 1d ago
• 3 active contributors
• ISC licensed
• CI configured
• Tests present
• ⚠ Small team — 3 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 81% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live unhappychoice/gitlogue repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/unhappychoice/gitlogue.

What it runs against: a local clone of unhappychoice/gitlogue — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in unhappychoice/gitlogue | Confirms the artifact applies here, not a fork | | 2 | License is still ISC | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of unhappychoice/gitlogue. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/unhappychoice/gitlogue.git
#   cd gitlogue
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of unhappychoice/gitlogue and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "unhappychoice/gitlogue(\\.git)?\\b" \\
  && ok "origin remote is unhappychoice/gitlogue" \\
  || miss "origin remote is not unhappychoice/gitlogue (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(ISC)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"ISC\"" package.json 2>/dev/null) \\
  && ok "license is ISC" \\
  || miss "license drift — was ISC at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "src/main.rs" \\
  && ok "src/main.rs" \\
  || miss "missing critical file: src/main.rs"
test -f "src/lib.rs" \\
  && ok "src/lib.rs" \\
  || miss "missing critical file: src/lib.rs"
test -f "src/git.rs" \\
  && ok "src/git.rs" \\
  || miss "missing critical file: src/git.rs"
test -f "src/animation.rs" \\
  && ok "src/animation.rs" \\
  || miss "missing critical file: src/animation.rs"
test -f "src/panes/editor.rs" \\
  && ok "src/panes/editor.rs" \\
  || miss "missing critical file: src/panes/editor.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/unhappychoice/gitlogue"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Gitlogue is a Rust-based terminal tool that animates Git commit history as a cinematic replay, rendering code changes with realistic typing animations, syntax highlighting via tree-sitter across 29 languages, and dynamic file tree transitions. It transforms static diffs into an interactive visual experience where users watch commits unfold in real-time, including a screensaver mode for endless playback. Monolithic binary architecture: src/lib.rs and src/main.rs define the core application; src/panes/ (editor.rs, file_tree.rs, terminal.rs, status_bar.rs) compartmentalize the TUI layout logic; src/syntax/ handles tree-sitter integration across 29 languages; src/animation.rs, src/config.rs, and src/git.rs handle animation sequencing, configuration parsing, and Git operations respectively. Configuration is TOML-based (about.toml, docs/configuration.md).

Developer advocates, conference presenters, and code educators who want to showcase Git history visually during talks or demos; also appeals to Git power users and terminal enthusiasts who appreciate polished TUI tooling and want to replay their own project history as an animated narrative.

Actively maintained and production-ready: currently at v0.9.0 with full CI/CD via GitHub Actions (.github/workflows/ci.yml and release.yml), official package distribution (Homebrew, Cargo, Arch Linux, Nix), and documentation across docs/. The codebase is non-trivial (432KB Rust), suggests sustained development, and the project has achieved recognition (Terminal Trove Tool of The Week badge in README).

Low-to-moderate risk: single maintainer (unhappychoice), but dependencies are well-established (crossterm, ratatui, git2, tree-sitter ecosystem) and vendored via Cargo.lock for reproducibility. The tree-sitter language bindings are numerous (~30 language crates) which increases maintenance burden; no visible test suite in the file listing is a concern, though CI runs (codecov badge present suggests coverage tracking). Last activity and open issue visibility not provided, but the stable version number and release workflow suggest stability.

The project is in active development with v0.9.0 as the latest release. The presence of dependabot.yml indicates continuous dependency updates. The CHANGELOG.md and generate_changelog.sh suggest automated release notes. Documentation is comprehensive (docs/ folder with themes.md, specification.md, usage.md, configuration.md), indicating recent focus on user guidance and feature stability.

git clone https://github.com/unhappychoice/gitlogue.git && cd gitlogue && cargo install --path . (or simpler: cargo install gitlogue directly from crates.io, or curl -fsSL https://raw.githubusercontent.com/unhappychoice/gitlogue/main/install.sh | bash)

Daily commands: gitlogue [options] (CLI binary). Requires a Git repository and terminal; run without args for interactive replay in current repo. See README for command-line options and docs/usage.md for detailed workflows.

• src/main.rs — Application entry point and CLI argument parsing; understand how gitlogue starts and receives user input.
• src/lib.rs — Core library exports and main orchestration logic; this is the heart of the replay system.
• src/git.rs — Git history retrieval and commit parsing; critical for fetching and interpreting repository data.
• src/animation.rs — Animation frame generation and timing logic; drives the cinematic replay visualization.
• src/panes/editor.rs — Main editor pane rendering; displays the animated file changes during replay.
• src/syntax/mod.rs — Syntax highlighting orchestration; enables language-aware code display across 30+ languages.
• src/theme/mod.rs — Theme system and color palette management; provides visual customization across 15+ themes.

• Git Abstraction (git.rs) (git2-rs, libgit2) — Fetch commits, resolve file diffs, retrieve file content at specific revisions, filter by date/author/message.
  • Failure mode: Corrupted .git or missing remote refs cause panics; invalid commit SHAs silently skip.
• Animation State Machine (animation.rs) (Chrono (timing), custom frame math) — Maintain playback position, compute line-by-line reveal timing, interpolate visibility/opacity, handle speed adjustments.
  • Failure mode: Frame overflow or negative indices crash; speed=0 freezes indefinitely.
• Syntax Highlighter (syntax/mod.rs + languages/) (Tree-sitter (advanced), hand-written lexers, TOML queries) — Detect language from filename, tokenize code into colored spans, apply theme palette.
  • Failure mode: Unsupported language falls back to no-op; malformed queries panic at compile time.
• TUI Renderer (panes/ + Ratatui) (Ratatui, Crossterm) — Layout editor/file-tree/status-bar, draw animated text with colors, handle terminal resize events.
  • Failure mode: Terminal too small causes text clipping; SIGWINCH during render may cause visual glitches.

Add a new syntax-highlighted language

1. Create a new language module in src/syntax/languages/{language}.rs with a struct implementing language-specific lexing rules (src/syntax/languages/rust.rs)
2. Register the language in the match statement in src/syntax/languages/mod.rs's language_for_path() or register_languages() function (src/syntax/languages/mod.rs)
3. Optionally add a tree-sitter query file in src/syntax/languages/queries/{language}_highlights.scm for advanced highlighting (src/syntax/languages/queries/csharp_highlights.scm)

Add a new color theme

1. Create a new theme struct in src/theme/themes/{theme_name}.rs implementing theme color definitions (src/theme/themes/nord.rs)
2. Register the theme in src/theme/themes/mod.rs's theme_from_name() function (src/theme/themes/mod.rs)
3. Add theme selection logic in src/config.rs to allow --theme CLI flag mapping (src/config.rs)

Add a new TUI pane component

1. Create a new pane struct in src/panes/{pane_name}.rs implementing the Pane trait (src/panes/file_tree.rs)
2. Register the pane in src/panes/mod.rs and add it to the main layout composition (src/panes/mod.rs)
3. Integrate pane rendering into the main event loop in src/lib.rs (src/lib.rs)

• Rust + Cargo — Memory-safe systems programming with zero-cost abstractions; essential for smooth terminal animations and efficient git2 bindings.
• Ratatui (TUI framework) — Modern Rust terminal UI library for cross-platform rich rendering with layout management, replacing older tui-rs.
• git2-rs + vendored-libgit2 — Direct Git repository access without shelling out; vendored build ensures portability and avoids system Git dependency.
• Crossterm — Cross-platform terminal event handling (key presses, mouse) and raw mode control for responsive playback.
• Tree-sitter queries + custom lexers — Hybrid syntax highlighting: tree-sitter for advanced languages (C#, Kotlin, Swift) and hand-written lexers for lighter languages (Bash, JSON).
• Chrono + chrono-english — Human-readable date range filtering (e.g., --after '3 weeks ago') for commit selection.

• Vendored libgit2 over system Git binary

  • Why: Guarantees consistent behavior across platforms and avoids shell subprocess overhead.
  • Consequence: Larger binary size (~50+ MB) but reliable cross-platform distribution.

• Per-frame syntax highlighting instead of pre-computed cache

  • Why: Simplifies state management and allows theme switching without restart.
  • Consequence: CPU-bound during playback; smooth only on modern hardware.

• Single-threaded synchronous animation loop

  • Why: Avoids complexity of async TUI rendering and synchronization issues.
  • Consequence: Cannot parallelize Git I/O or highlighting; frame rate capped by single-core performance.

• Hardcoded 15+ themes vs. fully pluggable theme system

  • Why: Reduces complexity and ensures themes are tested and visually coherent.
  • Consequence: Users cannot load arbitrary custom TOML themes; limited extensibility.

• Real-time collaborative playback across multiple terminals
• Video export or screen recording integration
• Full git-blame or interactive commit editing
• Network repository cloning (assumes local .git)
• Windows 7 or earlier support (uses modern Crossterm API)

1. Tree-sitter language crates: Each language is a separate dependency (tree-sitter-rust, tree-sitter-python, etc.); adding/updating languages requires editing Cargo.toml and likely src/syntax/. 2. Terminal escape codes: Crossterm abstracts platform differences, but raw terminal state (colors, cursor, scrolling) can be fragile; test on multiple terminals. 3. Git2 vendored deps: libgit2 and OpenSSL are vendored; large rebuild times and platform-specific compile flags may be needed on unusual systems. 4. Config file location: Likely ~/.config/gitlogue/ or similar (dirs crate); test config loading across Linux/macOS/Windows. 5. Unicode width: unicode-width is used for cursor positioning; emoji and wide characters in filenames/code may cause alignment issues.

• Tree-sitter incremental parsing — Gitlogue uses tree-sitter to syntactically parse 29 languages for highlighting; understanding how tree-sitter's incremental update model works helps optimize performance when replaying large diffs
• Diff hunks and unified diff format — The animation engine in src/animation.rs must consume diffs from git2 and translate them into character-by-character replay sequences; understanding unified diff structure (@@, +/-, context lines) is essential
• Terminal Rendering & Cursor Control (ANSI escape codes) — Crossterm abstracts ANSI escape sequences for cursor movement, colors, and clearing; understanding the underlying protocol helps debug rendering glitches and optimize redraw performance
• Rasterized animation frame pacing — Gitlogue must render character-by-character typing animations at realistic human speeds (~40-100 wpm) with proper timing; understanding frame rate control and animation state machines is critical to src/animation.rs
• Git object model and commit DAG — src/git.rs traverses the commit graph and extracts diffs; understanding Git's directed acyclic graph of commits, refs, and diff generation helps when implementing new replay modes or filtering logic
• Configuration schema validation (TOML deserialization) — Gitlogue's themes, keybindings, and replay settings are TOML-based and deserialized via serde in src/config.rs; understanding serde derive macros and type-safe config patterns is necessary for extending user customization
• Unicode grapheme clusters and visual width — The animation must correctly handle multi-byte Unicode characters and emoji; unicode-width crate computes display width for cursor positioning, and misalignment causes visual glitches in the editor pane

• jesseduffield/lazygit — Terminal UI for Git with interactive commit navigation; shares ratatui TUI design patterns and git2-rs bindings, but focuses on repository management vs. cinematic replay
• charmbracelet/glow — Terminal markdown renderer with TUI; demonstrates polished Rust terminal tooling and thematic styling similar to gitlogue's theme system
• tree-sitter/tree-sitter — Core dependency providing syntax parsing and highlighting; understanding tree-sitter fundamentals is essential for extending language support in gitlogue
• ratatui-org/ratatui — TUI framework powering gitlogue's layout and rendering; learning ratatui is necessary for modifying panes and visual behavior
• libgit2/libgit2 — Underlying C library vendored via git2-rs; knowledge of libgit2 API helpful for understanding diff extraction and commit traversal in src/git.rs

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for src/syntax/languages module

The syntax highlighting module has 25+ language implementations (Rust, Python, JavaScript, etc.) but there's no dedicated test suite. Given the complexity of tree-sitter grammar handling and the critical role syntax highlighting plays in the cinematic replay experience, this is a high-impact area. A test suite would catch regressions in language-specific tokenization and ensure consistent highlighting behavior across the 25+ supported languages.

• [ ] Create tests/syntax directory structure mirroring src/syntax/languages
• [ ] Add test cases for each language parser in src/syntax/languages/mod.rs (test instantiation, basic token parsing)
• [ ] Create integration tests that verify syntax highlighting output for code snippets in each supported language
• [ ] Reference test_highlighter.rs example as a foundation and expand it into proper unit tests
• [ ] Add test execution to .github/workflows/ci.yml to run syntax tests on every commit

Add missing language syntax highlighter modules for popular languages

The repo supports 25+ languages via tree-sitter, but examining src/syntax/languages/mod.rs reveals gaps: TypeScript exists but ReScript/Flow variants are missing, there's no Ruby, no Postgres/SQL, no YAML highlighting despite tree-sitter-yaml being in dependencies. Adding these would increase utility for developers working with common stack combinations (TypeScript + SQL backends, Rails projects, infrastructure-as-code).

• [ ] Check src/syntax/languages/mod.rs for incomplete language registrations
• [ ] Add src/syntax/languages/ruby.rs (tree-sitter-ruby already in Cargo.toml) with similar structure to existing language files
• [ ] Add src/syntax/languages/sql.rs supporting common SQL dialects
• [ ] Add src/syntax/languages/yaml.rs (tree-sitter-yaml already in Cargo.toml)
• [ ] Register new languages in src/syntax/languages/mod.rs match statement
• [ ] Document newly supported languages in docs/specification.md

Add missing CLI integration tests and error case coverage

The repo has complex CLI argument handling (via clap in src/main.rs) with date filtering (chrono-english), git operations (git2), and configuration loading (src/config.rs), but lacks integration tests. There are no tests for: invalid date formats, missing git repos, malformed config files, or edge cases like empty repositories. This would catch regressions in user-facing error messages and behavior.

• [ ] Create tests/integration directory
• [ ] Add tests/integration/cli_args.rs testing clap argument parsing with invalid inputs (bad dates, missing repos)
• [ ] Add tests/integration/config.rs testing config file loading failures and invalid toml
• [ ] Add tests/integration/git_operations.rs testing git2 operations on test repositories (non-existent repos, empty repos)
• [ ] Add test git repository fixtures in tests/fixtures/repos/
• [ ] Update .github/workflows/ci.yml to run integration tests with 'cargo test --test '*''

• Add tests for src/config.rs TOML parsing: examples/test_highlighter.rs exists but no obvious unit tests for configuration loading and schema validation; writing tests in tests/ directory would catch parsing regressions and document expected behavior
• Document keyboard shortcuts in a keybindings section of docs/usage.md: usage.md exists but file structure suggests keybindings/controls may be undocumented; adding a table of available keybindings (q to quit, arrow keys, etc.) would improve UX docs
• Add tree-sitter language for a popular missing language (e.g., Dockerfile, SQL, or HCL): Cargo.toml has 30 language bindings but Dockerfile and SQL are conspicuously absent; adding a new language involves adding the crate to Cargo.toml and registering it in src/syntax/ with minimal complexity

The gitlogue codebase demonstrates generally good security practices as a Rust application. The main concerns are: (1) vendored OpenSSL/libgit2 may delay security patch delivery, (2) Git repository processing should include explicit input validation to handle malformed data safely, and (3) the large number of tree-sitter parser dependencies increases the attack surface. No hardcoded secrets, SQL injection, or obvious infrastructure misconfigurations were detected. The project uses a permissive ISC license and has CI/CD pipelines configured. Recommended improvements focus on input validation for Git data and maintaining an update schedule for vendored dependencies.

• Medium · Vendored OpenSSL and libgit2 Dependencies — Cargo.toml - git2 dependency. The git2 crate is configured with 'vendored-openssl' and 'vendored-libgit2' features. While vendoring can improve build consistency, it may delay security patches for OpenSSL and libgit2. If vulnerabilities are discovered in these libraries, the application won't automatically receive updates until the git2 crate is updated. Fix: Monitor security advisories for OpenSSL and libgit2 regularly. Consider using non-vendored versions if your distribution maintains updated packages, or establish a process to quickly update git2 when security patches are released.
• Medium · Unsafe Git Operations Without Input Validation — src/git.rs. The application processes Git history and file contents. Without explicit evidence of input validation in src/git.rs, there's potential risk of malformed Git repositories causing unexpected behavior or crashes. Git repositories with specially crafted commits or files could potentially trigger unsafe code paths. Fix: Implement comprehensive input validation for Git repository data. Add error handling for malformed commits, unusual file paths, and large files. Use safe parsing methods provided by the git2 library and validate all external Git data before processing.
• Low · Tree-sitter Parser Dependencies — Cargo.toml - tree-sitter-* dependencies. The application includes 30+ tree-sitter language parser dependencies. While tree-sitter is generally safe, each parser is an additional attack surface. If any parser has a vulnerability in its grammar or parsing logic, it could affect the syntax highlighting feature. Fix: Keep tree-sitter and all language parsers updated regularly. Monitor security advisories for tree-sitter ecosystem. Consider lazy-loading only the parsers needed for the currently displayed file rather than bundling all of them.
• Low · Terminal UI Input Handling — src/panes/ directory - editor.rs, terminal.rs. The application uses crossterm for terminal interaction and ratatui for UI rendering. Improper handling of terminal escape sequences or user input could potentially allow terminal injection attacks or unexpected behavior. Fix: Ensure all user input from terminal is properly sanitized. Use ratatui's built-in text rendering functions which handle escape sequences safely. Avoid raw terminal output of unsanitized file contents.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.