GRW - Git Repository Watcher

A terminal-based user interface (TUI) for monitoring git repositories in real-time. Built with Rust and Ratatui.

Features

• Real-time monitoring: Automatically detects changes in your git repository every 500ms
• File tree view: Hierarchical display of changed files with directories
• Diff visualization: Color-coded git diffs (green for additions, red for deletions)
• Dual diff modes: Single-pane and side-by-side diff views
• Panel toggling: Hide/show diff panel for focused file tree view
• Vim-like keybindings: Intuitive navigation for vim users
• Status bar: Shows repository info, branch, last commit, and change statistics with automatic text wrapping
• Help system: Built-in help page with all keybindings
• Logging: Comprehensive logging with debug mode for troubleshooting
• Responsive UI: Adapts to terminal size with intelligent header wrapping
• Light/Dark themes: Toggle between light and dark themes
• AI-Powered Advice: Get actionable suggestions for improving your code changes from an integrated AI assistant.

AI-Powered Advice Panel

GRW includes an AI-powered advice panel that provides actionable suggestions for improving your code changes. It analyzes your diff and offers feedback to enhance code quality, performance, and readability.

• Activation: Press Ctrl+l to open the advice panel.
• Interaction: Use the chat interface to ask questions or request further clarification.
• Configuration: Requires an LLM API key and can be configured via command-line arguments or the config.json file.

Keybindings

General

• ? - Show/hide help
• Esc - Exit help page or active panel (like Advice Panel)
• Ctrl+h - Toggle diff panel visibility
• Ctrl+b - Toggle changed files pane visibility
• Ctrl+o / Ctrl+m - Toggle monitor pane visibility
• Ctrl+l - Toggle AI advice panel
• Ctrl+t - Cycle through available themes (light, dark, and custom if configured)
• Ctrl+P - Enter commit picker mode
• Ctrl+W - Return to working directory view
• q / Ctrl+c - Quit application

Pane Modes

• Ctrl+d - Switch to inline diff view (or exit Advice Panel)
• Ctrl+s - Switch to side-by-side diff view

File Tree

• Tab / g t - Next file
• Shift+Tab / g T - Previous file

Diff View

• j / Down / Ctrl+e - Scroll down
• k / Up / Ctrl+y - Scroll up
• PageDown - Page down
• PageUp - Page up
• g g - Go to top
• Shift+G - Go to bottom

Monitor

• Alt+j / Alt+Down - Scroll down
• Alt+k / Alt+Up - Scroll up

Commit Picker

• j / k / ↑ / ↓ - Navigate commits
• g t - Next commit
• g T - Previous commit
• Enter - Select commit
• Esc - Exit commit picker

Advice Panel

• / - Activate chat input
• Enter - Send message (when input is active)
• Esc - Deactivate chat input
• ? - Show help

Installation

From Source

git clone <repository-url>
cd grw
cargo build --release

Docker

docker run -it --rm -v $(pwd):/repo ghcr.io/<your-github-username>/grw:latest

Usage

Run the application from any git repository:

grw

Command Line Options

• -v, --version - Print version information and exit
• -h, --help - Print help information
• -d, --debug - Enable debug logging
• --no-diff - Hide diff panel, show only file tree
• --hide-changed-files-pane - Hide changed files pane, show only diff
• --monitor-command <COMMAND> - Command to run in monitor pane
• --monitor-interval <SECONDS> - Interval in seconds for monitor command refresh
• --theme <THEME> - Set initial theme (light or dark)
• --llm-provider <PROVIDER> - LLM provider to use for AI features (e.g., openai)
• --llm-model <MODEL> - Default LLM model for all AI features
• --llm-summary-model <MODEL> - Specific model for commit summaries
• --llm-advice-model <MODEL> - Specific model for generating advice
• --llm-max-tokens <NUMBER> - Maximum number of tokens to send to LLM for both summary and advice generation (default: 16000)
• --llm-api-key <KEY> - API key for the LLM provider
• --llm-base-url <URL> - Base URL for the LLM provider
• --commit-history-limit <NUMBER> - Maximum number of commits to load (default: 100)
• --commit-cache-size <NUMBER> - Maximum number of commits to cache (default: 200)
• --summary-preload-enabled <BOOL> - Enable summary pre-loading (default: true)
• --summary-preload-count <NUMBER> - Number of summaries to pre-load (default: 5)

Examples

# Normal mode with diff panel
grw

# Hide diff panel for focused file tree view
grw --no-diff

# Enable debug logging for troubleshooting
grw --debug

# Hide diff panel with debug logging
grw --no-diff --debug

# Run a monitor command every 5 seconds
grw --monitor-command "git status --short" --monitor-interval 5

# Run a custom script in monitor pane
grw --monitor-command "./scripts/check-deps.sh" --monitor-interval 10

# Start with light theme
grw --theme light

# Start with dark theme
grw --theme dark

Configuration File

GRW supports a configuration file at ~/.config/grw/config.json that can be used to persist settings:

{
  "debug": false,
  "no_diff": false,
  "monitor_command": "git status --short",
  "monitor_interval": 5,
  "theme": "dark"
}

Or a minimal configuration with only some settings:

{
  "debug": true,
  "theme": "light"
}

Configuration options:

