Working with agents

g2g is built so that a program can drive it without a person watching every step. Three properties make that safe: it previews before it acts, it refuses anything ambiguous and names the fix, and its exit status says exactly how far it got.

It previews before it acts

Every command that changes anything runs as a preview unless it is given --apply. With --apply it re-discovers the state and revalidates it against the preview before mutating, renders and flushes the final plan first, and refuses ambiguous or unsafe work instead of guessing. On failure it never claims that changes were made. See Preview and apply.

The one exception is moving the checkout with up, down, top and bottom. They change no ref, record or remote, and git switch already refuses to overwrite a local change. They offer --dry-run to say where they would go without moving.

Nothing is recorded without an explicit --apply either: observing a pull request base or inferring an ancestry edge produces a preview, never a record.

It refuses rather than guesses

Wherever there is more than one reasonable answer, g2g stops and asks for one:

• track without --parent lists the candidate parents and blocks. It never picks for you.
• up, down, top and bottom refuse at a fork and name the branches above.
• A trunk is never guessed from a branch’s name.
• A branch with two open pull requests refuses, because nothing here can tell which one you meant.
• The commands that publish to a GitHub native stack refuse a selection that forks rather than choosing a line through it.
• g2g never runs Graphite in a repository that does not already use it.

A blocked preview names the command that repairs the state. In --json the reason is blocked, and the ways out are repair, each carried as a command and what running it achieves, so an agent does not have to find the command inside a sentence. A way out with no command is a real answer that is not a thing to run, such as “fetch and reconcile first”. See When a command refuses.

Its exit status is reliable

Status	Meaning
0	it did what was asked, or there was nothing to do
1	doctor only: it found something that needs putting right
2	it failed, and achieved nothing
3	it did part of what was asked and stopped somewhere you have to act

3 is not a failure to retry and not a success: what replayed stays replayed and what merged stays merged. The output says what happened and what to do next, and the status lets something reading only the status tell the difference. See Exit status.

Read the machine output, not the picture

Prefer --json or --porcelain to parsing the human preview. Both are renderers over the same validated view, both suppress colour and every human-facing line, and schemaVersion changes when a field changes meaning or disappears. blocked is reported alongside command, not instead of it, so check blocked before acting on command. See Output.

A loop an agent can follow

1. Start with g2g status (offline, the stack you are on) or g2g doctor (offline, every stack, only what is wrong). Reach for g2g github status when the question is about pull requests.
2. Run the command bare and read the preview.
3. If it is blocked, act on repair rather than on the sentence.
4. Add --apply.
5. Read the exit status, and on 3 read the output for what to do next.

Know which commands reach GitHub. pull never changes GitHub; the commands that do are submit, land, and everything under g2g github except status and adopt.

To open pull requests without an editor, generate a spec in a private temporary directory, fill in each title, validate it, then apply it:

spec_dir="$(mktemp -d)"
g2g submit --write-spec "$spec_dir"
g2g submit --spec "$spec_dir/submission.json"
g2g submit --spec "$spec_dir/submission.json" --apply

If apply fails, the spec stays in place and the error gives the exact repair, validation and retry commands. A repository with more than one pull request template needs --template <name> or --no-template; g2g never guesses. See Push and submit.

The g2g skill

Install the g2g skill so an agent knows all of the above without being told:

npx skills add shhac/agent-skills --skill g2g --global

--global installs it for your user; drop it to install into the current project only, and run npx skills update to keep it current. The skill is published from shhac/agent-skills. It documents the CLI and does not install it, so the agent still needs g2g from Homebrew (see Install).

Its source lives in the g2g repository at skills/g2g/SKILL.md. It covers both using g2g safely and developing it. Among other things, it tells an agent to:

• Find the command once at the start of a task: try g2g --version, then gt2gh --version, which is worth one attempt only for an install predating the rename. If neither works, the user must run brew install shhac/tap/g2g or provide a built binary.
• Record the command it found and use it for every later invocation, rather than detecting it again.
• Use the command’s --help to inspect the current interface.
• Read the preview before any --apply.

For work on g2g itself, AGENTS.md holds the process knowledge that is easy to miss, and points back to the skill as the place to start.