github-cli

Turn one giant AI-generated pull request to a reviewable stack (opens in new tab)

Coding agents can rapidly produce complete features, but they often deliver them as enormous, shallow pull requests that are difficult to review and slow to merge. GitHub’s stacked pull requests address this by decomposing a feature into small, dependency-ordered layers. The result is a reviewable chain of changes that preserves context while reducing maintenance and merge conflicts. ## The Problem with Giant AI-Generated Pull Requests - A seemingly simple product-search feature may include: - A data model and seed data - An API route and validation - Client integration and UI states - Coding agents commonly generate all of this in a single 1,000-plus-line pull request. - Large pull requests: - Become difficult to review thoroughly - Cause reviewers to lose context - Receive lower-quality feedback - Take longer to merge - Are more likely to land under-reviewed Traditional alternatives are also imperfect: one large pull request harms reviewability, while a manually maintained chain of smaller pull requests creates synchronization work and conflict-management overhead. ## Stacked Pull Requests - Stacked pull requests break a feature into logical, dependent layers. - Each pull request focuses on one concern and remains small enough for reviewers to understand. - Later layers build naturally on earlier, already-reviewed work. - Different layers can be assigned to specialized reviewers, such as data or UI owners. For the product-search example, the proposed stack is: - **L1 – `feat/catalog-data`**: Typed catalog, seed data, validation, and data access; based on `main` - **L2 – `feat/search-api`**: Validated `/api/products/search` endpoint; based on L1 - **L3 – `feat/chat-grounding`**: Connects chat to the API and real product data; based on L2 - **L4 – `feat/grounded-ui`**: Adds product citation cards and UI states; based on L3 ## Setting Up the Stack - Choose the stack base first, because CI checks and merge rules are evaluated against it. - Place foundational work closest to the base and dependent work above it. - Install GitHub’s CLI extension: ```bash gh extension install github/gh-stack ``` - Teach coding agents how to create and manage stacks: ```bash gh skill install github/gh-stack ``` Alternatively: ```bash npx skills add github/gh-stack ``` - Ensure CI is configured, since every pull request layer is checked against the stack base. ## Assigning Agents to Layers The example uses separate agents with strict scope boundaries: - **L1:** Data modeler agent - **L2:** Backend agent - **L3:** Frontend agent - **L4:** Frontend agent This division encourages each agent to produce a focused pull request rather than reconstructing the entire feature in one pass. ## Recommended Workflow The development process starts with the foundational catalog layer and proceeds upward through the dependency chain. Agents work autonomously within their assigned scope, while each completed layer can be reviewed independently before subsequent layers are evaluated. Stacked pull requests are a practical way to preserve the productivity benefits of coding agents without sacrificing review quality. Teams should define clear layer boundaries, establish the stack base, assign appropriate reviewers or agents, and run CI for every layer.

Dungeons & Desktops: Building a procedurally generated roguelike with GitHub Copilot CLI (opens in new tab)

GitHub Dungeons is a terminal-based roguelike that transforms a repository into a procedurally generated dungeon. Built in Go with GitHub Copilot CLI, it uses the latest commit SHA as a seed, making each commit produce a distinct but reproducible map. The project demonstrates how AI-assisted development can let developers focus more on game design and iteration than on implementation details. ## Repository-Driven Procedural Generation - The game generates rooms, corridors, and enemies from the current codebase. - Each repository produces a structurally different dungeon. - The latest commit determines the random seed: - The same commit always creates the same map. - Code changes reshape the dungeon. - Procedural generation creates replayability by producing many layouts from a single set of rules. ## Roguelike Design - GitHub Dungeons draws on classic games such as *Rogue*. - It combines: - Procedurally generated levels - Permadeath - A text-based terminal interface - Players navigate with arrow keys, fight bugs, collect items, and search for the exit. - When the player’s HP reaches zero, the run ends and they must start over. - The Copilot CLI `/yolo` command, an alias for `/allow-all`, reinforces the game’s one-life theme. ## Building with GitHub Copilot CLI - The author began with a high-level prompt asking Copilot to build a Go-based GitHub CLI extension using BSP-generated dungeons. - The `/delegate` command sent feature requests to Copilot’s cloud-based coding agent. - Copilot worked asynchronously and returned changes through pull requests. - Example delegated work included progressively harder levels with: - More enemies - Additional health potions - The author reviewed and refined Copilot’s output, including cheat codes for invincibility. - Copilot also generated a “dungeon scribe” agent that created documentation and ASCII diagrams explaining dungeon generation. - This workflow allowed the author to concentrate on mechanics, balance, player experience, and easter eggs rather than boilerplate and scaffolding. ## Binary Space Partitioning - Binary Space Partitioning (BSP) generates the dungeon by repeatedly dividing a large area into smaller regions. - The process begins with one rectangle representing the entire map. - That space is recursively split into smaller sections, which can then be used to place rooms and connect them. - BSP suits roguelikes because it balances: - Structure, avoiding chaotic layouts - Replayability through controlled randomness - Navigation, by supporting connected maps - The technique naturally produces clean rectangular rooms while retaining variation between generated levels. GitHub Dungeons shows how repository data, classic roguelike mechanics, and AI-assisted coding can combine into a playful development experiment. Using Copilot as an implementation partner lets the developer iterate quickly while remaining focused on designing an enjoyable game.

