A high-performance command-line tool that tracks changes in GitHub users' starred repositories, showing only newly starred repositories between runs. Designed for automation, monitoring workflows, and integration with other development tools.

• Incremental Monitoring: Only shows newly starred repositories since the last run
• Multi-User Support: Monitor multiple GitHub users simultaneously with parallel processing
• First Run Baseline: Establishes a baseline on the first run without showing output
• Multiple Output Formats: Support for text (human-readable) and JSON formats
• Optional Authentication: Works without tokens (60 req/hour) or with tokens (5000 req/hour) - only prompts when --auth flag is used
• Secure Token Storage: Uses OS keychain for token storage with interactive fallback
• Rate Limit Handling: Intelligent rate limit detection and user-friendly error messages
• Clean Architecture: Well-structured codebase with interfaces and dependency injection
• Comprehensive Error Handling: User-friendly error messages with actionable guidance

• Go 1.25 or later
• macOS (for keychain integration) or Linux

git clone https://github.com/akme/gh-stars-watcher.git
cd gh-stars-watcher
make build

The application is available as a multi-architecture Docker image supporting linux/amd64, linux/arm64, and linux/arm/v7.

# Monitor a user with Docker
docker run --rm ghcr.io/akme/gh-stars-watcher:latest monitor octocat

# With JSON output
docker run --rm ghcr.io/akme/gh-stars-watcher:latest monitor octocat --output json

# Monitor multiple users
docker run --rm ghcr.io/akme/gh-stars-watcher:latest monitor "octocat,github,torvalds"

To maintain state between runs, mount a volume:

# Create a named volume for state persistence
docker volume create star-watcher-data

# Run with persistent state
docker run --rm \
  -v star-watcher-data:/home/nonroot/.star-watcher \
  ghcr.io/akme/gh-stars-watcher:latest \
  monitor octocat

# Using environment variable
docker run --rm \
  -e GITHUB_TOKEN=your_token_here \
  ghcr.io/akme/gh-stars-watcher:latest \
  monitor octocat --auth

# Using Docker secrets (recommended for production)
echo "your_token_here" | docker secret create github_token -
docker run --rm \
  --secret github_token \
  -e GITHUB_TOKEN_FILE=/run/secrets/github_token \
  ghcr.io/akme/gh-stars-watcher:latest \
  monitor octocat --auth

Use the included docker-compose.yml for easy local development:

# Run with Docker Compose
GITHUB_TOKEN=your_token docker-compose up star-watcher

# Development mode with live code reload
docker-compose up star-watcher-dev

# Build locally
make docker-build

# Test multi-arch build
make docker-build-multiarch

# Build and push to registry
make docker-push

# Build and push with version tag
make docker-push-version VERSION=v1.0.0

# Build with version tag
VERSION=v1.2.0 make docker-push-version

Monitor a single user's starred repositories:

./bin/star-watcher monitor octocat

Monitor multiple users simultaneously with comma-separated usernames:

./bin/star-watcher monitor "octocat,github,torvalds"

Multi-user example with JSON output:

./bin/star-watcher monitor "octocat,github" --output json

On the first run, the tool establishes a baseline:

$ ./bin/star-watcher monitor octocat
First run for octocat - baseline established with 3 starred repositories.
Run again to detect newly starred repositories.

Subsequent runs show only newly starred repositories:

$ ./bin/star-watcher monitor octocat
🌟 octocat has starred 2 new repositories!

⭐ octocat/Hello-World
   My first repository on GitHub!
   Language: None | Stars: 1
   Starred: 2024-01-15
   https://github.com/octocat/Hello-World

⭐ github/docs
   The open-source repo for docs.github.com
   Language: JavaScript | Stars: 2150
   Starred: 2024-01-16
   https://github.com/github/docs

Total repositories: 5
Previous check: 2024-01-14 10:30:45

When monitoring multiple users, output is grouped by username:

$ ./bin/star-watcher monitor "octocat,github"
🌟 octocat has starred 1 new repository!

⭐ octocat/Hello-World
   My first repository on GitHub!
   Language: None | Stars: 1
   Starred: 2024-01-15
   https://github.com/octocat/Hello-World

🌟 github has starred 1 new repository!

⭐ github/docs
   The open-source repo for docs.github.com
   Language: JavaScript | Stars: 2150
   Starred: 2024-01-16
   https://github.com/github/docs

=== Summary ===
Total users monitored: 2
Users with new stars: 2
Total new repositories: 2

Get structured output in JSON format:

./bin/star-watcher monitor octocat --output json

Single user JSON output:

{
  "username": "octocat",
  "new_repositories": [
    {
      "full_name": "octocat/Hello-World",
      "description": "My first repository on GitHub!",
      "star_count": 1,
      "updated_at": "2024-01-15T10:30:00Z",
      "url": "https://github.com/octocat/Hello-World",
      "starred_at": "2024-01-15T12:00:00Z",
      "language": "",
      "private": false
    }
  ],
  "total_repositories": 5,
  "previous_check": "2024-01-14T10:30:45Z",
  "current_check": "2024-01-16T14:20:30Z",
  "rate_limit": {
    "limit": 60,
    "remaining": 45,
    "reset_time": "2024-01-16T15:00:00Z",
    "used": 15
  },
  "is_first_run": false
}

Multi-user JSON output:

