Skip to content
Good Grief

What Good Grief is

Good Grief is an orchestration framework for AI agents. An organisation defines the kinds of work its agents do, and each kind can run on a regular schedule or be started by hand. All work follows a formal, managed set of rules: what an agent may do, how long it may take, what a person must approve, and where the result may go.

Its first use is software development, such as investigating a bug or building a feature in an organisation’s repositories. The same framework can orchestrate other kinds of work.

All of it happens through gg, a single command-line tool. gg has two roles:

  • The console. Running gg with no arguments opens a terminal application for starting work, following what is running, and answering anything that is waiting on a person.
  • The runner. Running gg runner up on a machine makes that machine take work and carry it out. It clones the repository, runs the agent, and reports what happened.

Code stays where it is

Section titled “Code stays where it is”

gg talks to a service called the control plane. The control plane keeps the record of the work: what was asked for, who approved what, and how each piece ended. It never sees the code or the credentials. The runner clones repositories, holds credentials and runs agents, all on machines the organisation controls. What it sends to the control plane are facts about the work, never the work itself.

Terms that appear first

Section titled “Terms that appear first”

Good Grief borrows a few terms from aviation. These are the ones that appear first:

  • A flight is one piece of requested work, such as finding out why login times out. Every flight has a number, such as GG-42.
  • A runner is a machine that picks up flights and works on them.
  • The envelope is the organisation’s set of rules for flights. It says which agent runs, how long it may take, which files it may change, and where finished work may go.
  • A gate is a point where a flight waits for a person to approve or reject something. Nothing behind a gate proceeds until someone answers.
  • The airspace is where the organisation keeps its rules and names: the repositories it works on, the kinds of work it does, and the machines it has.
  • A watch is a standing instruction to look at something on a schedule, such as a queue of work items. Each run of a watch is a sweep.
  • A nomination is a proposal that some work should become a flight, usually made by a sweep.
  • The board is where nominations wait until a person opens one as a flight or declines it.
  • An itinerary is a plan made of several flights, called legs, that pursue one goal. A person, or a planning flight, proposes it, and its legs open as flights once the plan is approved.

The glossary covers the rest. This is how the terms fit together:

How the terms relateA person opens a flight with gg fly; an itinerary, a plan of several flights, opens each of its legs as a flight once it is approved; or a watch runs sweeps that make nominations, which wait on the board until a person opens one as a flight. The envelope, made of root, the work kind and narrowings, governs the flight. A runner flies it, it may stop at a gate for a person, and it lands at a destination.Enveloperoot + work kind + narrowingsgovernsFlightone piece of workItinerarya plan of several flightsits legs open asA personasks for workgg flyOn a scheduleWatchwhat to look atSweepa run of a watchNominationsproposed workBoardwhere they waita person opens oneRunnerthe machine flying itflown byGatea person approvesstops atDestinationwhere work landslands at

A flight from start to finish

Section titled “A flight from start to finish”
A flight from start to finishA flight is created, waits on the ground until a machine is free, takes off when a runner leases it, is worked by the agent at cruising height, is evaluated on the way down, where it may wait at a gate for a person or be sent back for another attempt, and ends: landed, failed, grounded or withdrawn. A request can also be rejected when the flight is opened.1 Createdrules worked out2 Readywaits for a machine3 Leaseda runner takes it4 Workedthe agent works5 Evaluatedrules are checked6 Endedlanded · failedgrounded · withdrawnor rejected when openedsent back: another attemptGatemay wait for a person
  1. Someone asks for a piece of work: gg fly "why does login time out after an hour?"
  2. The control plane checks the organisation’s rules, and the flight waits for a runner that is allowed to take it.
  3. A runner takes the flight, runs the agent, and reports what it found or changed.
  4. If the rules require a person to approve something, such as a pull request, the flight stops at a gate until someone does.
  5. The flight ends. It lands when the work was accepted somewhere. Otherwise it ends in one of a few other ways, and it always records which one.

First flight walks through these steps with real commands. Anatomy of a flight describes each step in detail.