Improving token efficiency in GitHub Agentic Workflows (opens in new tab)

GitHub’s Agentic Workflows can quietly accumulate substantial token costs because they run automatically in CI. GitHub improved efficiency by instrumenting token usage, auditing workflows, pruning unused MCP tools, and replacing many MCP data-fetching calls with deterministic GitHub CLI commands. Early results show that reducing context and removing unnecessary LLM reasoning can save thousands of tokens per run, though measuring true efficiency requires accounting for model choice and workload quality. ## Logging Token Usage - GitHub runs hundreds of agentic workflows against real GitHub Actions limits. - Different agent frameworks produced incompatible usage logs, so GitHub used its API proxy to normalize data across Claude CLI, Copilot CLI, and Codex CLI. - Each workflow now emits a `token-usage.jsonl` artifact containing: - Input, output, cache-read, and cache-write tokens - Model and provider - Timestamps - One record per API call - These records make it possible to compare historical runs and identify recurring sources of waste. ## Automated Auditing and Optimization - A daily **Token Usage Auditor** aggregates recent usage by workflow and reports: - Significant increases in token consumption - The most expensive workflows - Anomalous runs, such as a workflow taking 18 LLM turns instead of its usual four - A daily **Token Optimizer** examines flagged workflows, their source YAML, and recent logs. - It creates GitHub Issues with concrete inefficiencies and recommended fixes. - The auditing workflows also consume tokens, creating a feedback loop in which their own costs are monitored. ## Removing Unused MCP Tools - MCP tool names and JSON schemas are typically included in every stateless LLM request. - A GitHub MCP server with roughly 40 tools can add 10–15 KB of schema to every turn. - If a workflow uses only two tools, the other 38 create repeated overhead without adding value. - GitHub compares configured tools with actual tool calls and recommends removing unused registrations. - In smoke tests, pruning tools reduced each call’s context by 8–12 KB and saved several thousand tokens per run without changing behavior. ## Replacing MCP Calls with GitHub CLI - GitHub found larger savings by replacing MCP calls for predictable data retrieval—such as pull request diffs, file contents, and review comments—with `gh` commands. - MCP calls require an additional reasoning cycle: the model chooses a tool, constructs arguments, and processes the response. - Commands such as `gh pr diff` make deterministic API requests without involving the LLM in the retrieval step. Two migration patterns were used: - **Pre-agentic downloads** - Workflow setup steps run `gh` commands before the agent starts. - Results such as diffs and changed-file lists are saved to workspace files. - The agent reads the files directly, eliminating MCP round trips. - **In-agent CLI proxy substitution** - When data must be selected dynamically, the agent runs commands such as `gh pr view --json`. - A transparent proxy routes CLI requests to GitHub’s API without exposing credentials. - This preserves the zero-secrets security model while avoiding MCP overhead. ## Measuring Efficiency - Lower token counts do not necessarily mean better workflows; a workflow may simply be doing less work. - Model selection also affects cost. Claude Haiku and Sonnet may use similar numbers of tokens, but Haiku is substantially cheaper. - GitHub therefore uses an **Effective Tokens (ET)** metric that weights usage by token type and model cost: ```text ET = m × (1.0 × I + 0.1 × C + 4.0 × O) ``` - `m` represents the model multiplier: Haiku `0.25×`, Sonnet `1.0×`, and Opus `5.0×`. - `I` is newly processed input, `C` is cache-read tokens, and `O` is output tokens. - Output tokens receive greater weight because they are typically the most expensive component. GitHub’s experience suggests that agentic workflow authors should measure usage continuously, remove tools that workflows do not actually use, and move routine API retrieval outside the LLM reasoning loop wherever possible.