Skip to content

README.md

Latest commit

 

History

History
322 lines (237 loc) · 10.3 KB

README.md

File metadata and controls

322 lines (237 loc) · 10.3 KB

GitAI - GitHub Activity Monitor

A fast, colorful CLI tool for monitoring GitHub pull requests/issues and GitLab merge requests/issues across repositories. Track your contributions, reviews, and assignments with real-time progress visualization.

Features

  • 🚀 Parallel API Calls - Fetches data concurrently for maximum speed
  • 🎨 Colorized Output - Easy-to-read color-coded labels, states, and progress
  • 📊 Smart Cross-Referencing - Automatically links related PRs and issues
  • ⚡ Real-Time Progress Bar - Visual feedback with color-coded completion status
  • 🔍 Comprehensive Search - Tracks authored, mentioned, assigned, commented, and reviewed items
  • 📅 Time Filtering - View items from the last month by default (configurable with --time)
  • 🎯 Organized Display - Separates open, merged, and closed items into clear sections

Installation

Pre-built Binaries (Recommended)

Download the latest release for your platform from the releases page:

macOS

# Intel Mac
curl -L https://github.com/zveinn/git-feed/releases/latest/download/git-feed_<VERSION>_Darwin_x86_64.tar.gz | tar xz
chmod +x git-feed
sudo mv git-feed /usr/local/bin/

# Apple Silicon Mac
curl -L https://github.com/zveinn/git-feed/releases/latest/download/git-feed_<VERSION>_Darwin_arm64.tar.gz | tar xz
chmod +x git-feed
sudo mv git-feed /usr/local/bin/

Linux

# x86_64
curl -L https://github.com/zveinn/git-feed/releases/latest/download/git-feed_<VERSION>_Linux_x86_64.tar.gz | tar xz
chmod +x git-feed
sudo mv git-feed /usr/local/bin/

# ARM64
curl -L https://github.com/zveinn/git-feed/releases/latest/download/git-feed_<VERSION>_Linux_arm64.tar.gz | tar xz
chmod +x git-feed
sudo mv git-feed /usr/local/bin/

Windows

Download the appropriate .zip file from the releases page, extract it, and add git-feed.exe to your PATH.

Build from Source

go build -o git-feed .

Release Management

Releases are automatically built and published via GitHub Actions using GoReleaser:

# Create a new release
git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0

This will automatically:

  • Build binaries for Linux (amd64, arm64), macOS (Intel, Apple Silicon), and Windows (amd64)
  • Generate checksums for all releases
  • Create a GitHub release with installation instructions
  • Publish all artifacts to the releases page

Configuration

First Run Setup

On first run, GitAI automatically creates a configuration directory at ~/.git-feed/ with:

  • .env - Shared configuration file for GitHub and GitLab
  • github.db - Local database for caching GitHub data
  • gitlab.db - Local database for caching GitLab data

GitHub Token Setup

Create a GitHub Personal Access Token with the following scopes:

  • repo - Access to repositories
  • read:org - Read organization data

Generate token: https://github.com/settings/tokens

Environment Setup

You can provide credentials via a shared env file or environment variables. Select platform with --platform github|gitlab (default: github).

Option 1: Configuration File (Recommended)

Edit ~/.git-feed/.env and add your credentials:

# GitHub (`--platform github`)
# Required in GitHub online mode
GITHUB_TOKEN=your_token_here
GITHUB_USERNAME=your_username

# Optional in GitHub online mode
GITHUB_ALLOWED_REPOS=user/repo1,user/repo2

# GitLab (`--platform gitlab`)
# Required in GitLab online mode
GITLAB_TOKEN=your_token_here
# Optional alternative token variable
GITLAB_ACTIVITY_TOKEN=

# Optional host/base URL settings
GITLAB_HOST=
GITLAB_BASE_URL=https://gitlab.com

# Required in GitLab online mode
GITLAB_ALLOWED_REPOS=group/repo1,group/subgroup/repo2

# Legacy fallback used only when platform-specific vars are unset
ALLOWED_REPOS=

Option 2: Environment Variables

export GITHUB_TOKEN="your_token_here"
export GITHUB_USERNAME="your_username"
export GITHUB_ALLOWED_REPOS="user/repo1,user/repo2"  # Optional in GitHub mode

export GITLAB_TOKEN="your_token_here"
export GITLAB_ALLOWED_REPOS="group/repo1,group/subgroup/repo2"  # Required in GitLab mode

Note: Environment variables take precedence over the .env file.

Usage

Basic Usage

# Monitor items from the last month (default, platform=github)
git-feed

# Explicit platform
git-feed --platform github
git-feed --platform gitlab

# Show items from the last 3 hours
git-feed --time 3h

# Show items from the last 2 days
git-feed --time 2d

# Show items from the last 3 weeks
git-feed --time 3w

# Show items from the last 6 months
git-feed --time 6m

# Show items from the last year
git-feed --time 1y

# Show detailed logging output
git-feed --debug

# Use local database instead of GitHub API (offline mode)
git-feed --local

# Show hyperlinks underneath each PR/issue
git-feed --links

