Welcome to the GithubRoast project, powered by the Gemini API and crewAI. This app shows how to set up a CrewAI crew using Gemini models grounded with Google Search.
If you just want to try it out, go to https://roast.markm.cd/
A CrewAI crew is defined that follows a short plan:
- Research the user
- Research their projects
- Write a roast
You can see the CrewAI configuration in the config
dir. Also check out the custom LLM
class that uses the google_search tool inside
CrewAI.
The agents all use the Gemini API, by default Gemini 2.5 Flash. The agents defined for the research tasks use the Gemini API's Google Search Grounding feature to look up any relevant information on the supplied user's GitHub profile. This is easy to implement, runs pretty quickly and can grab any relevant GitHub information from around the web.
The Crew is wrapped in a FastAPI that serves a streaming endpoint. This API streams progress updates to indicate as tasks complete, and eventually returns a message with the roast, in markdown.
The web frontend is just a static HTML page that calls the API and renders updates. If you want to develop something more complex, the API is serving the HTML as a static route, so you can deploy a separate web app pointed at the API.
Ensure you have Python >=3.10 <3.13 installed on your system. This project uses UV for dependency management and package handling.
First, if you haven't already, install uv:
pip install uvNext, navigate to your project directory and install the dependencies:
uv syncGrab an API key from Google AI Studio and
add it to the .env file as GEMINI_API_KEY.
cp .env.example .env
# Now edit .env and add add your key to the GEMINI_API_KEY line.You can now choose to run the API service locally or with Docker. Read one of the the next two sections depending on what you prefer. Docker will need to be installed, or just run locally using the already-installed tools.
Run the service. Use --reload to automatically refresh while you're editing.
uv run uvicorn api.service:app --reloadWith the API server running, browse to http://localhost:8000/
To build and run a docker image locally, using a specified API key:
docker build -t roaster-backend-local:latest .
docker run -p 8000:8080 -e GEMINI_API_KEY=your_api_key_here --name my-roaster-app-local roaster-backend-local:latestWith the API server running, browse to the docker port, http://localhost:8080/
To run your crew of AI agents directly, without an API server, run this from the root folder of your project. Pass your GitHub username as the last argument to roast yourself.
uv run github_roaster yourgithubusernameYou will get a markdown file created in the same directory, yourgithubusername.md. Load it in your favourite markdown renderer, e.g. glow.