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/gitui-org/gitui 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 the board

• Last commit 2w ago
• 20 active contributors
• Distributed ownership (top contributor 37% of recent commits)
• MIT licensed
• CI configured
• ⚠ No test directory detected

_{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 gitui-org/gitui repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/gitui-org/gitui.

What it runs against: a local clone of gitui-org/gitui — 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 gitui-org/gitui | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 45 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of gitui-org/gitui. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/gitui-org/gitui.git
#   cd gitui
#
# 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 gitui-org/gitui and re-run."
  exit 2
fi

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

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

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

# 4. Critical files exist
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "asyncgit/src/lib.rs" \\
  && ok "asyncgit/src/lib.rs" \\
  || miss "missing critical file: asyncgit/src/lib.rs"
test -f "src/app.rs" \\
  && ok "src/app.rs" \\
  || miss "missing critical file: src/app.rs"
test -f ".github/workflows/ci.yml" \\
  && ok ".github/workflows/ci.yml" \\
  || miss "missing critical file: .github/workflows/ci.yml"
test -f "build.rs" \\
  && ok "build.rs" \\
  || miss "missing critical file: build.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 45 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~15d)"
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/gitui-org/gitui"
  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).

GitUI is a blazing-fast terminal UI for Git written in Rust that provides a responsive, keyboard-driven interface for common Git operations (staging, committing, branching, stashing, blame, log search) without leaving the terminal. It uses Ratatui for TUI rendering, asyncgit for non-blocking Git operations, and Crossterm for terminal control, solving the problem that traditional Git GUIs become unresponsive on large repositories. Monorepo structure with core application in root (src/) and specialized workspace members: asyncgit/ (async Git operations), filetreelist/ (file tree UI component), git2-hooks/ (Git hook execution), git2-testing/ (test fixtures), and scopetime/ (performance measurement). Main TUI logic lives in src/ with component-based architecture using Ratatui widgets; state management is component-local with message passing.

Terminal-native developers and power users who spend most of their Git work in the command line but occasionally need GUI-like features (visual diff, interactive staging, blame browsing) without switching to a separate application or dealing with sluggish graphical Git clients on large monorepos.

Production-ready and actively maintained. The codebase has 1.09M lines of Rust code, is published on crates.io (v0.28.1), uses GitHub Actions for CI/CD (workflows in .github/workflows/), has comprehensive keybinding documentation (KEY_CONFIG.md), and shows regular maintenance with a current MSRV of 1.88. The project is stable enough for daily use but follows semantic versioning pre-1.0.

Low risk for a single-maintainer project at this maturity. Dependencies are relatively conservative (ratatui, crossterm, git2-rs ecosystem, syntect for syntax highlighting) and pinned in Cargo.lock. The #[forbid(unsafe_code)] constraint (visible in badge) reduces memory-safety risk. Main risk is maintainer availability (extrawurst is primary), though the codebase is well-structured for contributions.

Active development visible in CI workflows (.github/workflows/ci.yml, cd.yml, nightly.yml) with Dependabot enabled for dependency updates. The repo tracks issues and PRs via GitHub (ISSUE_TEMPLATE/ has bug and feature templates), publishes nightlies (NIGHTLIES.md), and maintains a CHANGELOG.md. Recent work appears focused on performance and feature completeness rather than major rewrites.

git clone https://github.com/gitui-org/gitui.git
cd gitui
cargo build --release
./target/release/gitui

Daily commands:

cargo run --release
# Or debug mode with logging:
RUST_LOG=debug cargo run

• Cargo.toml — Root workspace configuration defining all members (gitui, asyncgit, filetreelist, git2-hooks, git2-testing, scopetime) and primary dependencies; essential for understanding project structure and build setup.
• asyncgit/src/lib.rs — Core async git abstraction layer that powers all git operations; contributors must understand this to modify any git-related functionality.
• src/app.rs — Main application entry point and event loop orchestrator; critical for understanding how UI components interact and state flows through the system.
• .github/workflows/ci.yml — CI/CD pipeline definition; essential for understanding testing, build, and release processes before contributing.
• build.rs — Build script handling version generation and asset compilation; necessary for contributors modifying build-time behavior or adding new build features.
• KEY_CONFIG.md — Key binding and configuration documentation; contributors adding new features must document key interactions here.
• CONTRIBUTING.md — Contribution guidelines, code standards, and development workflow; mandatory reading for all contributors.

