ge — GitHub Engineering for AI Agents

Tools and skills that let AI coding agents work on GitHub issues, PRs, and discussions intelligently.

Most GitHub engineering can be done from an AI agent console with gh and Python. But some tasks — fetching an issue with all its comments, downloading screenshots, extracting video frames, checking if the issue is stale or already fixed — burn tokens every time, with a different improvised solution each time. ge crystallizes these into deterministic tools with CLI and Python interfaces. More importantly, it wraps them into AI skills that agents can use directly, so you just say “work on issue #42” and the agent knows exactly what to do.

So that’s the order here: skills first (the intended interface), then the tools underneath (for when you want direct control).

pip install ge
ge install-skills   # register skills with Claude Code

Skills — the main interface

ge ships Claude Code skills that teach the agent how to work on GitHub issues. After installing the package, register them globally:

ge install-skills

This creates symlinks in ~/.claude/skills/ pointing to the skills bundled with ge. From then on, tell your agent “work on THIS” — where THIS can be:

  • A GitHub URL: work on https://github.com/owner/repo/issues/42

  • A bare number: work on issue #42 (assumes the current repo)

  • A repo+number: work on owner/repo#42

  • A pre-prepared context folder: work on ~/.cache/ge/owner/repo/issue_42

The agent resolves whatever you give it, confirms what it understood before proceeding, then:

  1. Loads or prepares full context (body, comments, media, cross-references)

  2. Analyzes freshness — is it stale? already fixed? has related merged PRs?

  3. Describes images via the Claude API (or asks you to paste them as fallback)

  4. Asks you before working on ambiguous or likely-resolved issues

  5. Works on the issue — creates a branch, makes changes, submits a PR

Six skills are installed:

Skill

Purpose

ge

Full workflow — resolve target, confirm, prepare context, analyze, work

ge-analyze

Quick triage — check if an issue is worth working on

ge-context

Context preparation — fetch and assemble structured documents

ge-autonomous-execution

Behaviour policy for unattended runs (decide-and-log, don’t ask)

ge-roadmap-execution

Drive a roadmap issue end-to-end, one task per iteration

ge-cross-repo-triage

Classify & resolve issues across repos (failing test → fix → PR)

ge-write-issue

Authoring issues/comments people read — layering, asking, assigning

To remove the skills: ge uninstall-skills

Installing skills with gh skill

The skills are also installable directly from GitHub with gh skill — no pip install required (you only need the GitHub CLI, gh). Install any single skill into Claude Code with:

gh skill install thorwhalen/ge <name> --agent claude-code

For example, gh skill install thorwhalen/ge ge --agent claude-code installs the main workflow skill.

Skill

Description

ge

Use when asked to work on a GitHub issue, PR, or discussion. Resolves flexible input (URL, folder, number), confirms with the user, prepares context, and guides the workflow.

ge-analyze

Use when you need to check whether a GitHub issue or PR is still relevant, stale, or already resolved — without preparing full context or downloading media.

ge-context

Use when you need to prepare, read, or refresh full context for a GitHub issue, PR, or discussion — fetching data, downloading media, and writing structured context documents.

ge-autonomous-execution

Behavioural policy for running unattended. Use when launched in headless / auto-permission mode and there is no user available — converts every clarifying question into a logged decision so progress continues.

ge-roadmap-execution

Execute a roadmap of tasks end-to-end using GitHub as durable memory. Take the next todo task, do it, verify it, mark it done, log decisions, and repeat.

ge-cross-repo-triage

Triage and resolve a cross-repo issue backlog — Phase A classifies and orders issues; Phase B executes them one at a time (failing test → confirm red → fix → confirm green → open PR).

ge-write-issue

Use when AUTHORING a GitHub issue, comment, or report that a human will read — especially a non-technical stakeholder or client. Covers layering detail with <details>, asking a question that gets answered, and assigning so someone is on the hook.

