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
- Natural Language > Search Engines: Asking "why" questions got better explanations than Stack Overflow
- Context Awareness: Providing ContriFlow context made suggestions more relevant
- Speed: Instant answers instead of searching documentation
- Learning: Clear explanations increased understanding, not just copy-paste solutions
- 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:
- Real-World Problem: Open-source contribution is a genuine pain point affecting millions
- CLI-First Design: Natural fit for a CLI tool that enhances terminal workflows
- Copilot Enhanced: Copilot CLI directly improved development speed and quality
- Community Benefit: Helps developers everywhere contribute more effectively
- 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.
Top comments (0)