An agentic CLI tool for analyzing, describing, and generating documentation for GitHub repositories.

grepo automates the heavy lifting of repository maintenance. By integrating with LLM providers like Google Gemini, it intelligently analyzes your codebase to generate professional READMEs, suggest relevant repository topics, and craft repository descriptions.

flowchart TD
    User["User Command"] --> CLI["grepo CLI"]
    CLI --> GH["GitHub API / Gitingest"]
    GH -->|Repo Context| CLI
    CLI --> LLM["LLM (Gemini)"]
    LLM -->|Analysis/Doc Content| Generator["Documentation Generator"]
    Generator --> Output["Output (README/Mermaid)"]

Ensure you have Bun installed, then install grepo globally:

bun add -g @elysiumoss/grepo

Generate a new README.md for a repository:

grepo readme https://github.com/owner/repo --format md --push

Automatically update repository topics based on code analysis:

grepo topics https://github.com/owner/repo --apply --merge

Options:

• --format md|mdx: Output format (default: md)
• --push: Push the generated file directly to the GitHub repository
• --apply: Apply changes (topics/description) directly to the GitHub API
• --dry-run: Preview changes without writing or pushing
• --model <id>: Manually specify the LLM model to use

grepo requires authentication for repository access and AI analysis. Configure these via environment variables or a .env file:

• GEMINI_API_KEY: Required for AI code analysis.
• GH_TOKEN or GITHUB_TOKEN: Required for pushing files, updating topics, or repository descriptions.

Example .env file:

GEMINI_API_KEY=AIzaSy...
GH_TOKEN=ghp_...

1. Clone the repo:

   git clone https://github.com/ElysiumOSS/grepo
   cd grepo
   bun install

2. Build the project:

   bun run build

3. Run tests:

   bun run test

See .github/CONTRIBUTING.md and .github/DEVELOPMENT.md for detailed guidelines.

This project is licensed under the MIT License.