Narad GitHub Agent 🚀🤖

A Premium CLI & MCP Server Powered by Gemini 2.0 Flash

The Narad GitHub Agent is a next-generation, dual-mode intelligent agent engineered for seamless high-level interactions with GitHub. It operates as an interactive CLI chat agent you can talk to directly, or as a Model Context Protocol (MCP) server that integrates with AI-powered IDEs and tools.

Powered by Gemini 2.0 Flash, it transforms complex repository tasks into simple conversational interactions — with conversation memory, AI code reviews, and a daily digest of your GitHub activity.

Fully Dynamic: The agent uses whoever's GITHUB_TOKEN is in .env. Clone it, put your own token in, and it works 100% for your account — no code changes needed.

✨ Key Features

Related MCP server: GitHub MCP Server

🛠️ Tech Stack

📁 Project Structure

Narad-GitHub-Agent/
├── src/
│   ├── main.py              # Dual entry point: CLI or MCP Server
│   └── narad_mcp/
│       ├── config.py        # Pydantic Settings & Config
│       ├── server.py        # FastMCP Server with all tools
│       ├── cli.py           # Rich Interactive CLI Agent
│       ├── database.py      # SQLite layer (memory, PR reviews, digests)
│       ├── tools/
│       │   └── github_tools.py  # All GitHub API interactions
│       └── agents/
│           └── gemini_agent.py  # Gemini 2.0 Flash Reasoning Engine
├── tests/                   # Quality assurance suite
├── narad_agent.db           # 🔒 Local SQLite DB (auto-created, git-ignored)
├── .env                     # 🔒 Secrets (git-ignored, never pushed)
├── .env.example             # Credential Template for setup
├── .gitignore               # Strict security rules
└── requirements.txt         # Modern dependencies

🚀 Quick Start

1. Prerequisites

Ensure you have Python 3.10+ installed and your API keys ready.

2. Clone & Setup Environment

# Clone the repo
git clone https://github.com/Edge-Explorer/Narad-GitHub-Agent.git
cd Narad-GitHub-Agent

# Create and activate virtual environment
python -m venv venv
.\venv\Scripts\activate   # Windows

# Install dependencies
pip install -r requirements.txt

3. Configure Credentials

Create a .env file by copying the example:

copy .env.example .env

Then fill in your keys:

GITHUB_TOKEN="your_github_personal_access_token"
GEMINI_API_KEY="your_gemini_api_key"

Getting a GitHub Token: Go to GitHub Settings → Developer Settings → Personal Access Tokens and create a token with repo scope.

Getting a Gemini API Key: Visit Google AI Studio to generate your free Gemini API key.

4. Run the Agent

💬 Interactive CLI Mode (Chat with the Agent)

python src/main.py --cli

🌐 MCP Server Mode (Connect to AI IDE)

python src/main.py

🧰 CLI Commands

You can type natural language or use the keywords below:

Natural Language Examples

show me my repos
give me commits from Edge-Explorer/Narad-GitHub-Agent
analyze my Narad project
what are the open PRs in Edge-Explorer/Narad-MCP-Server
review pr Edge-Explorer/my-project 3
give me today's digest
what is a pull request?

🗄️ Local SQLite Database

The agent automatically creates narad_agent.db to persist data locally:

The database file is git-ignored and stays only on your machine.

🔒 Security & Best Practices

• Your token is 100% dynamic: The agent reads GITHUB_TOKEN from .env at startup. If you change the token, it uses the new one automatically. No code changes needed.

• Token never leaks: .env and *.db are strictly in .gitignore — they will never be pushed to GitHub.

• Anyone can clone this: A new user clones the repo, adds their own .env with their credentials, and the agent will work for their GitHub account — not yours.

• Least Privilege: Only the GitHub token scopes you need (repo is enough for all features).

• Validated Config: Pydantic Settings validates all environment variables on startup — it fails fast with a clear error if a key is missing.

🧰 MCP Tools (Server Mode)

When running as an MCP Server, these tools are exposed to your AI IDE:

🤝 About

Narad GitHub Agent — Re-engineered from the ground up with a focus on security, modularity, AI-first design, and genuine day-to-day developer utility.

Built as part of the Narad AI Ecosystem — a family of modular, premium AI agents.

📜 License

This project is licensed under the MIT License. See the LICENSE file for details.

© 2026 Edge-Explorer · Narad AI Ecosystem