<!-- generated by epythet -->

# 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).

```bash
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:

```bash
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`](https://cli.github.com/manual/gh_skill) — no `pip install` required (you only need [the GitHub CLI, `gh`](https://cli.github.com/)). Install any single skill into Claude Code with:

```bash
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.

```bash
# 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.

```bash
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).

```python
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

```bash
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

```default
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

```python
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)”.

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

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

Standalone:

```bash
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

```default
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
```

<p class="epythet-aggregates">This documentation as a single file: <a href="ge.md">ge.md</a> (Markdown, for agents).</p>