Buttery-smooth tools for GitHub. See what you've shipped, never miss a review comment, and let AI write your standup for you.

ghee is a tiny, friendly CLI that turns your scattered GitHub (and Linear) activity into a clean, readable summary. Point it at a date range and it tells you what you worked on. Point it at a PR and it tells you what reviewers said. Optionally, let Google Gemini turn it all into a tidy narrative.

🔍 Analyzing GitHub activity for user: octocat
📡 Fetching activity data...
📋 Fetching Linear issues...

============================================================
🤖 AI-Powered Summary
============================================================
This sprint you focused on the auth refactor (3 PRs merged),
fixed two flaky tests, and unblocked the billing migration…

• "What did I do again?" — Generate a standup, weekly update, or self-review in seconds instead of scrolling through GitHub.
• Never drop a review comment — ghee pr surfaces every unresolved comment in the repo you're standing in.
• Understand a review at a glance — ghee pr-rounds reconstructs a PR's review history into clean, chronological rounds.
• Zero hardcoding — user, repo, and auth all come from your gh login and local git remote. Nothing company- or environment-specific baked in.
• Scriptable — --json everywhere it matters, so you can pipe into jq and build your own dashboards.

• 📝 Commits — everything you pushed in a date range, grouped by repo
• 🔀 Pull requests — what you opened, with status at a glance
• 💬 PR comments — list every unresolved review comment in the current repo
• 🔁 Review rounds — reconstruct a PR's review history, round by round
• 📋 Linear issues — fold in the tickets you actually worked on (optional)
• 🤖 AI summaries — a human-readable recap via Google Gemini (optional)
• 🧰 Plays nice with scripts — --json on the comment commands for jq pipelines

You'll need:

• Python 3.11+
• GitHub CLI (gh), installed and authenticated
• uv (recommended)

Clone and sync:

uv sync

That's it — ghee is now runnable via uv run ghee.

ghee talks to GitHub through the gh CLI, so just log in once:

gh auth login

The default user, current repo, and all API access are inferred from gh and your local git remote — nothing is hardcoded.

Want your Linear tickets in the mix? Provide an API key in any of these (highest precedence first):

