ContriFlow CLI: An AI-Powered GitHub Contribution Assistant

This is a submission for the GitHub Copilot CLI Challenge

ContriFlow CLI is an AI-powered GitHub contribution assistant that finds beginner-friendly issues, automates setup, generates solution suggestions, and gamifies open-source contributions all from the terminal.

What I Built

ContriFlow CLI - An intelligent command-line tool that democratizes open-source contributions by making it effortless for developers to discover, contribute to, and track open-source projects on GitHub.

The Problem

Many developers want to contribute to open-source projects but struggle with:

• Finding beginner-friendly repositories to contribute to


• Locating issues that match their skill level


• Understanding contribution guidelines


• Tracking their contribution progress and streaks


• Managing forks, clones, and pull requests from the terminal

The Solution

ContriFlow CLI is a comprehensive GitHub automation tool that handles the entire contribution workflow in one unified interface, making open-source contribution accessible to everyone - from beginners to experienced developers.

Key Features

✨ Smart Issue Discovery

• Global search for beginner-friendly issues across all GitHub repos


• Filter by programming language, repository stars, and issue labels


• Repository-specific issue listing with advanced filtering


• Beautiful table-format display with color-coding using cli-table3

🍴 One-Command Setup

• Fork repositories directly from the CLI


• Clone to organized workspace with conflict detection


• Automatic upstream remote configuration


• Intelligent contribution guideline detection (3-layer search strategy)

🤖 AI-Powered Solutions

• OpenRouter API integration for AI-generated issue solutions


• Automatic code patch generation


• Smart issue analysis and suggestions

🎮 Gamified Contribution Tracking

• Daily contribution challenges with trending repositories


• Streak tracking (consecutive contribution days)


• XP system and level progression


• 28+ unique badges (First Step, Streaks, Volume, Collaboration)


• Comprehensive contribution dashboard with ASCII visualization

📊 Rich Dashboard

• Real-time stats (contributions, PRs, streaks, badges)


• Contribution history visualization


• Multiple display modes (table, list, ASCII art)


• Beautiful box drawing with proper alignment


• Progress bars and colorized output

🔐 Secure Authentication

• GitHub token-based authentication


• Safe credential storage in home directory


• Token validation with GitHub API


• Support for personal access tokens

📚 Contribution Guidelines Intelligence

• Layer 1: GitHub Community Profile API (primary method)


• Layer 2: Common repository paths (.github/, docs/, root)


• Layer 3: Organization default .github repository


• Automatic detection and display of CONTRIBUTING.md

Architecture Highlights

12 Modular Commands:

• 
  login/auth - Secure GitHub authentication


• 
  search - Repository discovery with filters


• 
  issues - Issue finder (global & repo-specific)


• 
  fork - One-click repository forking


• 
  clone - Smart repository cloning


• 
  setup - Complete repository initialization


• 
  guide - Contribution guidelines viewer


• 
  solve - AI-powered issue solutions


• 
  pr - Pull request management


• 
  contribute - Gamified contribution tracker


• 
  dashboard - Stats and progress visualization


• 
  config - Configuration management

Technology Stack:

• Node.js + ES Modules


• Commander.js for CLI framework


• Octokit REST API for GitHub integration


• Chalk for beautiful terminal colors


• Inquirer.js for interactive prompts


• Ora for loading spinners


• cli-table3 for formatted tables


• Simple-git for Git operations


• OpenRouter for AI-assisted issue analysis (optional)
  

Note: OpenRouter is optional. ContriFlow works fully without AI features and can be used as a standard GitHub

automation CLI.

Demo

╭──────────────────────────────────────────────────────────────╮

│ ╭─╮╭─╮                                                       │

│ ╰─╯╰─╯   ContriFlow CLI v1.0.0                               │

│ █ ▘▝ █  Describe a task or run a command to get started     │

│ ▔▔▔▔                                                      │

│ Use /help for commands. Type exit or quit to leave.          │

╰──────────────────────────────────────────────────────────────╯



📋 Commands: login, search, issues, fork, clone, setup, solve, guide, contribute, pr, dashboard, config

💡 Type /help for command list or /help <command> for details

🔀 Type shift+tab to switch modes (normal/plan/solve)

❌ Type exit or quit to leave



❯ ●

Usage Examples

1. Get Started in 3 Commands:

# Authenticate with GitHub

contriflow login



# Find beginner-friendly issues

contriflow issues github/copilot-cli



# Setup and start contributing

contriflow setup --repo github/copilot-cli --issue 1284

2. Daily Challenge Mode:

# Get today's contribution challenges

contriflow contribute --daily



# Trending repositories with beginner issues

# Across JavaScript, Python, TypeScript, and Go

3. AI-Powered Solutions:

# Get AI-generated solution for an issue

contriflow solve 1284 github/copilot-cli



# Auto-generates patch file with code suggestions

4. Gamified Dashboard:

# View your contribution stats

contriflow dashboard



# Multiple display modes available

contriflow dashboard --ascii      # ASCII art visualization

contriflow dashboard --detailed   # Full history

contriflow dashboard --badges     # All badges

contriflow dashboard --stats      # Statistics only