Autonomous execution

ge can drive Claude Code through a long body of work without interrupting you. State lives in GitHub (issues, comments) so each session can exit, the runner relaunches a fresh one, and progress resumes — context exhaustion is no longer a failure mode.

# Drive a roadmap issue to completion (one headless `claude -p` per task).
ge run-roadmap owner/repo <ROADMAP_ISSUE>

# Triage and resolve issues across several repos.
ge run-triage <TRACKING_REPO> <TRACKING_ISSUE> "owner/a,owner/b" --phase analyze
ge run-triage <TRACKING_REPO> <TRACKING_ISSUE> "owner/a,owner/b" --phase execute

The runner launches claude with --permission-mode auto by default; pass --mode bypass if you have explicitly authorised --dangerously-skip-permissions. Between iterations the session is gone — the next one rehydrates state from GitHub.

Each spawned session sees what the runner scopes for it. It starts in --cwd (default: the current directory), and that directory decides whose CLAUDE.md loads: give a package’s checkout. A cwd outside every git checkout (a projects root, a scratch working folder) loads none of the work’s instructions, so the runner warns about it. --add-dirs a,b adds directories the run must edit: their skills join the listing, but their CLAUDE.md files do not load, so the runner tells the session to Read them first. --read-first names further routing documents (relative to the cwd), --skills the skills to load by name, and --model / --effort pass through to claude. The JSON result carries the scope, for diagnosing a run later.

ge run-roadmap owner/repo 12 --cwd ~/proj/pkg --add-dirs ~/proj/lib --skills pkg-dev --model sonnet --effort high

The memory model

Store

Backing

Use for

RoadmapStore

A roadmap issue whose body holds a markdown task list between <!-- ge:roadmap:begin --> / end. Checkboxes render as GitHub’s task-list progress bar.

Roadmap of tasks; agent-modifiable.

DecisionLog

Tagged comments (<!-- ge:decision -->) on an issue or PR.

Significant decisions and course-corrections.

TriageBacklog

A tracking issue whose body holds a JSON block keyed by owner/repo#N.

Cross-repo triage with explicit resolution order.

GitHub is the single source of truth; the .ge/cache/ snapshot is hydrate-only (gitignored).

import ge

mall = ge.github_memory(
    "owner/repo",
    roadmap_issue=1,
    decisions_target=1,
    triage_issue=9,
)
roadmap = mall["roadmap"]
roadmap.next_todo()  # next "- [ ]" task
roadmap.append("New task")  # adds "- [ ] New task"

mall["decisions"].append("Used X over Y", rationale="cheaper")
mall["triage"]["owner/repoA#42"] = ge.TriageEntry(
    ref="owner/repoA#42",
    verdict=ge.TriageVerdict.fixable,
    order=1,
)

CLI equivalents: ge roadmap-show, ge roadmap-next, ge roadmap-set, ge roadmap-append, ge decision-log, ge decisions-show, ge triage-set, ge triage-show, ge check-requirements.

Tools — what the skills use under the hood

Everything below is what the skills orchestrate automatically. You can use any of it directly via CLI or Python.

What ge prepare does

Fetches an issue or PR and assembles everything an agent needs:

  • Issue/PR body and all comments — with media URLs rewritten to local paths

  • Images downloaded — screenshots, mockups, error captures (auto-detected from content)

  • Video frames extracted — via ffmpeg scene detection

  • AI image descriptions — images described via Claude API, embedded in the context document

  • Freshness analysis — staleness, related merged PRs, resolution signals

  • Cross-references — commits and PRs that mention this issue

All via gh CLI, so private repos just work.

Quick start

ge prepare owner/repo --number 42
ge prepare https://github.com/owner/repo/pull/7
ge analyze-issue owner/repo 42