1. LINEAR_KEY environment variable
2. ~/.config/ghee/config.ini → [api_keys] → linear = lin_api_…
3. An existing ~/.config/lnr.cfg (first organization's key is reused automatically)

Drop in a Google Gemini key to unlock AI recaps:

1. GEMINI_KEY environment variable
2. ~/.config/ghee/config.ini → [api_keys] → gemini = …

💡 Environment variables always win over the config file. The config file is created for you on first run at ~/.config/ghee/config.ini (location follows your OS config dir).

ghee has three commands. activity is the default — running ghee with no command is the same as ghee activity.

<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
Usage: ghee [OPTIONS] COMMAND [ARGS]...

  GitHub Activity Analyzer CLI.

Options:
  --from TEXT      Start date (YYYY-MM-DD format, default: Monday 2 weeks ago)
  --to TEXT        End date (YYYY-MM-DD format, default: now)
  --no-ai-summary  Disable AI-powered summary (by default, uses Gemini if
                   GEMINI_KEY is available)
  -u, --user TEXT  GitHub login to analyze  [default: (logged-in user)]
  --help           Show this message and exit.

Commands:
  activity   Analyze GitHub activity between dates.
  pr         Fetch and list all unresolved PR comments for the current...
  pr-rounds  Fetch review rounds (submitted reviews + their inline...

<!-- OUTPUT:END -->

Summarize your commits, PRs, and Linear issues across a date range.

# Default: from Monday two weeks ago → now
uv run ghee activity

# …and because activity is the default command:
uv run ghee

# Pick a date range (YYYY-MM-DD)
uv run ghee activity --from 2024-01-01 --to 2024-01-15

# Analyze someone else's public activity
uv run ghee activity --user octocat

# Skip the AI summary even if a Gemini key is set
uv run ghee activity --no-ai-summary

What gets counted:

• PRs: Only PRs authored by the specified user (via --user/-u), created in the date range. Reviewed or commented-on PRs are deliberately excluded — the count reflects "PRs I opened", not "PRs I touched".
• --user / -u: Expects a GitHub login (e.g. octocat, pace-gene), not an email address. Passing an invalid login will produce silently zeroed activity — use gh api users/{login} to verify a login exists.

<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
Usage: ghee activity [OPTIONS]

  Analyze GitHub activity between dates.

Options:
  --from TEXT      Start date (YYYY-MM-DD format, default: Monday 2 weeks ago)
  --to TEXT        End date (YYYY-MM-DD format, default: now)
  --no-ai-summary  Disable AI-powered summary (by default, uses Gemini if
                   GEMINI_KEY is available)
  -u, --user TEXT  GitHub login to analyze  [default: (logged-in user)]
  --help           Show this message and exit.

<!-- OUTPUT:END -->

List every unresolved review comment on PRs in the current repository (detected from your git origin).

# Human-readable
uv run ghee pr

# Machine-readable for scripts
uv run ghee pr --json

Run this from inside a cloned repo with an origin remote.

<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
Usage: ghee pr [OPTIONS]

  Fetch and list all unresolved PR comments for the current repository.

Options:
  --json  Output as JSON instead of human-readable format
  --help  Show this message and exit.

<!-- OUTPUT:END -->

Reconstruct a PR's review history as rounds. Each round captures the review state (APPROVED / CHANGES_REQUESTED / COMMENTED / DISMISSED), the reviewer, their top-level body, and the inline comments left in that round.

# By full PR URL — works from anywhere
uv run ghee pr-rounds https://github.com/owner/repo/pull/123

# By number, using the current git repo
uv run ghee pr-rounds 123

# By number, with an explicit repo
uv run ghee pr-rounds 123 --repo owner/repo

# JSON output
uv run ghee pr-rounds 123 --json

<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
Usage: ghee pr-rounds [OPTIONS] PR_REF

  Fetch review rounds (submitted reviews + their inline comments) for a PR.

  PR_REF can be a PR number (e.g. 123) or a full PR URL.

Options:
  --repo TEXT  Repository in OWNER/REPO format (overrides current git repo
               when PR_REF is a bare number).
  --json       Output as JSON instead of human-readable format
  --help       Show this message and exit.

<!-- OUTPUT:END -->

Notes:

• Pending (unsubmitted) reviews are excluded.
• Pagination is capped at 100 reviews/PR and 100 inline comments/review; exceeding either prints a warning to stderr.
• In human output, resolved comments are prefixed with ✅.

Per-comment JSON fields (in addition to identity/location):

Filter out resolved comments with jq:

uv run ghee pr-rounds 123 --json \
  | jq '[.[] | .comments |= map(select(.is_resolved | not))]'

ghee ships with an agent skill that teaches AI coding agents when and how to use the CLI (e.g. "what did I work on this week?", "what review comments are still open?"). It lives at skills/ghee/SKILL.md.

Install it by copying the skill folder into your agent's skills directory:

# Claude Code — make it available in every project (user-level)
mkdir -p ~/.claude/skills
cp -r skills/ghee ~/.claude/skills/ghee

# …or scope it to a single project (project-level)
mkdir -p .claude/skills
cp -r skills/ghee .claude/skills/ghee

# Cursor uses the same SKILL.md format under .cursor/skills
mkdir -p ~/.cursor/skills
cp -r skills/ghee ~/.cursor/skills/ghee

Once installed, the agent will reach for ghee automatically when you ask about GitHub activity, PR comments, or review rounds.

If your agent already has the GitHub MCP server, ghee is a complement, not a replacement. Reach for the right tool:

ghee shines when you want:

• Cross-repo, date-ranged digests — ghee activity assembles a standup / retro / self-review across all your repos in a single call. Doing this over MCP means fanning out across many search/list calls and aggregating by hand.
• Linear in the mix — the GitHub MCP doesn't touch Linear; ghee folds those issues in.
• A ready-made AI narrative — ghee activity can return a written summary directly.
• Context efficiency — one compact CLI result instead of many MCP round-trips that fill up the agent's context window.
• Portability — it's just a binary, so it works in a plain shell, cron, or CI with jq pipelines, no MCP host required.
• Opinionated shapes — pr-rounds groups reviews into rounds and emits a stable, compact JSON schema built for downstream tooling.

ghee pr-rounds is specifically better at review history. On a large PR (e.g. astral-sh/uv#19884, 42 review rounds) ghee pr-rounds returns the whole thing in one call — each round's state, reviewer, timestamp, the top-level review body, and every inline comment correlated to its round with file:line, author, resolved status, and a permalink. The GitHub MCP needs two separate methods for the same picture (get_reviews + get_review_comments), both paginated, and they don't line up: review comments come back grouped by thread, not by round, so they have to be correlated by hand — and get_reviews doesn't return the review body text at all. That gap is exactly why an agent tends to bounce between calls (or fall back to raw gh) when reconstructing a PR's review history.

Prefer the GitHub MCP server when you want:

• One-off reads or rich navigation of a single PR / issue.
• Write actions — creating PRs, submitting reviews, resolving threads. ghee is read-only by design.

• Commits grouped by repository
• Pull requests with their status
• Linear issues you actually worked on (if configured)
• An AI-powered analysis of your focus areas (if configured)
• Totals for each activity type

github_tools/
├── __init__.py      # Package exports
├── __main__.py      # CLI entry point (Click commands)
├── ai.py            # AI / Gemini integration
├── config.py        # Config file management (~/.config/ghee/config.ini)
├── formatters.py    # Output formatting (human + JSON)
├── github_api.py    # GitHub interactions (via gh)
├── linear_api.py    # Linear GraphQL interactions
├── prompt.j2        # Jinja2 template for the LLM prompt
└── utils.py         # Dates, git repo / PR-ref parsing

Run the tests:

uv run pytest tests

Lint & format (ruff + mypy via pre-commit):

uv run pre-commit run -a

The CLI help blocks above are kept in sync with markdown-code-runner: uv run --no-sync markdown-code-runner README.md

BSD-2-Clause. See LICENSE.