Unparty Logo

GROW

the macOS app for repositories

theunpartygrow

Repository Information

Location: unparty-app/theunpartygrow
Status: Active Development
Primary Purpose: macOS menu bar application for real-time GitHub activity monitoring and developer productivity tracking

Tech Stack

  • Framework: SwiftUI
  • Language: Swift
  • Platform: macOS 11+
  • Build Tool: Xcode
  • Authentication: GitHub Personal Access Token / GitHub CLI
  • API: GitHub REST API v3
  • Architecture Pattern: MVVM (Model-View-ViewModel)

Key Features

Core Functionality

  • Real-Time GitHub Monitoring: Polls GitHub Events API every 30 seconds for latest activity
  • Menu Bar Integration: Native macOS menu bar extra with link.circle SF Symbol
  • Event Tracking: Currently supports PushEvent with commit details
  • Authenticated Access: Works with GitHub Personal Access Token or GitHub CLI authentication
  • User Activity Feed: Displays authenticated user's events across all accessible repositories (public, private, enterprise)
  • Flexible Authentication: Multi-layered token retrieval system (Constants.swift → Keychain → GitHub CLI)

Event Support (Current & Planned)

Currently Supported:

  • ✅ PushEvent: Commit history with SHA, message, author, and URL

Planned Expansion (40+ GitHub event types):

  • Pull Request events (open, close, merge, review)
  • Issue events (open, close, comment)
  • Release events (publish, edit)
  • Star/Fork events
  • Branch/Tag creation and deletion
  • Commit comments
  • GitHub Actions workflow runs
  • Project board updates
  • And more (see GitMonitor/github_events_expansion.md)

Technical Features

  • Asynchronous Polling: Non-blocking background task with Task-based concurrency
  • Error Handling: Comprehensive error states with user-friendly messaging
  • Connection Status: Real-time connection indicator
  • Token Security: Supports keychain storage and environment-based configuration
  • Username Resolution: Automatic authenticated user detection

Architecture

Code

GitMonitor (macOS App)
├── App Entry (GitMonitorApp.swift)
│   └── MenuBarExtra (System menu bar integration)
├── Views (SwiftUI)
│   ├── MenuBarView (Main interface)
│   └── EventRow (Event display component)
├── Services
│   ├── GitHubService (API client & polling)
│   └── GitHubCLIManager (Token retrieval)
├── Models
│   ├── GitHubEvent (Event structure)
│   ├── Repository (Repo metadata)
│   ├── Actor (User information)
│   ├── EventPayload (Event data)
│   └── CommitInfo (Commit details)
└── Supporting Files
    └── Constants (Configuration)

Data Flow

Authentication Flow

Integration Points

External Services

  • GitHub REST API v3: Event polling, user authentication, repository access
  • GitHub CLI (optional): Token authentication fallback mechanism
  • macOS Keychain: Secure token storage

API Endpoints Used

  • GET /user - Fetch authenticated user information
  • GET /users/{username}/events - Poll user events (includes private/enterprise repos with proper authentication)

Security Features

  • Bearer token authentication
  • HTTPS-only API communication
  • Keychain integration for secure storage
  • Optional environment-based token configuration

Business Value

ABOUT (Understanding Progress)

GitMonitor provides real-time visibility into development activity, helping creators and developers understand:

  • Commit velocity: How often code changes are being made
  • Activity patterns: When and where development happens
  • Repository engagement: Which projects are actively being worked on
  • Team collaboration: Who is contributing to shared repositories

By surfacing GitHub activity in the menu bar, developers maintain constant awareness of project momentum without context-switching to web browsers or separate tools.

BUILD (Enabling Creation)

GitMonitor accelerates development workflows by:

  • Reducing friction: No need to open GitHub.com to check activity
  • Quick access: One click to see recent commits and events
  • Context preservation: Monitor activity while staying focused in IDE or other tools
  • Multi-repo tracking: See activity across all accessible repositories in one place
  • Authentication flexibility: Works with existing GitHub CLI or standalone tokens

The app enables developers to stay connected to their work without interrupting their flow state.

CONNECT (Facilitating Sharing)

GitMonitor strengthens team connectivity through:

  • Visibility: Transparent view of what's happening across projects
  • Accountability: Clear record of who did what and when
  • Collaboration awareness: See team member contributions in real-time
  • Release tracking: Monitor when new versions are published (planned feature)
  • Issue/PR awareness: Stay informed on discussions and reviews (planned feature)

By making GitHub activity ambient and accessible, GitMonitor fosters team coordination and project awareness.

