octoscope

Product Introduction

1. Definition: Octoscope is a high-performance, native Terminal User Interface (TUI) dashboard specifically engineered to monitor GitHub profiles, repository metrics, and developer activity. Developed using the Go programming language and the BubbleTea framework, it functions as a specialized CLI tool that interfaces directly with the GitHub GraphQL API to provide real-time data visualization within a terminal environment.

2. Core Value Proposition: Octoscope eliminates the need for frequent context-switching between the terminal and a web browser by consolidating critical GitHub telemetry into a single, auto-refreshing interface. By leveraging the GitHub GraphQL API for efficient data fetching, octoscope provides developers, open-source maintainers, and DevOps engineers with immediate visibility into pull requests, issue counts, commit frequency, and repository health metrics, significantly enhancing developer productivity and situational awareness.

Main Features

1. Automated Background Synchronization and Refresh Engine: Octoscope implements a persistent background execution loop that re-fetches data every 60 seconds. Built on the Go concurrency model, this ensures that statistics—including star counts, follower growth, and PR statuses—remain current without manual intervention. Users can also trigger an on-demand synchronization via the "r" hotkey.

2. Multi-Dimensional GitHub Analytics Dashboard: The TUI is segmented into distinct logical modules for comprehensive data coverage:

• Profile & Social: Tracks identity metadata (name, bio, location, tenure) alongside social engagement metrics like followers and stars across non-forked repositories.
• Activity & Contribution Tracking: Aggregates lifetime pull request data, issue management history, and a rolling one-year commit count, complemented by a language distribution bar utilizing GitHub’s proprietary hex color palette.
• Operational & Repo Health: Monitors public repository inventory, fork counts, and open workloads (PRs and issues) to assess project maintenance requirements.
• Network Mapping: Visualizes organizational memberships and verified social links (X, LinkedIn, Bluesky, Mastodon) to map a developer's professional ecosystem.

3. Visual and Auditory Feedback System: To reduce cognitive load, octoscope employs a "Live Feedback" mechanism. When a metric changes during a refresh cycle—such as a new star or a merged PR—the specific card’s border flashes in an accent-pink color for two seconds. Additionally, it integrates native system notifications and audio cues (beeps) for follower and star updates, ensuring the user is alerted even when the terminal window is not in the foreground.

Problems Solved

1. Pain Point: Web-UI Friction and Manual Refreshing. Navigating the GitHub web interface to track multiple metrics across various repositories is time-consuming and requires manual page reloads. Octoscope solves this by providing a hands-free, terminal-resident alternative that auto-updates, reducing "tab fatigue."

2. Target Audience: This tool is designed for Software Engineers, Open Source Maintainers, DevOps Professionals, and Technical Recruiters. It is particularly valuable for developers who operate primarily within CLI-driven workflows and require low-latency access to their contribution data or the public profiles of collaborators and competitors.

3. Use Cases:

• Active Maintainer Monitoring: Keeping track of incoming PRs and issues across a large portfolio of repositories in real-time.
• Developer Benchmarking: Quickly analyzing the public contributions and tech stack (languages) of other developers via commands like "octoscope [username]".
• Productivity Auditing: Reviewing personal commit trends and PR merge ratios during sprint reviews or performance self-assessments.

Unique Advantages

1. Differentiation: Unlike web-based dashboards or Electron-based desktop apps, octoscope is a native Go binary with a minimal memory footprint. It offers a "zero-diff" experience where changes are highlighted automatically, whereas traditional methods require the user to manually compare old and new numbers. Furthermore, its ability to toggle between personal dashboards and any public profile with a simple command-line argument makes it a versatile reconnaissance tool.

2. Key Innovation: The integration of the GitHub GraphQL API over the REST API allows octoscope to perform deep, consolidated queries that fetch disparate data points (e.g., social links + commit counts + org memberships) in a single request, optimizing network usage and respecting API rate limits. Its "no-configuration" philosophy—automatically reading GITHUB_TOKEN or gh auth credentials—ensures immediate utility upon installation.

Frequently Asked Questions (FAQ)

1. How do I install octoscope on macOS, Linux, or Windows? Octoscope can be installed on macOS and Linux via Homebrew using the command "brew install gfazioli/tap/octoscope". For Go developers, it is available via "go install github.com/gfazioli/octoscope@latest". Windows users and those preferring manual installation can download the pre-built binaries directly from the GitHub Releases page and add them to their system PATH.

2. Is a GitHub Personal Access Token (PAT) required to use octoscope? While octoscope can view public profiles without a token, a token is effectively required for sustained use. The unauthenticated GitHub rate limit is 60 requests per hour, which is insufficient for the 60-second auto-refresh loop. Using a $GITHUB_TOKEN or the "gh" CLI authentication provides a significantly higher rate limit (5,000 requests per hour), ensuring the dashboard remains operational.

3. Does octoscope show GitHub Achievements or Pro badges? No, octoscope focuses on data exposed via the official GitHub GraphQL and REST APIs. Metrics like Achievements (Pull Shark, YOLO, etc.), "Highlights" like the PRO badge, and local time are not currently available through these APIs. Octoscope prioritizes data integrity and avoids HTML scraping to ensure long-term stability and performance.