• App (src/app.rs) (Rust, crossterm events, custom message enum) — Central event dispatcher and state machine; routes keyboard input to components, manages component lifecycle, coordinates async job results
  • Failure mode: App hangs/crashes if event loop deadlocks or panics in event handler; cascades to unresponsive UI
• AsyncGit (asyncgit/src/) (git2-rs, std::sync::mpsc channels, threadsafe Arc<Mutex<>> state) — Non-blocking git operation abstraction; executes git2-rs calls on background threads, caches results, notifies app of completion
  • Failure mode: Git operation panic on background thread may silently fail or cause memory leak; invalid repo state propagates to UI
• UI Components (src/components/) (ratatui) — Stateful view logic for individual screens (diff, log, commit, branches); handles component-local input, renders to canvas

Add a new UI component / view

1. Create new component struct in src/components/ directory (e.g., src/components/mynewview.rs) implementing DrawableComponent trait (src/components/mynewview.rs)
2. Register component in src/components/mod.rs and add to component enum (src/components/mod.rs)
3. Add event handling in src/app.rs for the new component's input events (src/app.rs)
4. Add key bindings in src/keys.rs for invoking the new component (src/keys.rs)
5. Update KEY_CONFIG.md with new key bindings documentation (KEY_CONFIG.md)

Add a new async git operation

1. Create new async operation module in asyncgit/src/ (e.g., asyncgit/src/myoperation.rs) using AsyncJob trait (asyncgit/src/myoperation.rs)
2. Export the new operation in asyncgit/src/lib.rs public interface (asyncgit/src/lib.rs)
3. Call the new operation from src/app.rs or appropriate component via GIT_CMD message dispatch (src/app.rs)
4. Add unit tests in asyncgit/tests/ directory using git2-testing fixtures (asyncgit/tests)

Add a new configuration option or theme

1. Define configuration struct in src/ui/style.rs or create new config module (src/ui/style.rs)
2. Load configuration from ~/.config/gitui/theme.ron or environment in initialization code (src/app.rs)
3. Apply configuration to components during draw phase in respective component files (src/components)
4. Document new theme/config options in THEMES.md (THEMES.md)

• Rust + cargo workspace — Systems language ensuring memory safety without GC; zero-cost abstractions for terminal performance; workspace structure enables code reuse across gitui and asyncgit library
• ratatui + crossterm — Pure Rust terminal UI framework with minimal dependencies; crossterm abstracts platform-specific terminal control (Windows/Unix)
• git2-rs (libgit2 bindings) — Comprehensive git functionality without invoking git CLI; better control over operations and error handling
• AsyncJob + threaded channels — Prevents UI blocking during long-running git operations; responsive terminal experience with non-blocking background tasks
• ron config format — Human-readable Rust Object Notation for theme/key config; easy parsing and serialization without external schema tools

• Async job queue instead of pure async/await

  • Why: git2-rs is not async-native; manual job queue provides better control and cross-platform consistency
  • Consequence: Slightly more verbose than pure async code but avoids thread-per-operation overhead and works reliably on all platforms

• Terminal UI only (no web/GUI variant)

  • Why: Focused scope ensures deep optimization for terminal workflows; simpler codebase and instant startup
  • Consequence: Cannot serve web or traditional GUI use-cases; limits platform to systems with terminal support

• Single-threaded rendering + background thread pool for git ops

  • Why: Terminal rendering is not thread-safe; git operations safely delegate to background workers
  • Consequence: Channel overhead between threads but prevents race conditions and ensures predictable frame timing

• No persistent undo/redo system

  • Why: Git itself is the source of truth; user can undo via git commands (git reset, git revert)
  • Consequence: Simpler implementation but requires user git knowledge for complex undo scenarios