5. Smart Issue Discovery:

# Global search with filters

contriflow issues --language python --label help-wanted --min-stars 500



# Repository-specific issues

contriflow issues nodejs/node --label bug --state open



# With label filtering

contriflow issues github/copilot-cli --label good-first-issue

Beautiful Output Examples

Command Help System:

$ contriflow --help

Usage: contriflow [options] [command]



🚀 Automate your open-source contributions with ContriFlow



Commands:

  login [options]                      Log in with GitHub

  search [keyword]                     Search repositories

  issues [repo]                        Find issues (global or repo-specific)

  fork [repo]                          Fork a repository

  clone [repo]                         Clone a repository

  guide [repo]                         View contribution guidelines

  solve [issue_number] [repo]          Solve issue with AI

  setup [options]                      Fork and clone

  contribute                           Track contributions & streaks

  pr [issue_number] [repo]             Create pull request

  dashboard                            View stats and progress

  config                               Manage configuration

Beautiful Table Display with cli-table3:

📋 Issues in facebook/react with label: good-first-issue



┌────┬──────────┬──────────────────────────────────────┬──────────────┐

│ #  │ Issue ID │ Title                                │ Labels       │

├────┼──────────┼──────────────────────────────────────┼──────────────┤

│ 1  │ #25432   │ Fix typo in documentation            │ good-first-  │

│    │          │                                      │ issue        │

│ 2  │ #25401   │ Add missing TypeScript types         │ help-wanted, │

│    │          │                                      │ typescript   │

│ 3  │ #25381   │ Update deprecated API usage          │ documentation│

└────┴──────────┴──────────────────────────────────────┴──────────────┘

ASCII Dashboard with Proper Alignment:

╔═══════════════════════════════════════════════════════════╗

║          🎯 ContriFlow Contribution Dashboard 📊         ║

╚═══════════════════════════════════════════════════════════╝



┌─────────────────────────────────────────────────────────┐

│                 ⭐ LEVEL  5 ⭐                         │

│                 📈 XP Progress  45/100                 │

└─────────────────────────────────────────────────────────┘



┌─────────────────────────────────────────────────────────┐

│ 🔥 CURRENT STREAK: 15 days                             │

│ ⭐ LONGEST STREAK: 30 days                             │

│ 🔥 × 15                                                │

└─────────────────────────────────────────────────────────┘



┌─────────────────────────────────────────────────────────┐

│ ✅ CONTRIBUTIONS:   156                                │

│ 📝 ISSUES SOLVED:    28                                │

│ 🔀 PRS CREATED:      12                                │

│ 🎯 TODAY:  5/ 5 ████████████████ 100%                  │

└─────────────────────────────────────────────────────────┘



🏆 BADGES (12 Earned)

  🎯 First Step              🔥 3-Day Streak

  ⭐ 7-Day Streak             👑 30-Day Streak

  💪 10 Contributions         🚀 25 Contributions

Repository & Installation

GitHub: github.com/sunder-kumar/contriflow

Install from NPM:

npm install -g contriflow-cli

contriflow --help

Quick Start

1. Log in to ContriFlow

contriflow login

Interactive login that validates your GitHub token and securely stores your credentials.

Alternative (simpler):

contriflow auth

You'll need a GitHub Personal Access Token with these scopes:

• 
  repo - Full control of private repositories


• 
  public_repo - Access public repositories


• 
  user - User profile data

Create one at: https://github.com/settings/tokens

🔐 Repository Permissions

When creating your GitHub Personal Access Token, configure the following Repository permissions:

Set:

• Contents → Read and Write


• Pull requests → Read and Write


• Issues → Read and Write


• 
  Administration → Read and Write (needed for forks)
  

- Metadata → Read-only (default OK)

⚠️ Most Important

The following permissions are critical for ContriFlow to work correctly:

• ✅ Contents: Read & Write
  


• ✅ Administration: Read & Write
  

For Development:

git clone https://github.com/sunder-kumar/contriflow.git

cd contriflow-cli

npm install

npm start --help

My Experience with GitHub Copilot CLI

How GitHub Copilot CLI Transformed My Development

GitHub Copilot CLI was instrumental in building ContriFlow CLI. Rather than just using it for code generation, I leveraged Copilot CLI's natural language understanding to solve complex architectural and debugging challenges:

1. Architecture & Design Decisions

@github explain how to structure a Node.js CLI tool with multiple commands

Result: Copilot CLI provided architectural guidance, helping me understand command patterns, middleware setup, and best practices for scalable CLI design that led to the modular 12-command structure.

2. GitHub API Complexity

@github explain the GitHub REST API rate limiting and pagination

Result: Deep understanding of pagination, caching strategies, and efficient API usage patterns - crucial for the issues listing feature that handles thousands of results.

3. Async/Await Debugging

@github why is my Promise not resolving in this async function

Result: Multiple times during development, I had spinner and async issues where Copilot CLI's natural language explanation helped me quickly identify that startSpinner() needed to be awaited - saving debugging time.

4. Data Persistence Strategy

@github show me how to implement a simple JSON-based local database for tracking contributions