Relationship to UNPARTY Ecosystem

Position in Ecosystem

theunpartygrow is a developer-facing productivity tool within the UNPARTY ecosystem, complementing:

  • theunpartyrunway (Dev Automation): While runway tracks costs and velocity through scripts, grow provides real-time visual monitoring
  • theunpartycrawler (Analytics Intelligence): Crawler analyzes conversation data; grow monitors GitHub events
  • theunpartyapp (Web Platform): App serves end users; grow serves developers building the platform
  • theunpartyunppp (Native Journal App): unppp is for end-user journaling; grow is for developer activity tracking

Integration Opportunities

Potential Synergies:

  1. Cost Correlation: Export event data to runway for API usage cost analysis
  2. Velocity Metrics: Integrate commit frequency with runway's sprint tracking
  3. Analytics Pipeline: Stream events to crawler for development pattern analysis
  4. Cross-Repository Insights: Aggregate activity across all 36 UNPARTY repositories

Ecosystem Alignment

  • Privacy Protection: All data stays local; no external analytics or tracking
  • Cost Sensitivity: Minimal API calls (30-second polling interval)
  • Creator Ownership: Developer controls their own monitoring data
  • Measurable Progress: Real-time visibility into ABOUT → BUILD → CONNECT activities

Setup & Installation

Prerequisites

  • macOS 11.0 or later
  • Xcode 14.0 or later (for building from source)
  • GitHub account with repository access

Quick Setup (No GitHub CLI Required)

Option 1: Configure Token in Constants.swift (Recommended)

  1. Create a GitHub Personal Access Token:

    • Go to https://github.com/settings/tokens
    • Click "Generate new token (classic)"
    • Give it a descriptive name like "GitMonitor App"
    • Select scopes: repo and read:user
    • Click "Generate token" and copy the token

  2. Add the token to your app:

    • Open GitMonitor/Supporting Files/Constants.swift
    • Replace the empty string with your token:

    swift

    static let githubToken = "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

    ⚠️ Important: Replace the x's with your actual token. Never commit real tokens to version control.

  3. Build and run the app in Xcode

Option 2: Use GitHub CLI (Original Method)

If you prefer using GitHub CLI:

bash

# Install GitHub CLI
brew install gh

# Authenticate
gh auth login

The app will automatically detect and use your CLI token.

How It Works

The app uses a fallback mechanism:

  1. First: Checks for token in Constants.swift
  2. Second: Checks for token in keychain (from previous CLI auth)
  3. Third: Falls back to GitHub CLI

This means the app will work even if GitHub CLI is not installed!

Troubleshooting

Common Issues

"No GitHub token available"

  • Solution: Configure a token using Option 1 in Setup section

"GitHub CLI not found"

  • Solution: Either install GitHub CLI (brew install gh) or use Option 1

"GitHub API error: 401"

"GitHub API error: 403"

  • Solution: Rate limit exceeded or insufficient token permissions. Ensure token has repo and read:user scopes

No events showing

  • Solution: Make sure you have recent GitHub activity in accessible repositories. Try pushing a commit or opening an issue.

Development & Testing

Building from Source

bash

# Clone the repository (adjust URL to match your fork/location)
git clone https://github.com/unparty-app/theunpartygrow.git
cd theunpartygrow

# Open in Xcode
open GitMonitor.xcodeproj

# Build and run (Cmd+R)

Project Structure

Code

theunpartygrow/
├── GitMonitor/                    # Main application code
│   ├── GitMonitorApp.swift       # App entry point
│   ├── ContentView.swift         # (Legacy view)
│   ├── Models/
│   │   └── GitHubModels.swift    # Data structures
│   ├── Views/
│   │   ├── MenuBarView.swift     # Main menu bar UI
│   │   └── EventRow.swift        # Event list item
│   ├── Services/
│   │   ├── GitHubService.swift   # API client
│   │   └── GitHubCLIManager.swift # Token retrieval
│   ├── Supporting Files/
│   │   └── Constants.swift       # Configuration
│   ├── github_events_expansion.md # Feature planning
│   └── auth_issue.md             # Authentication docs
├── GitMonitor.xcodeproj/         # Xcode project
├── SETUP.md                      # Quick setup guide
└── README.md                     # This file

Testing Strategy

  1. Manual Testing:

    • Run app and verify menu bar icon appears
    • Check that events are displayed correctly
    • Test authentication with different token sources
    • Verify 30-second polling interval

  2. Integration Testing:

    • Create test GitHub activity (commits, issues, PRs)
    • Verify events appear in app within 30 seconds
    • Test with private and public repositories
    • Validate error handling for invalid tokens

  3. Future: Automated Testing:

    • Unit tests for GitHubService API parsing
    • Mock GitHub API responses for reliable testing
    • UI tests for menu bar interactions