# Delete and recreate the database cache (start fresh)
git-feed --clean

# Filter to specific repositories only
git-feed --allowed-repos="user/repo1,user/repo2"

# Quick offline mode with links (combines --local and --links)
git-feed --ll

# Combine flags
git-feed --local --time 2w --debug --links --allowed-repos="miniohq/ec,tunnels-is/tunnels"

Command Line Options

Flag Description
--time RANGE Show items from the last time range (default: 1m)
Examples: 1h (hour), 2d (days), 3w (weeks), 4m (months), 1y (year)
--platform PLATFORM Activity source platform: github or gitlab (default: github)
--debug Show detailed API call progress instead of progress bar
--local Use local database instead of platform API (offline mode, no token required)
--links Show hyperlinks (with 🔗 icon) underneath each PR and issue
--ll Shortcut for --local --links (offline mode with links)
--clean Delete and recreate the database cache (useful for starting fresh or fixing corrupted cache)
--allowed-repos REPOS Filter to specific repositories (GitHub: owner/repo1; GitLab: group[/subgroup]/repo)

Color Coding

Labels:

  • AUTHORED - Cyan
  • MENTIONED - Yellow
  • ASSIGNED - Magenta
  • COMMENTED - Blue
  • REVIEWED - Green
  • REVIEW REQUESTED - Red
  • INVOLVED - Gray

States:

  • OPEN - Green
  • CLOSED - Red
  • MERGED - Magenta

Usernames: Each user gets a consistent color based on hash

How It Works

Online Mode (Default)

  1. Parallel Fetching - Simultaneously searches for activity on the selected platform:

    • PRs you authored
    • PRs where you're mentioned
    • PRs assigned to you
    • PRs you commented on
    • PRs you reviewed
    • PRs requesting your review
    • PRs involving you
    • Your recent activity events
    • Issues you authored/mentioned/assigned/commented

  2. Local Caching - All fetched data is automatically saved to a local BBolt database (~/.git-feed/github.db for GitHub or ~/.git-feed/gitlab.db for GitLab)

    • MRs/PRs, issues, and comments/notes are cached for offline access
    • Each item is stored/updated with a unique key
    • Database grows as you fetch more data

  3. Cross-Reference Detection - Automatically finds connections between PRs and issues by:

    • Checking PR body and comments for issue references (#123, fixes #123, full URLs)
    • Checking issue body and comments for PR references
    • Displaying linked issues directly under their related PRs

  4. Smart Filtering:

    • Shows both open and closed items from the specified time period
    • Default: Items updated in last month (1m)
    • Custom: Use --time with values like 1h, 2d, 3w, 6m, 1y

Offline Mode (--local)

  • Reads all data from the selected local database instead of platform APIs
  • No internet connection or API token required
  • Displays all cached PR/MR and issue activity
  • Useful for:
    • Working offline
    • Faster lookups when you don't need fresh data
    • Reviewing previously fetched data

API Rate Limits

GitAI monitors GitHub API rate limits and will warn you when running low:

  • Search API: 30 requests per minute
  • Core API: 5000 requests per hour

Rate limit status is displayed in debug mode.

Automatic Retry & Backoff

When rate limits are hit, GitAI automatically retries with exponential backoff:

  • Detects rate limit errors (429, 403 responses)
  • Waits progressively longer between retries (1s → 2s → 4s → ... up to 30s max)
  • Continues indefinitely until the request succeeds
  • Shows clear warnings: ⚠ Rate limit hit, waiting [duration] before retry...
  • No manual intervention required - the tool handles rate limits gracefully

Troubleshooting

"GITHUB_TOKEN environment variable is required"

Set up your GitHub token (GITHUB_TOKEN) for --platform github, or GitLab token (GITLAB_TOKEN / GITLAB_ACTIVITY_TOKEN) plus GITLAB_ALLOWED_REPOS for --platform gitlab.

"Rate limit exceeded"

Wait for the rate limit to reset. Use --debug to see current rate limits.

Progress bar looks garbled

Your terminal may not support ANSI colors properly. Use --debug mode for plain text output.

Development

Project Structure

git-feed/
├── main.go                      # Main application code
├── platform_github.go           # GitHub platform implementation
├── platform_gitlab.go           # GitLab platform implementation
├── db.go                        # Database operations for caching GitHub data
├── README.md                    # This file
├── CLAUDE.md                    # Instructions for Claude Code AI assistant
├── .goreleaser.yml              # GoReleaser configuration for builds
├── .github/
│   └── workflows/
│       └── release.yml          # GitHub Actions workflow for releases

~/.git-feed/                  # Config directory (auto-created)
 ├── .env                     # Shared configuration file
 ├── github.db                # BBolt database for GitHub cache
 └── gitlab.db                # BBolt database for GitLab cache

Testing Releases Locally

You can test the GoReleaser build locally before pushing a tag:

# Install goreleaser
go install github.com/goreleaser/goreleaser/v2@latest

# Test the build (creates snapshot without publishing)
goreleaser release --snapshot --clean

# Check the dist/ folder for built binaries
ls -la dist/

License

MIT License - Feel free to use and modify as needed.