• debug (boolean): Enable debug logging (optional, default: false)
• no_diff (boolean): Hide diff panel, show only file tree (optional, default: false)
• hide_changed_files_pane (boolean): Hide changed files pane, show only diff (optional, default: false)
• monitor_command (string): Command to run in monitor pane (optional)
• monitor_interval (number): Interval in seconds for monitor command refresh (optional)
• theme (string): Initial theme setting (light, dark, or custom) (optional)
• custom_theme (object): Custom theme color definitions (optional, see below)
• commit_history_limit (number): Maximum number of commits to load in commit picker (optional, default: 100)
• summary_preload_enabled (boolean): Enable automatic summary preloading (optional, default: true)
• summary_preload_count (number): Number of summaries to preload ahead (optional, default: 5)
• llm (object): LLM provider configuration (optional)
  • provider (string): LLM provider (e.g., "openai")
  • model (string): Default LLM model name
  • summary_model (string): Specific model for commit summaries (optional)
  • advice_model (string): Specific model for generating advice (optional)
  • max_tokens (number): Maximum number of tokens to send to LLM for both summary and advice generation (optional, default: 16000)
  • api_key (string): API key for the LLM provider
  • base_url (string): Base URL for the LLM provider

A full configuration with LLM settings and a custom theme might look like this:

{
  "debug": false,
  "no_diff": false,
  "hide_changed_files_pane": false,
  "monitor_command": "git status --short",
  "monitor_interval": 5,
  "theme": "custom",
  "commit_history_limit": 150,
  "summary_preload_enabled": true,
  "summary_preload_count": 8,
  "llm": {
    "provider": "openai",
    "model": "gpt-4o-mini",
    "summary_model": "gpt-4o-mini",
    "advice_model": "gpt-4-turbo",
    "max_tokens": 12000,
    "api_key": "your-api-key-here",
    "base_url": "https://api.openai.com/v1"
  },
  "custom_theme": {
    "background": "#1e1e2e",
    "foreground": "#cdd6f4",
    "primary": "#89b4fa",
    "secondary": "#f9e2af",
    "error": "#f38ba8",
    "highlight": "#585b70",
    "border": "#313244",
    "directory": "#a6e3a1",
    "added": "#a6e3a1",
    "removed": "#f38ba8",
    "unchanged": "#cdd6f4"
  }
}

Command line arguments override configuration file settings.

Interface Layout

The application will:

1. Monitor the current git repository
2. Display changed files in a tree structure on the left
3. Show git diffs in the right panel (when visible)
4. Display repository information in the status bar (with automatic text wrapping)
5. Update automatically every 500ms

Panel Modes

• Default mode: Shows both file tree (30%) and diff panel (70%)
• No-diff mode: Shows only file tree (100% width)
• Help mode: Shows help documentation in place of diff panel or full content area

Theme System

GRW includes a flexible theme system with built-in light and dark modes, plus support for a user-defined custom theme.

• Dark Theme: The default theme, optimized for terminal use with dark backgrounds.
• Light Theme: A bright theme suitable for light terminal backgrounds or for better readability in bright environments.
• Custom Theme: Define your own color scheme in the configuration file for a personalized look.
• Hotkey Toggle: Use Ctrl+t to cycle through the available themes (light, dark, and custom if configured).
• Persistent Setting: Your theme preference can be saved in the configuration file or set via the command line.

The theme system intelligently adapts all UI components to the selected theme, ensuring that important information, like git diff colors (green for additions, red for deletions), remains clear and visible.

Custom Themes

You can create a custom theme by adding a custom_theme object to your ~/.config/grw/config.json file. The application will load your custom colors and make the theme available in the theme cycle.

• Hex Colors: All colors must be provided as hex strings in either #RRGGBB or shorthand #RGB format.
• Fallback: If any color key is omitted from the custom_theme object, the application will use the color from the default dark theme as a fallback for that specific key.

Here are all the available keys for the custom_theme object:

Key	Description
background	The main background color of the application.
foreground	The primary text color.
primary	The color for interactive elements and titles.
secondary	The color for secondary text and highlights.
error	The color for error messages and deletions.
highlight	The background color for selected items.
border	The color of pane borders.
directory	The color for directory names in the file tree.
added	The color for added lines in the diff view.
removed	The color for removed lines in the diff view.
unchanged	The color for unchanged lines in the diff view.

To activate your custom theme, set "theme": "custom" in your config.json.

Logging

The application includes comprehensive logging for troubleshooting and monitoring:

• Log location: ~/.local/state/grw/grw.log (follows XDG Base Directory specification)
• Default level: INFO (normal operation information)
• Debug level: DEBUG (detailed performance and operation logs)

# Enable debug logging
grw --debug

# View log file
cat ~/.local/state/grw/grw.log

# Follow log file in real-time
tail -f ~/.local/state/grw/grw.log

Debug logs include:

• Performance metrics for git operations
• Render timing information
• File change detection details
• UI state changes

Architecture

GRW uses a modern shared state architecture built on lock-free concurrent data structures from the scc crate. This design provides better performance and lower latency compared to traditional channel-based communication.

Shared State Components

• GitSharedState: Manages repository data, commit cache, and file diffs using concurrent HashMap structures
• LlmSharedState: Handles LLM summary and advice caching with active task tracking
• MonitorSharedState: Stores monitor command output and timing information
• SharedStateManager: Central coordinator for all shared state components

Key Benefits

• Lock-free operations: All data structures use atomic operations for thread-safe access
• Better cache locality: Shared memory reduces overhead compared to message passing
• Direct access: Main thread can read data directly without waiting for channel messages
• Concurrent caching: Multiple workers can update caches simultaneously without blocking

Performance Characteristics

• Real-time git status updates with minimal overhead
• Efficient LLM summary caching and preloading
• Responsive UI updates through direct shared state access
• Automatic cleanup of stale tasks and cached data

Development

Prerequisites

• Rust 1.70+
• Git

Building

cargo build

Testing

cargo test

Formatting

cargo fmt

Linting

cargo clippy

Docker

The project includes a Dockerfile for building a containerized version:

docker build -t grw .

License

This project is open source and available under the MIT License.