{
  "results": [
    {
      "username": "octocat",
      "new_repositories": [
        {
          "full_name": "octocat/Hello-World",
          "description": "My first repository on GitHub!",
          "star_count": 1,
          "updated_at": "2024-01-15T10:30:00Z",
          "url": "https://github.com/octocat/Hello-World",
          "starred_at": "2024-01-15T12:00:00Z",
          "language": "",
          "private": false
        }
      ],
      "total_repositories": 3,
      "is_first_run": false
    },
    {
      "username": "github",
      "new_repositories": [],
      "total_repositories": 50,
      "is_first_run": false
    }
  ],
  "summary": {
    "total_users": 2,
    "users_with_new_stars": 1,
    "total_new_repositories": 1
  },
  "timestamp": "2024-01-16T14:20:30Z"
}

Remove stored state for a user:

./bin/star-watcher cleanup octocat

Remove all stored states:

./bin/star-watcher cleanup --all

• -o, --output string: Output format: text (default) or json
• -q, --quiet: Quiet output (errors only)
• -v, --verbose: Verbose output (detailed logging)
• --state-file string: Custom state file path (default: ~/.star-watcher/{username}.json)

star-watcher monitor [username] [flags]

Monitor GitHub user(s) starred repositories for changes. Username can be a single user or comma-separated list for multi-user monitoring.

Flags:

• --auth: Prompt for GitHub token authentication (optional, increases rate limits)
• All global flags also apply

Examples:

star-watcher monitor octocat
star-watcher monitor octocat --output json
star-watcher monitor "octocat,github,akme"
star-watcher monitor octocat --auth --verbose
star-watcher monitor octocat --state-file ./custom-state.json

star-watcher cleanup [username] [flags]

Remove stored state files for a specific user or all users.

Flags:

• --all: Remove all state files (use with caution)

Examples:

star-watcher cleanup octocat
star-watcher cleanup octocat --state-file ./custom-state.json
star-watcher cleanup --all

Authentication is completely optional! The tool works without authentication, but provides higher rate limits when authenticated.

1. No Authentication (default): 60 requests per hour - sufficient for monitoring a few users
2. With Authentication: 5000 requests per hour - use the --auth flag to enable

1. Environment Variable: Set GITHUB_TOKEN environment variable
2. OS Keychain: Tokens are securely stored in the system keychain
3. Interactive Prompt: If no token is found, you'll be prompted to enter one

Only prompt for authentication when you need higher rate limits:

# Use without authentication (60 req/hour)
./bin/star-watcher monitor octocat

# Use with authentication (5000 req/hour)
./bin/star-watcher monitor octocat --auth

1. Go to GitHub Settings > Personal Access Tokens
2. Click "Generate new token (classic)"
3. Add a note (e.g., "GitHub Stars Monitor")
4. Select scopes:
   • public_repo (for public repositories)
   • repo (if you want to monitor private starred repositories)
5. Click "Generate token"
6. Copy the token and provide it when prompted

The tool stores state in JSON files under ~/.star-watcher/:

• ~/.star-watcher/{username}.json: Contains the baseline of starred repositories for each user
• Files include repository metadata, star counts, and timestamps
• State files are atomic-write protected to prevent corruption
• Each user has independent state management for multi-user monitoring
• Significantly reduced file sizes - removed unnecessary audit logging to keep files minimal

• Unauthenticated: 60 requests per hour
• Authenticated: 5000 requests per hour

The tool automatically handles rate limits and provides helpful error messages:

Error: GitHub API rate limit exceeded. Resets at: 2024-01-16T15:00:00Z

The project follows clean architecture principles:

cmd/star-watcher/          # CLI entry point
internal/
├── auth/                  # Authentication (keychain, prompts)
├── cli/                   # CLI commands and output formatting
├── github/                # GitHub API client
├── monitor/               # Core monitoring logic
└── storage/               # State persistence
tests/
├── contract/              # Interface contract tests
└── integration/           # End-to-end tests

go build -o star-watcher ./cmd/star-watcher

go test ./...

The project follows standard Go conventions and uses:

• Clean architecture with interfaces
• Dependency injection
• Comprehensive error handling
• Test-driven development (TDD)

• Startup Time: ~20ms for CLI operations
• API Performance: ~50 seconds for 3000 repositories (limited by GitHub API)
• State File Size: Significantly reduced - removed unnecessary audit logging (timestamps) for minimal file sizes
• Memory Usage: Minimal - processes repositories in batches
• Multi-User Processing: Parallel processing for multiple users with goroutines
• Rate Limit Optimization: Intelligent handling for both authenticated (5000/hour) and unauthenticated (60/hour) usage

Wait for the rate limit to reset or authenticate with a GitHub token for higher limits.

Ensure the username follows GitHub's rules:

• 1-39 characters long
• Only alphanumeric characters and hyphens
• Cannot start or end with a hyphen

Remove the state file and re-run to establish a new baseline:

star-watcher cleanup username
star-watcher monitor username

Ensure the tool has permission to write to ~/.star-watcher/ directory.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes following the existing code style
4. Add tests for new functionality
5. Ensure all tests pass (go test ./...)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

This project is licensed under the MIT License - see the LICENSE file for details.

• go-github for GitHub API integration
• Cobra for CLI framework
• go-keyring for secure token storage
• tests/ - Comprehensive test suite (contract, integration, unit)

MIT License - see LICENSE file for details.