• Does not provide authentication UI beyond basic credential prompts; assumes SSH keys or git credentials are pre-configured
• Does not support non-git version control systems (SVN, Mercurial, etc.)
• Does not run on platforms without terminal support (pure web, mobile native)
• Does not aim to be a full Git reference implementation; complex rebases or merge conflicts still require CLI fallback

1. Async task spawn pattern: asyncgit spawns tasks on a background thread pool; blocking operations in components will freeze the UI. Always use asyncgit::ProgressPercent polling or spawn async tasks via Sender. 2. Terminal size constraints: Ratatui layout is finite; components must handle small terminal widths gracefully (e.g., truncation in blame.rs). 3. Git hook execution: git2-hooks/ handles pre-commit, commit-msg, post-commit — if hooks are slow or interactive, they block; no timeout mechanism visible. 4. Config path resolution: uses dirs::config_dir() for .gitui config (Ron format in ~/.config/gitui/); fails silently if dir unwritable. 5. Syntax highlighting theme files: syntect loads themes at runtime; missing theme file falls back to default, not an error.

• Async Task Spawning & Non-blocking I/O — GitUI uses asyncgit to spawn Git operations (clone, fetch, blame) on background thread pools so the TUI remains responsive; understanding crossbeam channels and task result polling is essential to avoid UI freezes when adding new Git features
• Event-driven State Machine Architecture — The app.rs state machine processes keyboard/mouse events and routes them to components, returning new state; understanding this message-passing pattern is key to adding new UI panels or modifying control flow
• Terminal Capability Detection (Crossterm) — GitUI uses Crossterm to abstract terminal control (colors, cursor movement, mouse input) across platforms; knowing which features require capability detection prevents crashes on minimal terminals
• Syntax Highlighting via Syntect — Diff and code views use syntect to parse code and apply theme colors at runtime; understanding TextStyle and scope matching helps when customizing highlighting or fixing rendering bugs
• Git Index (Staging Area) Representation — GitUI's core feature is interactive staging (hunks, lines, files); asyncgit must correctly model the three-way diff (HEAD, index, working tree) — bugs here break commit correctness
• Progress/Cancellation Pattern for Long Operations — Large Git operations (clone, fetch) report progress via ProgressPercent; components poll this and update UI; understanding how to wire progress callbacks prevents UI hangs and enables cancel UX

• gitoxide/gitoxide — Pure Rust Git implementation (no libgit2 dependency); potential future backend to reduce C FFI overhead in gitui
• starship/starship — Terminal-native Rust CLI tool with similar async architecture (crossterm TUI, component-based); shares design patterns for responsive terminal UIs
• helix-editor/helix — Terminal editor in Rust using Ratatui; demonstrates advanced TUI patterns (async event handling, incremental rendering) applicable to gitui components
• libgit2/libgit2 — C library underlying git2-rs bindings used by asyncgit; understanding libgit2 semantics critical for diagnosing low-level Git operation bugs
• ratatui-org/ratatui — TUI framework that gitui depends on (v0.30); upstream for rendering primitives and layout logic

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 integration tests for asyncgit workspace module

The asyncgit workspace member lacks comprehensive integration tests. Given that gitui depends heavily on asyncgit for async git operations, adding integration tests would catch regressions early and improve code reliability. This is especially important since asyncgit is a critical dependency shared across the workspace.

• [ ] Review asyncgit/src/ to identify core async operations (likely in lib.rs and main modules)
• [ ] Create asyncgit/tests/integration/ directory with tests for key operations (clone, fetch, push, commit)
• [ ] Add test fixtures using git2-testing workspace member for realistic repo states
• [ ] Update asyncgit/Cargo.toml to include test dependencies if needed
• [ ] Run tests locally with cargo test --package asyncgit and verify CI passes

Document KEY_CONFIG.md with practical theme customization examples

KEY_CONFIG.md exists but the THEMES.md file suggests extensive theming capabilities. Currently there's a gap between the raw configuration documentation and practical examples. Adding a section with before/after configuration examples (e.g., 'Creating a Dracula theme', 'Customizing color scheme for accessibility') would reduce contributor friction and increase feature discoverability.