Result: Copilot CLI provided patterns for file-based data persistence, which was perfect for a CLI tool that needs to track user contributions locally without external databases.

5. Terminal UI Enhancement

@github how to create beautiful colored tables in the terminal with proper alignment

Result: This led to implementing cli-table3 and chalk, plus creating a padLine() helper function to handle ANSI color codes and emoji width - resulting in the beautiful table displays.

6. Contribution Guidelines Detection

@github how do I find CONTRIBUTING.md in a GitHub repository if it's not in the root

Result: Implemented the intelligent 3-layer search strategy that checks Community Profile API, common paths, and organization defaults - making the tool robust across different repo structures.

7. Gamification Logic

@github how to calculate and track consecutive days without server

Result: Guided me through local timestamp tracking and streak reset logic with proper edge case handling.

8. Error Handling Best Practices

@github what are the best practices for user-friendly error messages in CLI tools

Result: Comprehensive error handling with clear next-step suggestions throughout the codebase.

Impact on Development

Productivity Metrics:

• Development time reduced by ~40%


• Bug resolution time cut in half


• Code quality issues identified early


• Better architectural decisions from the start

Learning & Understanding:

• Deep GitHub API knowledge


• Better async/await patterns


• Cleaner error handling strategies


• Best practices for CLI user experience


• Terminal UI constraints and possibilities

Code Quality Improvements:

• More consistent patterns across all 12 commands


• Better validation and edge case handling


• Improved user experience through clearer messaging


• Reduced technical debt

Specific Wins with Copilot CLI

Problem 1: Directory Conflict on Re-Setup

User: contriflow setup --repo github/copilot-cli --issue 1284 (second time)

Error: fatal: destination path already exists and is not an empty directory

Solution via Copilot CLI:

@github how to handle existing directories gracefully in git operations

Led to implementing intelligent directory detection with user options to update, use as-is, or re-clone.

Problem 2: Box Drawing Misalignment

The ASCII dashboard had misaligned borders with emojis and colored text.

Solution via Copilot CLI:

@github why are my box drawing characters misaligned in the terminal

Explained ANSI escape codes and emoji width issues, leading to the padLine() helper function that properly accounts for invisible characters.

Problem 3: Negative Progress Bar Values

Dashboard crashed with "Invalid count value: -200"

Solution via Copilot CLI:

@github how to safely handle negative numbers in progress calculations

Implemented bounds checking and validation throughout the dashboard rendering logic.

Why Copilot CLI Was Essential

1. 
   Natural Language > Search Engines: Asking "why" questions got better explanations than Stack Overflow


2. 
   Context Awareness: Providing ContriFlow context made suggestions more relevant


3. 
   Speed: Instant answers instead of searching documentation


4. 
   Learning: Clear explanations increased understanding, not just copy-paste solutions


5. 
   Confidence: AI validation of approaches boosted confidence in implementation

The Real Value

The most valuable aspect of Copilot CLI wasn't code generation - it was problem-solving acceleration. When faced with:

• Architectural decisions


• Debugging mysterious errors


• Understanding complex APIs


• Best practice questions


• Edge case handling

Having natural language access to that knowledge directly in the terminal transformed my productivity.

Submission Notes

What Makes ContriFlow Special

🎯 Problem Solver: Directly addresses the pain point of finding open-source contribution opportunities

🌍 Inclusive: Designed for contributors of all skill levels with beginner-friendly focus

🤖 AI-Powered: Integration with OpenRouter API for intelligent issue analysis and solutions

🎮 Engaging: Gamification elements (streaks, badges, levels) make contribution fun and rewarding

📈 Comprehensive: Complete workflow from discovery to PR creation - nothing else needed

🚀 Production Ready: Full error handling, validation, testing, and documentation

Challenge Experience

Building ContriFlow CLI was the perfect showcase for GitHub Copilot CLI because:

1. 
   Real-World Problem: Open-source contribution is a genuine pain point affecting millions


2. 
   CLI-First Design: Natural fit for a CLI tool that enhances terminal workflows


3. 
   Copilot Enhanced: Copilot CLI directly improved development speed and quality


4. 
   Community Benefit: Helps developers everywhere contribute more effectively


5. 
   Demonstrates Potential: Shows what's possible when AI meets terminal development

Technical Achievements

• ✅ 15 source files with ~2,000 lines of clean, modular code


• ✅ 12 CLI commands fully implemented and tested


• ✅ 3-layer intelligence for contribution guideline detection


• ✅ Beautiful output with proper box drawing and ANSI handling


• ✅ Robust error handling with user-friendly messages


• ✅ Full test coverage with 28/28 tests passing


• ✅ Comprehensive documentation with 46,000+ words


• ✅ npm-ready with proper .npmignore and packaging

Thank You

Building ContriFlow CLI with GitHub Copilot CLI was an exciting journey that demonstrated the transformative power of AI-assisted development. The combination of natural language problem-solving and terminal-based productivity created a development experience that was both efficient and enjoyable.

This tool is ready for the community, and I'm excited to see it help developers everywhere contribute to open-source projects!

ContriFlow turns every developer into an open-source contributor, powered by GitHub Copilot CLI.