gemtracker

gemtracker

A beautiful, interactive Terminal UI for analyzing Ruby gem dependencies and quickly identifying security risks in your projects.

Features

• Interactive Tab-Based TUI: Clean, modern interface with 4 main screens

  • [Gems] - First-level gem list with versions and update status
  • [Search] - Real-time gem search across all dependencies
  • [CVE] - Vulnerability detection and reporting
  • Gem Details - Full dependency tree visualization

• Dependency Visualization: See forward and reverse dependency trees with version info

• Vulnerability Detection: Identify known CVEs and affected gem versions

• Group-Based Analysis: Understand gem scope (default, development, test, production)

• Version Management: See installed versions, latest available, and outdated gems

• Direct Links: Quick links to rubygems.org and GitHub repositories

Installation

macOS (Homebrew) — Recommended

brew tap spaquet/gemtracker
brew install gemtracker

To upgrade:

brew upgrade gemtracker

Linux

Download the latest release:

# For x86-64
curl -L https://github.com/spaquet/gemtracker/releases/download/v1.0.0/gemtracker_linux_amd64.tar.gz | tar xz

# For ARM64
curl -L https://github.com/spaquet/gemtracker/releases/download/v1.0.0/gemtracker_linux_arm64.tar.gz | tar xz

Or build from source:

git clone https://github.com/spaquet/gemtracker
cd gemtracker
make build

Windows

Download the latest release from GitHub Releases:

• gemtracker_windows_amd64.zip for x86-64
• gemtracker_windows_arm64.zip for ARM64

Extract the ZIP file and add the directory to your PATH, or place gemtracker.exe in a directory already in your PATH.

macOS (Direct Download)

If you prefer not to use Homebrew:

# For Intel (x86-64)
curl -L https://github.com/spaquet/gemtracker/releases/download/v1.0.0/gemtracker_darwin_amd64.tar.gz | tar xz

# For Apple Silicon (ARM64)
curl -L https://github.com/spaquet/gemtracker/releases/download/v1.0.0/gemtracker_darwin_arm64.tar.gz | tar xz

From Source (All Platforms)

Requires Go 1.24 or later:

git clone https://github.com/spaquet/gemtracker
cd gemtracker
make build
./gemtracker

Usage

Basic Usage

# Analyze current directory (must contain Gemfile.lock)
gemtracker

# Analyze specific project
gemtracker /path/to/project

# Analyze specific Gemfile.lock directly
gemtracker /path/to/project/Gemfile.lock

# Expand tilde for home directory
gemtracker ~/my-rails-app

# Show version
gemtracker -v
gemtracker --version

Interactive Navigation

Once running, use these keys:

Tab Navigation

• Tab / Shift+Tab - Switch between screens ([Gems] → [Search] → [CVE])
• / - Jump directly to Search screen

List Navigation

• ↑ / ↓ - Move selection up/down
• Enter - Select gem to view details

Gem Details

• Tab - Toggle between dependency sections
• ↑ / ↓ - Scroll through dependencies
• Esc - Return to previous screen

Global

• q / Ctrl+C - Quit gemtracker

Understanding the Gem Table

The gem list shows:

#    Gem Name    Installed   Latest      Groups      Status
──────────────────────────────────────────────────────────────
1    rails       7.1.2       7.2.0       default     ↑ 7.2.0
2    devise      4.9.3       latest      default     ✓
3    rack        2.1.2       latest      default     ⚠ CVE

Groups column shows where gems are used:

• default - All environments (production, staging, development)
• development - Development only
• test - Test only
• production - Production only

Important: A vulnerability in a test or development gem doesn't affect production if not used there.

Status column shows:

• ✓ - Up to date, no vulnerabilities
• ↑ version - Newer version available (outdated)
• ⚠ CVE - Known vulnerabilities detected

Understanding CVE Information

The CVE screen shows all known vulnerabilities:

• CVE ID - Vulnerability identifier (e.g., CVE-2021-22942)
• Gem - Name of the affected gem
• Version - Version range affected
• Description - What the vulnerability does
• Status - Whether gem is directly used or transitive

Quick Start

1. Navigate to a Ruby project with Gemfile.lock:

   cd ~/my-rails-app
   

2. Launch gemtracker:

   gemtracker
   

3. Browse gems:

   • [Gems] tab shows all first-level dependencies
   • Press Enter on any gem to see its full dependency tree
   • Check Groups column to assess vulnerability impact

