GitHub AI Agent 🤖

An intelligent AI-powered interface for managing ALL your GitHub repositories through natural conversation. Built with Express, Google's Gemini AI, and htmx for a seamless, modern web experience.

Perfect for managing the compusophy-bot account or any GitHub account programmatically!

✨ Features

• 🤖 AI-Powered Chat Interface: Interact with ALL your repositories using natural language
• 📚 Multi-Repository Management: View, create, and delete repositories
• 📁 Repository Browser: Visual file tree for easy navigation across all repos
• ✏️ Code Editor: Edit files directly in the browser
• 🔄 Automated Git Operations: The AI can commit, create PRs, and merge changes
• 🎨 Beautiful UI: Modern, gradient-based design with smooth interactions
• ⚡ htmx-Powered: Fast, dynamic updates without heavy JavaScript frameworks

🛠️ AI Capabilities

The AI agent can help you with:

• List Repositories: "Show me all my repositories" or "What repos do I have?"
• Create Repositories: "Create a new public repo called my-awesome-project"
• Delete Repositories: "Delete the test-repo repository" (use with caution!)
• Explore Repository: "What files are in compusophy-bot/my-repo?"
• Read Files: "Show me the package.json from my-project"
• Edit Files: "Update the README in my-repo to add installation instructions"
• Create PRs: "Create a pull request in my-repo to add a new feature"
• Manage PRs: "List all open pull requests in my-repo" or "Merge PR #5"
• Code Analysis: Ask questions about your codebase across all repos

🚀 Quick Start

Prerequisites

• Node.js 18+ installed
• GitHub Personal Access Token with repo permissions
• Google Gemini API Key

Installation

1. Clone the repository

   git clone <your-repo-url>
   cd gui

2. Install dependencies

   npm install

3. Configure environment variables

   Create a .env file in the root directory:

   GITHUB_TOKEN=ghp_your_github_token_here
   GITHUB_USERNAME=compusophy-bot
   GEMINI_API_KEY=your_gemini_api_key_here
   PORT=3000

   Replace compusophy-bot with your GitHub username.

4. Start the server

   npm start
   
   taskkill /F /IM node.exe && npm start
   
   taskkill /F /IM node.exe; npm start

5. Open your browser Navigate to http://localhost:3000

🔑 Getting API Keys

GitHub Personal Access Token

1. Go to GitHub Settings → Developer Settings → Personal Access Tokens
2. Click "Generate new token (classic)"
3. Select scopes: repo (Full control of private repositories)
4. Generate and copy the token

Google Gemini API Key

1. Visit Google AI Studio
2. Sign in with your Google account
3. Click "Create API Key"
4. Copy the generated key

📁 Project Structure

gui/
├── api/
│   └── index.js          # Express server with AI integration
├── index.html            # Frontend UI with htmx
├── package.json          # Dependencies
├── .env.example          # Environment variables template
└── README.md            # Documentation

🎯 Usage Examples

Chat with the AI

User: "List all my repositories"

AI: Lists all repositories for your account with descriptions

---

User: "Create a new repository called awesome-project with description 'My awesome project'"

AI: Creates the new repository and provides the URL

---

User: "Show me the files in compusophy-bot/awesome-project"

AI: Lists all files in that repository

---

User: "Read the README.md file from awesome-project"

AI: Displays the content of the README file

---

User: "Update the package.json in awesome-project to change the version to 2.0.0"

AI: Updates the file and commits the change

---

User: "Delete the test-repo repository"

AI: Deletes the repository (after confirmation)

🔧 API Endpoints

The backend exposes several endpoints:

• POST /chat - AI chat interface with function calling
• GET /repos - List all repositories for the authenticated user
• GET /files?repo=username/repo&path= - List files in a repository
• GET /file?repo=username/repo&path= - Get file contents
• POST /commit - Commit file changes (requires repo parameter)
• GET / - Serve the web interface

🎨 UI Features

• Repository Browser: Click "Load Repositories" to view all your repos
• Multi-Repo Support: Switch between repositories seamlessly
• File Browser: Click any repository to browse its files
• Code Editor: Click any file to open it in the editor
• Save Button: Edit and save files with custom commit messages
• Chat Interface: Natural language commands for ALL repository operations
• Real-time Updates: Instant feedback on all operations

🤝 AI Tool System

The AI has access to these powerful tools:

1. list_repos - List all repositories for the account
2. create_repo - Create new repositories
3. delete_repo - Delete repositories (use with caution!)
4. list_files - Browse repository contents
5. read_file - Read file contents
6. update_file - Modify or create files
7. create_pr - Create pull requests
8. list_prs - View open pull requests
9. merge_pr - Merge pull requests

🔒 Security Notes

• Never commit your .env file (already in .gitignore)
• Store API keys securely
• Use environment variables for sensitive data
• GitHub token requires full repo and delete_repo permissions for all features
• Deletion operations are permanent - the AI will delete repositories when asked!
• Consider using a dedicated GitHub account (like compusophy-bot) for automated management
• Review all AI actions before confirming destructive operations

🚀 Deployment

Vercel

1. Push your code to GitHub
2. Import project in Vercel
3. Add environment variables in Vercel dashboard
4. Deploy!

Other Platforms

Compatible with any Node.js hosting platform. Ensure environment variables are configured.

🐛 Troubleshooting

Issue: "GITHUB_TOKEN not configured"

• Solution: Make sure .env file exists with valid GITHUB_TOKEN

Issue: "GEMINI_API_KEY not configured"

• Solution: Add your Google Gemini API key to .env

Issue: AI can't access repository

• Solution: Verify GitHub token has correct permissions and repo name is correct

Issue: Files not loading

• Solution: Check repository name format is username/repo-name

📝 License

MIT

🙏 Acknowledgments

• Built with Express
• UI powered by htmx
• AI by Google Gemini
• Inspired by modern developer tools

---

Made with ❤️ for developers who want to interact with GitHub in a smarter way