A terminal dashboard for exploring git commit activity. View commit heatmaps, recent commits, contributor rankings, and file churn hotspots updates when you select different commits from the commit list all rendered live in your terminal.
giteyes works in two modes:
- Local mode: Point it at a repo already on your disk. No API keys, no network access; it reads the
.gitdirectory directly. - GitHub API mode: Point it at
owner/repoor a GitHub URL. It pulls the same dashboard straight from the GitHub REST API without cloning the repository.
If you have uv installed, you can run giteyes against any GitHub repo immediately, with absolutely no installation required. uv will download the tool into a throwaway environment, run it, and leave your system clean afterward:
uvx --from git+https://github.com/henderson-01/giteyes giteyes https://github.com/henderson-01/random-quotes
You can swap henderson-01/random-quotes for any owner/repo, a full URL, or a local file path.
Tip
If you plan to use this often, set up a shell alias so you don't have to type the full git URL every time:
alias giteyes='uvx --from git+https://github.com/henderson-01/giteyes giteyes'
If you CD into your cloned local project path and run giteyes . with the above alias set this will display the project in the TUI.
If you have already cloned the giteyes repository and want to run it without fully installing it, you can execute these commands from inside the giteyes directory:
1. Pull a repo's stats via GitHub API (without cloning the target project):
uvx --from . giteyes https://github.com/henderson-01/Ollama-uninstall-guides- Screenshot via GitHub API with the cloned giteyes
2. Run against another local project on your machine:
uvx --from . giteyes ../giteyes
(This assumes your target project, giteyes, is located in the same parent folder as giteyes.)
- Screenshot via Local Clone 👆 UVX command giteyes
To install giteyes locally for standard usage or development, we use uv to manage the environment and dependencies:
git clone https://github.com/henderson-01/giteyes.git
cd giteyes
uv sync
This automatically creates a .venv, locks your dependencies, and installs the project in editable mode.
Because uv isolates the installation, how you run the command depends on where you are in your terminal.
If you are currently inside your cloned giteyes folder, prefix your commands with uv run:
uv run giteyes # Dashboard for the current directory
uv run giteyes /path/to/other-repo # Dashboard for a specific local repo
uv run giteyes henderson-01/random-quotes # Dashboard for an uncloned GitHub repo
uv run giteyes https://github.com/henderson-01/random-quotes # Full URLs work too
If you want to analyze a project without shifting your terminal back to the giteyes source folder, you can use uvx pointing to your local installation directory:
# CD into any project you want to explore
cd /path/to/your-target-project
# Run giteyes using the local source path
uvx --from /path/to/cloned/giteyes giteyes .
To make running giteyes globally seamless, add this alias to your shell profile (e.g., ~/.bashrc or ~/.zshrc):
alias giteyes="uvx --from /path/to/cloned/giteyes giteyes"
Once reloaded, you can simply cd into any git repository on your machine and type:
giteyes .
Dashboard Controls:
r— Refresh dataq— Quit
Note: A local path is always checked first. Only targets that don't exist locally are parsed as GitHub references.
Run this to clean up the uv/uvx cache from time to time:
uv cache clean
GitHub's unauthenticated REST API allows 60 requests per hour. Because each dashboard load makes roughly 15 requests, you will hit this limit quickly.
To raise your limit to 5,000 requests per hour, provide a personal access token (no special scopes are needed for public repos):
# Pass it as an argument example
uv run giteyes henderson-01/random-quotes --token ghp_yourtokenhere
# Or export it as an environment variable
export GITHUB_TOKEN=ghp_yourtokenhere
uv run giteyes henderson-01/random-quotes
API Limitation: In GitHub API mode, churn hotspots are computed only from the ~20 most recent commits to save your rate limit. In Local mode, hotspots scan the last 200 commits directly from disk. Clone the repo and use Local mode if you need the deepest file churn history.
Interested in building locally or learning more about the codebase structure? Check out DEVELOPMENT.md for testing and architecture details, and CONTRIBUTING.md for contribution guidelines.
MIT — see LICENSE