4. Search for specific gems:

   • Press / or click [Search] tab
   • Type gem name to filter in real-time
   • Press Enter to view details

5. Check vulnerabilities:

   • Click [CVE] tab to see all vulnerabilities
   • Filter by gem in [Search] tab
   • Check if vulnerable gems are in production

Building

Development Build

make build

Release Build (macOS universal binary)

make build-release

Version Information

Built binaries include git commit hash and build date. To build with custom version:

VERSION=1.0.0 COMMIT=abc123 DATE=2026-04-04 make build

Project Goals

• Provide fast, actionable insights into gem dependencies
• Help identify security and compliance risks early
• Support easy integration into CI/CD pipelines
• Beautiful, intuitive UI that developers love using
• Minimal dependencies and fast performance

Tech Stack

• Language: Go 1.24+
• TUI Framework: BubbleTea + Lipgloss (charmbracelet)
• Data Source: rubygems.org API + Gemfile.lock parsing

Development

Prerequisites

• Go 1.24 or later
• Make

Setup

git clone https://github.com/spaquet/gemtracker
cd gemtracker
make build

Running Tests

make test

Code Quality Checks

Before submitting a PR, ensure your code passes all quality checks:

# Run tests
make test

# Check code formatting (auto-fix with -w flag)
gofmt -s -l .

# Run linter
go vet ./...

Required before PR submission:

• ✅ All tests must pass: make test
• ✅ Code must be formatted: gofmt -s -w . (fixes automatically)
• ✅ No vet warnings: go vet ./...

These checks run automatically in GitHub Actions when you push, but fixing them locally first prevents CI failures:

# Quick pre-PR checklist (one command)
make test && gofmt -s -w . && go vet ./... && echo "✓ Ready for PR!"

Project Structure

gemtracker/
├── cmd/gemtracker/          # CLI entry point
├── internal/
│   ├── gemfile/             # Parsing & analysis
│   │   ├── parser.go        # Gemfile.lock parser
│   │   ├── analyzer.go      # Dependency analysis
│   │   ├── outdated.go      # Version checking
│   │   └── vulnerabilities.go # CVE detection
│   └── ui/                  # Terminal UI
│       ├── model.go         # BubbleTea model
│       ├── update.go        # Message routing
│       ├── view.go          # Screen rendering
│       └── styles.go        # Colors & themes
└── Makefile                 # Build & test

Releases & Updates

gemtracker follows semantic versioning. New versions are released when features are added or bugs are fixed. Check the releases page for the latest version.

To check your installed version:

gemtracker --version

Staying Updated

• Homebrew users: brew upgrade gemtracker
• Direct download users: Check releases page and re-download the latest binary

Future: Official Homebrew

Once gemtracker has stable releases, we plan to submit it to homebrew/homebrew-core, allowing installation with just brew install gemtracker (no tap needed).

Known Limitations

• Only parses standard Gemfile.lock format
• Outdated version checking requires network access
• CVE database is static (not real-time updated)
• No support for Gemfile global options or git/path sources yet

Documentation

• CONTRIBUTING.md — How to contribute and code quality requirements
• SOLO_CONTRIBUTOR_GUIDE.md — How to work with branch protection as a solo maintainer
• CHANGELOG.md — Version history and what's new in each release
• RELEASE_GUIDE.md — How to make releases and manage the distribution pipeline
• DISTRIBUTION_SETUP.md — GitHub setup instructions for distribution
• BRANCH_PROTECTION_SETUP.md — GitHub branch protection configuration
• SECURITY.md — Security policy and vulnerability reporting
• CLAUDE.md — Development guidelines for contributors

Security

Please report security vulnerabilities privately using GitHub Security Advisory. See SECURITY.md for details.

License

See LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support & Contributing

• Questions? Open a discussion
• Found a bug? Open an issue
• Want to contribute? See CONTRIBUTING.md for guidelines
• Code quality requirements? See CONTRIBUTING.md — Code Quality
• Solo maintainer? See SOLO_CONTRIBUTOR_GUIDE.md for PR workflow

Troubleshooting

"Gemfile.lock not found"

Make sure you're in a Ruby project directory with Gemfile.lock, or specify the path:

gemtracker /path/to/project

Version shows as "(development)"

Build using make build instead of go build to get proper version info from git.

Terminal appears garbled

Your terminal may not support 256 colors. Try:

TERM=xterm-256color gemtracker

Questions?

Check the built-in help or open an issue on GitHub.