• [ ] Review THEMES.md and .github/workflows/ci.yml to understand available theme variables
• [ ] Add a new 'Theme Examples' section to KEY_CONFIG.md with 3-4 complete, working configuration snippets
• [ ] Create assets/theme-examples/ directory with sample theme files (.ron format based on dependencies)
• [ ] Update README.md to link to the new theme examples section
• [ ] Test configurations locally with gitui to ensure they actually work

Add workflow for validating git2-hooks workspace integrity

The git2-hooks workspace member is critical for commit signing and hook execution but lacks dedicated CI validation. Currently, it's only tested as part of the general CI. Adding a specific workflow would catch breaking changes to hook functionality early and document the expected behavior.

• [ ] Create .github/workflows/git2-hooks-tests.yml (similar structure to cd.yml)
• [ ] Add unit tests in git2-hooks/tests/ for hook execution scenarios (pre-commit, post-commit, sign failures)
• [ ] Test against multiple git versions (reference git2-testing workspace member for fixtures)
• [ ] Configure workflow to run on changes to git2-hooks/** and Cargo.lock
• [ ] Document in CONTRIBUTING.md that git2-hooks changes require this workflow to pass

• Add unit tests for filetreelist crate: filetreelist/src/ has core tree logic but minimal test coverage visible; adding tests for path normalization and tree flattening would improve confidence in file browser stability
• Document asyncgit executor pattern in ADR or guide: The background task spawning in asyncgit/ is non-obvious (crossbeam channels, result polling); new contributors struggle to add async Git operations correctly without a design document
• Add color theme examples and docs to THEMES.md: THEMES.md exists but file list doesn't show detailed examples; users want to customize colors for syntect highlighting and UI; concrete examples (one dark, one light) would reduce support issues

GitUI demonstrates strong security practices overall. The codebase enforces forbid(unsafe_code), indicating memory safety is a priority. No hardcoded secrets, SQL injection risks, or XSS vulnerabilities were detected. Dependencies are well-maintained Rust crates with active security monitoring through deps.rs. The main concerns are around proper handling of git operations and user-supplied paths through shellexpand, but these appear to be appropriately scoped to configuration files. The project maintains good security hygiene with regular CI/CD checks and dependency management. Recommend: (1) Regular cargo audit runs, (2) Continued monitoring of git2 library security, (3) Validation of configuration file sources.

• Low · Dependency on base64 crate without version pinning — Cargo.toml - base64 dependency. The base64 dependency is specified as '0.22' without a patch version lock. While this is standard practice in Rust, it could theoretically pull in a future patched version with behavior changes. However, this is a low-risk pattern in the Rust ecosystem. Fix: Monitor base64 releases and review changelogs when updating. Consider using cargo audit regularly to detect known vulnerabilities.
• Low · Multiple dependencies on git2 ecosystem — Cargo.toml - git2-hooks, git2-testing dependencies. The project relies on git2-hooks and git2-testing custom crates which wrap libgit2. While custom wrappers add a security layer, this introduces complexity in the supply chain. Ensure these local crates are properly audited. Fix: Regularly audit the git2 wrapper crates in the workspace. Ensure they properly validate and sanitize git operations. Review git2 library security advisories.
• Low · Use of syntect for syntax highlighting — Cargo.toml - syntect dependency. The syntect crate with plist-load feature is used for syntax highlighting. XML/plist parsing can be vulnerable to XXE (XML External Entity) attacks if not properly configured, though syntect should handle this safely by default. Fix: Keep syntect updated. Verify that only trusted theme and syntax files are loaded. Consider restricting theme sources to application bundles.
• Low · Shell expansion capability enabled — Cargo.toml - shellexpand dependency. The shellexpand crate (v3.1) is used, which can expand environment variables and shell constructs. If user input is passed through this without validation, it could lead to unintended variable expansion. Fix: Ensure shellexpand is only used on trusted configuration files, not user input. Validate and sanitize any paths before shell expansion.
• Low · RON serialization format used for configuration — Cargo.toml - ron dependency. RON (Rusty Object Notation) is used for configuration serialization. While generally safe, ensure that user configuration files cannot execute arbitrary code through deserialization attacks. Fix: Validate RON configuration files before deserialization. Use schema validation or whitelisting for allowed configuration keys.

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.