Contributing Guide
We would love to accept your patches and contributions to this project. Learn how to get started and make your first contribution.
Before You Begin
Important requirements before contributing
Sign the CLA
Contributions must be accompanied by a Contributor License Agreement (CLA). You retain the copyright to your contribution.
Sign the CLA →Community Guidelines
This project follows Google's Open Source Community Guidelines. Please review them before contributing.
Read Guidelines →Ways to Contribute
There are many ways to contribute to the Gemini CLI project
Code Contributions
Fix bugs, add features, improve performance
- Bug fixes and patches
- New CLI commands
- Performance optimizations
- Code refactoring
- Test improvements
- Error handling enhancements
Documentation
Improve docs, add examples, create tutorials
- Fix documentation errors
- Add usage examples
- Improve API documentation
- Create tutorials and guides
- Update README files
- Add code comments
Issue Reporting
Report bugs, suggest features, provide feedback
- Bug reports with reproduction steps
- Feature requests and proposals
- Performance issue reports
- Security vulnerability reports
- User experience feedback
- Compatibility issues
Community Support
Help users, participate in discussions
- Answer questions in issues
- Help with troubleshooting
- Review pull requests
- Test beta versions
- Share usage examples
- Mentor new contributors
Pull Request Guidelines
Follow these guidelines to help us review and merge your PRs quickly
Link to an Existing Issue
All PRs should be linked to an existing issue. For bug fixes, link to the bug report. For features, link to an approved feature request.
Keep It Small and Focused
Create small, atomic PRs that address a single issue. Don't bundle multiple unrelated changes.
Use Draft PRs for Work in Progress
Use GitHub's Draft Pull Request feature for early feedback before formal review.
Ensure All Checks Pass
Run npm run preflight before submitting to ensure all tests, linting, and style checks pass.
Update Documentation
If your PR introduces user-facing changes, update the relevant documentation in the /docs directory.
Write Clear Commit Messages
Follow Conventional Commits standard for your commit messages and PR descriptions.
Development Setup
Step-by-step guide to set up your development environment
Prerequisites
Set up your development environment
# Install Node.js ~20.19.0 (required for development) # Use nvm to manage Node.js versions nvm install 20.19.0 nvm use 20.19.0
Clone and Setup
Get the source code and install dependencies
git clone https://github.com/google-gemini/gemini-cli.git cd gemini-cli npm install npm run build
Enable Sandboxing (Optional)
Set up sandboxing for enhanced security
# Add to your ~/.env file echo "GEMINI_SANDBOX=true" >> ~/.env # Build with sandbox container npm run build:all
Run and Test
Start the CLI and run tests
# Start Gemini CLI from source npm start # Run all tests npm run test # Run integration tests npm run test:e2e
Quality Checks
Ensure code quality before submitting
# Run all quality checks npm run preflight # Format code npm run format # Lint code npm run lint
Debugging and Testing
Tools and techniques for debugging and testing your contributions
VS Code Debugging
Debug the CLI interactively in VS Code with F5 or use the debug configuration.
# Start in debug mode npm run debug # Or use VS Code F5 key # with "Attach" configuration
React DevTools
Debug the CLI's React-based UI using React DevTools version 4.x.
# Start in development mode DEV=true npm start # Install React DevTools npm install -g react-devtools@4.28.5 react-devtools
Sandbox Debugging
Debug inside the sandbox container for security-related development.
# Debug inside sandbox DEBUG=1 gemini # Enable sandbox debugging GEMINI_SANDBOX=true npm start
Testing Types
Run different types of tests to ensure your changes work correctly.
# Unit tests npm run test # Integration tests npm run test:e2e # All quality checks npm run preflight
Ready to Contribute?
Start your contribution journey with these resources
Additional Resources
Helpful links and documentation for contributors