Requirements

  • gh CLI — installed and authenticated (gh auth login)

  • Python 3.10+

  • ffmpeg — optional, for video frame extraction

  • anthropic — optional, for AI-powered image descriptions (pip install anthropic + set ANTHROPIC_API_KEY)

  • ImageMagick — optional, for clipboard montage (brew install imagemagick on macOS)

CLI commands

ge prepare <repo> --number <N>              Full context (auto-detects issue/PR/discussion)
ge prepare <url>                           Full context from a GitHub URL
ge prepare-discussion <repo> --number <N>  Full context for a GitHub Discussion
ge analyze-issue <repo> <N>                Freshness analysis (JSON, no download)
ge analyze-pr <repo> <N>                   PR review analysis with CI status (JSON)
ge fetch-issue <repo> <N>                  Raw issue JSON
ge fetch-pr <repo> <N>                     Raw PR JSON
ge fetch-discussion <repo> <N>             GitHub Discussion JSON
ge media <file.md>                 Download media from markdown
ge video-frames <video>            Extract frames (scene detection by default)
ge describe-images <img>...        Describe images via Claude API (vision)
ge copy-images <img>...            Create montage + copy to clipboard (macOS)
ge resolve <target>                Resolve a URL, folder, or number to structured target
ge install-skills                  Register skills with Claude Code (~/.claude/skills/)
ge uninstall-skills                Remove ge skill symlinks

Python API

import ge

# Prepare full context
ctx = ge.prepare("https://github.com/owner/repo/issues/42")
ctx = ge.prepare_issue("owner/repo", 42)
ctx = ge.prepare_pr("owner/repo", 7)
ctx = ge.prepare_discussion("owner/repo", 5)

# Just analysis (no download)
analysis = ge.analyze_issue("owner/repo", 42)

# Resolve flexible input
target = ge.resolve_target("#42", current_repo="owner/repo")

# Image tools
from ge.media import describe_images, copy_images_to_clipboard

text = describe_images("screenshot.png", "error.jpg")
path = copy_images_to_clipboard("img1.png", "img2.png")

Image analysis

When ge prepare runs, it downloads images and — if anthropic is installed — automatically sends them to the Claude API for visual analysis. The descriptions are embedded in the context document under “Image Descriptions (AI-generated)”.

pip install anthropic
export ANTHROPIC_API_KEY=sk-ant-...

To disable: ge prepare owner/repo --number 42 -d

Standalone:

ge describe-images screenshot.png error.jpg
ge describe-images frame1.jpg frame2.jpg --prompt "What changed between these frames?"
ge copy-images screenshot1.png screenshot2.png   # montage + clipboard (macOS)

Project structure

ge/
├── __init__.py      # Facade: prepare(), resolve_target(), install_skills(), etc.
├── __main__.py      # CLI via cw (SSOT: _cli_commands list)
├── github.py        # GitHub API via `gh` CLI subprocess
├── media.py         # Image download, video frames, describe_images, clipboard montage
├── analysis.py      # Staleness/freshness/relevance analysis
├── context.py       # Assembles everything into context docs
├── util.py          # Internal helpers: gh wrapper, URL parsing, resolve_target
├── memory.py        # GitHub-backed memory: RoadmapStore, DecisionLog, TriageBacklog
├── run.py           # Autonomous runner: launches `claude` in a loop
└── data/skills/     # Claude Code skills (symlinked by install-skills)
    ├── ge/                     # Full workflow skill
    ├── ge-analyze/             # Triage/staleness skill
    ├── ge-context/             # Context preparation skill
    ├── ge-autonomous-execution/  # Unattended-mode behaviour policy
    ├── ge-roadmap-execution/     # Drive a roadmap issue end-to-end
    ├── ge-cross-repo-triage/     # Multi-repo triage and resolution
    └── ge-write-issue/           # Authoring issues for human readers

This documentation as a single file: ge.md (Markdown, for agents).

built 2026-10-14 06:08 UTC from 639fe26 (main) · ge 0.1.18 · about this build