Future Roadmap

Phase 1: Enhanced Event Support ✅ (In Progress)

  • Push events with commit details
  • Pull Request events (open, close, merge)
  • Issue events (open, close)
  • Comments on issues and PRs

Phase 2: Rich Visualization

  • Custom icons per event type (SF Symbols)
  • Color-coded event categories
  • Actionable links to GitHub.com
  • Event filtering and search
  • Notification preferences

Phase 3: Analytics Integration

  • Export events to CSV/JSON
  • Integration with theunpartyrunway
  • Velocity metrics dashboard
  • Cost correlation analysis

Phase 4: Advanced Features

  • Multi-user support
  • Repository-specific monitoring
  • Event history and caching
  • Webhook integration option
  • Cross-device sync (via CloudKit)

Security Note

⚠️ Important: The token in Constants.swift will be compiled into your app binary. For maximum security:

  • Use keychain storage: The app automatically checks macOS Keychain for tokens stored by GitHub CLI (gh auth login). This is the most secure method.
  • Never commit tokens: Add Constants.swift to .gitignore if it contains real tokens, or keep the token value empty in version control
  • Rotate tokens regularly: Generate new tokens periodically at https://github.com/settings/tokens
  • Use minimal required scopes: Only grant repo and read:user permissions

Contributing

Development Standards

  • Follow Swift naming conventions and style guides
  • Use SwiftUI for all UI components
  • Maintain MVVM architecture pattern
  • Document public APIs with inline comments
  • Test authentication flows thoroughly

Investigation Workflow

This repository follows UNPARTY's standardized investigation approach:

  • System Investigation Templates (SIT): Document technical issues
  • Technical Investigation Reports (TIR): Track solutions
  • Git-integrated tracking: Standardized commit messages
  • See github_events_expansion.md and auth_issue.md for examples
  • SETUP.md: Quick start guide for running the app
  • GitMonitor/github_events_expansion.md: Detailed plan for expanding GitHub event type support (40+ event types)
  • GitMonitor/auth_issue.md: Authentication troubleshooting and token management

Ecosystem Documentation

  • theunpartyrunway/docs/architecture/: Architectural evolution across UNPARTY repos
  • theunpartyapp/CLAUDE.md: Web app development guide
  • theunpartyunppp/CLAUDE.md: Native app development guide
  • theunpartycrawler/CLAUDE.md: Analytics intelligence guide

License

Copyright © 2024 UNPARTY LLC
All rights reserved.

Ecosystem Metrics

MetricValue
Repository Nametheunpartygrow
Primary LanguageSwift
Target PlatformmacOS 11+
User TypeDevelopers
CategoryDeveloper Tools
StatusActive Development

Questions Answered

1. What problem does this repo solve?
Developers need real-time visibility into GitHub activity without leaving their workflow. Opening GitHub.com repeatedly breaks focus and slows down development.

2. Who is the primary user?
Developers, engineering managers, and solo creators who want ambient awareness of repository activity.

3. What tech stack does it use?
SwiftUI, Swift, macOS native frameworks, GitHub REST API v3.

4. How does it integrate with other repos?
Potential data export to theunpartyrunway for cost tracking and theunpartycrawler for analytics. Currently standalone.

5. Is it actively developed or archived?
Actively developed. Current focus: expanding GitHub event type support (see github_events_expansion.md).

6. What are the key features/capabilities?
Real-time GitHub event monitoring, menu bar integration, multi-source authentication, PushEvent tracking with commit details.

7. What external services does it depend on?
GitHub REST API (required), GitHub CLI (optional), macOS Keychain (optional).

8. How does it align with ABOUT → BUILD → CONNECT?
ABOUT: Real-time visibility into development progress. BUILD: Reduces friction in developer workflow. CONNECT: Fosters team awareness and collaboration.

9. What business value does it provide?
Developer productivity, workflow optimization, team transparency, cost-efficient monitoring (minimal API calls).

10. How does it protect creator ownership, privacy, and cost-sensitivity?
All data stays local, no external tracking, minimal API usage (30s intervals), developer controls their own data.

Last Updated: 2025-10-29
Maintained By: UNPARTY LLC
Status: 🚧 Active Development (Phase 1: Core Event Support)

Focus: Empowering developers with real-time GitHub activity awareness while protecting privacy and minimizing costs.