AI-powered Git analysis and documentation tool using OpenRouter agents
npm install @bramatom/git-copilot> Transform your Git workflow with AI-powered analysis, documentation, and code review





Git Copilot revolutionizes your development workflow by combining the power of AI with Git operations. This intelligent CLI tool provides comprehensive code analysis, automated documentation generation, and thorough code reviews - all powered by cutting-edge AI agents through OpenRouter integration.
- ๐ค AI-Powered Intelligence: Leverages advanced AI models for deep code understanding
- โก Lightning Fast: Get instant insights without leaving your terminal
- ๐ฏ Specialized Agents: Three expert AI agents for different development needs
- ๐ Actionable Reports: Detailed fix.md files with prioritized recommendations
- ๐ง Zero Configuration: Works out of the box with any Git repository
- ๐ OpenRouter Integration: Access to multiple AI models and providers
Choose your preferred installation method:
bash
npm install -g @bramatom/git-copilot
`$3
For project-specific usage:
`bash
npm install @bramatom/git-copilot --save-dev
`$3
Try without installing:
`bash
npx @bramatom/git-copilot [command]
`$3
- Node.js >= 16.0.0
- Git installed and configured
- OpenRouter API key (for AI features) - Get yours at OpenRouter.ai๐ Quick Start
Get up and running in 60 seconds:
$3
`bash
export OPENROUTER_API_KEY="your-api-key-here"
`
๐ก Pro tip: Add this to your .bashrc, .zshrc, or .env file for persistent access$3
`bash
cd your-awesome-project
`$3
`bash
git-copilot analyze-branch
`$3
`
๐ BRANCH ANALYSIS REPORT
========================๐ Current Branch: feature/user-auth
๐ Statistics:
3 files changed, 127 insertions(+), 23 deletions(-)
๐ Changes Summary:
โข Staged: 2 files
โข Unstaged: 1 files
โข Untracked: 0 files
๐ก Recommendations:
โข โ
No pending changes detected
โข ๐ 2 files staged for commit
โข ๐ฌ Consider more descriptive commit messages
`๐ช Use Cases & Examples
$3
`bash
Before starting work
git-copilot analyze-branch # Understand current stateDuring development
git-copilot review # Continuous quality checksBefore committing
git-copilot analyze-branch # Final reviewFor documentation
git-copilot document # Auto-generate docs
`$3
`bash
Code review process
git-copilot review > team-review.mdDocumentation standards
git-copilot document --force # Standardized docsPR preparation
git-copilot analyze-branch # Pre-PR analysis
`$3
`bash
Security audits
git-copilot review # Identify security issuesCompliance reporting
git-copilot review --path src/ # Focused analysisDocumentation maintenance
git-copilot document # Keep docs current
`๐ Commands Reference
$3
Provides comprehensive analysis of your Git branch with AI-powered insights.
`bash
git-copilot analyze-branch
Also works as default command:
git-copilot
analyze-branch # Direct global command
`What it analyzes:
- โ
Staged, unstaged, and untracked files
- ๐ Commit history and message quality
- ๐ Diff statistics and change patterns
- ๐ก Workflow improvement suggestions
Example Output:
`bash
๐ Analyzing branch changes...
โ
Analysis complete!๐ Current Branch: feature/auth-system
๐ Changes Summary: 5 files staged, 2 unstaged
๐ก Recommendations: Consider more descriptive commit messages
`---
$3
Creates comprehensive project documentation tailored to your codebase.
`bash
git-copilot document
git-copilot doc # Short alias
`Features:
- ๐ Analyzes existing documentation style
- ๐๏ธ Generates README.md, API.md, and CHANGELOG.md
- ๐ Reads project structure and package.json
- ๐จ Maintains consistent formatting
Example:
`bash
git-copilot document
Creates: README.md, API.md, CHANGELOG.md
`---
$3
Performs deep code analysis and generates detailed improvement reports.
`bash
git-copilot review
`Analysis Categories:
- ๐ด Security: Hardcoded secrets, eval usage, vulnerabilities
- ๐ก Performance: Sync operations, nested loops, bottlenecks
- ๐ข Quality: Magic numbers, long functions, complexity
- โน๏ธ Best Practices: TODOs, debug statements, conventions
Output:
- ๐ fix.md: Detailed report with prioritized issues
- ๐ Statistics: Issue counts by severity and category
- ๐ก Recommendations: Actionable improvement suggestions
Example Report:
`markdown
Code Review Report
Total issues found: 12$3
- ๐ด High: 2 (Security vulnerabilities)
- ๐ก Medium: 4 (Performance issues)
- ๐ข Low: 6 (Code quality)
`๐ค Specialized AI Agents
Git Copilot employs three specialized AI agents, each expert in their domain, powered by OpenRouter:
$3
The Git Whisperer - Understands your repository like a senior developer
`javascript
// Capabilities:
โข Branch difference analysis with context awareness
โข Commit quality assessment and pattern recognition
โข Pull request optimization suggestions
โข Breaking change detection and impact analysis
โข Workflow improvement recommendations
`$3
The Technical Writer - Transforms code into clear, professional docs
`javascript
// Capabilities:
โข Intelligent README generation based on project structure
โข API documentation extraction from code analysis
โข Changelog creation with semantic versioning awareness
โข Style consistency maintenance across all documentation
โข Integration with existing KB.md and documentation rules
`$3
The Quality Guardian - Your personal code quality mentor
`javascript
// Capabilities:
โข Multi-layered security vulnerability detection
โข Performance bottleneck identification and optimization
โข Code complexity analysis with maintainability scoring
โข Best practice enforcement with industry standards
โข Prioritized fix reports with actionable recommendations
`> Powered by: Claude 3.5 Sonnet, GPT-4, and other cutting-edge AI models via OpenRouter
โ๏ธ Configuration
$3
| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
|
OPENROUTER_API_KEY | Your OpenRouter API key | โ
Yes | - |
| GIT_COPILOT_MODEL | AI model to use | โ No | claude-3.5-sonnet |`bash
Add to your shell profile (.bashrc, .zshrc, etc.)
export OPENROUTER_API_KEY="your-api-key-here"
export GIT_COPILOT_MODEL="gpt-4" # Optional: customize AI model
`$3
Git Copilot intelligently adapts to your project by reading existing files:
| File | Purpose | Impact |
|------|---------|--------|
|
README.md | Documentation style reference | ๐ Maintains writing consistency |
| KB.md | Knowledge base and style guidelines | ๐จ Follows your team's conventions |
| .github/CONTRIBUTING.md | Contribution guidelines | ๐ฅ Aligns with project standards |
| docs/STYLE_GUIDE.md | Code style preferences | ๐ฏ Customizes review criteria |
| package.json | Project metadata | ๐ฆ Understands dependencies and scripts |> Smart Defaults: No configuration files? No problem! Git Copilot works great out of the box.
๐ Generated Files
Git Copilot creates intelligent, actionable output files:
$3
`markdown
Code Review Report
Generated: 2024-01-15Summary
Total issues found: 23
- ๐ด High: 3 (Security vulnerabilities)
- ๐ก Medium: 8 (Performance issues)
- ๐ข Low: 12 (Code quality improvements)High Priority Fixes
1. auth.js:42 - Hardcoded API key detected
2. db.js:15 - SQL injection vulnerability
3. utils.js:89 - Use of eval() is dangerous
`$3
- README.md - Professional project documentation with usage examples
- API.md - Comprehensive API reference with endpoints and examples
- CHANGELOG.md - Semantic version history with detailed change descriptions$3
๐ Sample Branch Analysis Output
`bash
๐ BRANCH ANALYSIS REPORT
========================๐ Current Branch: feature/user-authentication
๐ Statistics: 8 files changed, 234 insertions(+), 67 deletions(-)
๐ Changes Summary:
โข Staged: 5 files (auth.js, user.model.js, login.vue, etc.)
โข Unstaged: 2 files (config.js, .env.example)
โข Untracked: 1 file (migration_001.sql)
๐ฏ Recent Commits (last 10):
โข a1b2c3d Add JWT authentication middleware
โข e4f5g6h Update user model with password hashing
โข i7j8k9l Fix login form validation
๐ก Recommendations:
โข โ
Good commit message structure
โข ๐ 5 files ready for commit
โข โ ๏ธ Consider staging config.js changes
โข ๐ New migration file detected - review before commit
โข ๐ Ensure sensitive data is properly excluded from git
`
๐ ๏ธ Development & Contributing
$3
`
git-copilot/
โโโ ๐ bin/ # CLI executables & entry points
โ โโโ git-copilot.js # Main CLI interface
โโโ ๐ src/ # Core source code
โ โโโ commands/ # Command implementations
โ โ โโโ analyze-branch.js # Git analysis logic
โ โ โโโ documentation.js # Doc generation
โ โ โโโ review.js # Code review engine
โ โโโ utils/ # Shared utilities
โ โ โโโ git-checker.js # Git validation
โ โโโ types/ # TypeScript definitions
โโโ ๐ agents/ # AI agent implementations
โ โโโ pr-git-expert.js # Git analysis specialist
โ โโโ documentation-expert.js # Documentation creator
โ โโโ code-review-expert.js # Code quality auditor
โโโ ๐ tests/ # Test suites
โโโ ๐ docs/ # Project documentation
โโโ ๐ package.json # Project metadata
`$3
#### 1๏ธโฃ Clone & Install
`bash
git clone https://github.com/bramato/git-copilot.git
cd git-copilot
npm install
`#### 2๏ธโฃ Development Mode
`bash
Link for global testing
npm linkTest your changes
git-copilot --version
`#### 3๏ธโฃ Code Quality
`bash
Run tests
npm testLint code
npm run lint
npm run lint:fixType checking (if TypeScript)
npm run type-check
`$3
`bash
Unit tests
npm run test:unitIntegration tests
npm run test:integrationCoverage report
npm run test:coverage
`$3
We welcome contributions! Here's how to get involved:
#### ๐ Ways to Contribute
- ๐ Bug Reports: Found an issue? Create an issue
- ๐ก Feature Requests: Have an idea? We'd love to hear it!
- ๐ง Code Contributions: Fix bugs or add features
- ๐ Documentation: Improve docs and examples
- ๐งช Testing: Add test cases and improve coverage
#### ๐ Contribution Workflow
1. ๐ด Fork the repository
2. ๐ฟ Create a feature branch:
`bash
git checkout -b feature/amazing-new-feature
`
3. โจ Develop your changes:
- Add comprehensive tests
- Follow existing code style
- Update documentation if needed
4. ๐งช Test everything:
`bash
npm test
npm run lint
`
5. ๐ Commit with clear messages:
`bash
git commit -m "โจ Add amazing new feature - Implement feature X with Y capability
- Add comprehensive tests
- Update documentation"
`
6. ๐ Push and create a Pull Request#### ๐ Development Standards
- โ
Code Coverage: Maintain > 80% test coverage
- ๐จ Code Style: Follow ESLint configuration
- ๐ Documentation: Update README for new features
- ๐งช Testing: Add tests for all new functionality
- ๐ Security: No hardcoded secrets or vulnerabilities
๐ฆ Publishing & Releases
$3
We follow SemVer for version management:`bash
Patch release (bug fixes)
npm version patchMinor release (new features)
npm version minorMajor release (breaking changes)
npm version major
`$3
`bash
1. Ensure everything is tested
npm test2. Update version
npm version patch # or minor/major3. Publish to NPM
npm publish
`$3
Our GitHub Actions automatically handle:
- โ
Automated Testing: Run full test suite on PRs
- ๐ NPM Publishing: Automatic publishing on release tags
- ๐ Code Quality: ESLint and security checks
- ๐ Coverage Reports: Track test coverage trends
๐ฌ Support & Community
$3
- ๐ Documentation: Complete Guide
- ๐ Bug Reports: GitHub Issues
- ๐ก Feature Requests: GitHub Discussions
- ๐ค Questions: Stack Overflow$3
!GitHub stars
!GitHub forks
!GitHub watchers
$3
Special Thanks To:
- ๐ค OpenRouter - Providing access to cutting-edge AI models
- ๐ง openrouter-agents - The foundation for our AI integration
- ๐ฅ Open Source Community - For inspiration and collaborative spirit
- ๐ง AI Research Community - Making advanced language models accessible
$3
- ๐ค openrouter-agents - AI agent framework
- ๐ Git Flow Tools - Similar workflow tools
- ๐ Documentation Generators - Doc automation tools
๐ License
This project is licensed under the MIT License - see the LICENSE file for details.
`
MIT License - Free for commercial and personal use
โ
Commercial use โ
Modification โ
Distribution โ
Private use
`---
$3
`bash
npm install -g @bramatom/git-copilot
``
Made with ๐ by bramato and the open source community
Git Copilot - Where AI meets Git mastery โจ