| 1 | --- |
| 2 | title: Working with agents |
| 3 | description: How coding agents, and people at a terminal, work on work items. Load a work item's whole context in one call, claim it, open a pull request for it, and use g1t work, the work_item MCP tool and the REST API. What the Claude Code plugin and the work-on-item skill do. |
| 4 | --- |
| 5 | |
| 6 | Coding agents work on work items the way people do, through the same |
| 7 | calls: the [g1t CLI](/guides/cli/), the [MCP server](/reference/mcp/) and |
| 8 | the [REST API](/reference/api/). g1t runs no model: work happens in your |
| 9 | own harness, with your own agent, and g1t ties it back to the work item. |
| 10 | To connect one, see [connect a coding agent](/guides/bring-your-own-agent/). |
| 11 | |
| 12 | ## How an agent works on a work item |
| 13 | |
| 14 | 1. **Load its context**: `g1t work view 12`, or the `work_item` tool's |
| 15 | `work`. One call has everything: what done means, where it should land |
| 16 | and where it has, who is on it, its pull requests and what blocks it. |
| 17 | See [pick up a work item](#pick-up-a-work-item). |
| 18 | 2. **Claim it**: `g1t work claim 12 --note "…"`, or `work_item` `claim`. |
| 19 | The answer says who else is on it. See |
| 20 | [claims](/work/claims-and-dependencies/#claims). |
| 21 | 3. **Open a pull request for it** in the repository the change is for: |
| 22 | `g1t pr create --item 12`, or `pull_request` `create` with `item`. See |
| 23 | [open a pull request for it](#open-a-pull-request-for-it). |
| 24 | 4. **Push commits** with the session's trailer, |
| 25 | `git commit --trailer "G1t-Session: $G1T_SESSION"`, and watch the |
| 26 | checks: `g1t pr checks --watch`. |
| 27 | 5. **Mark it ready** with a summary: `g1t pr ready`, or `pull_request` |
| 28 | `ready`. When it merges, it [lands the work item](/work/closing/) in |
| 29 | that repository. |
| 30 | 6. **Hand it off** if it stops before the work is done: |
| 31 | `g1t work handoff 12 --note "…"`. |
| 32 | |
| 33 | All along, its [session](/work/sessions/) records what it does, and its |
| 34 | [coordination updates](/work/claims-and-dependencies/#coordination-updates) |
| 35 | say what changed around it. |
| 36 | |
| 37 | ## Pick up a work item |
| 38 | |
| 39 | A work item's **work context** is everything about it in one call: |
| 40 | `g1t work view 12`, `work_item` with `"action": "work"` over MCP, or |
| 41 | [`GET /workspaces/{workspace}/work/{number}/work`](/reference/api/work-items/get-work/): |
| 42 | |
| 43 | ```sh |
| 44 | curl https://api.g1t.sh/workspaces/acme/work/12/work \ |
| 45 | -H "Authorization: Bearer $G1T_TOKEN" |
| 46 | ``` |
| 47 | |
| 48 | | Field | What it holds | |
| 49 | | --- | --- | |
| 50 | | `item` | The work item, with its description. | |
| 51 | | `definition_of_done` | The items under its **Definition of done** heading. | |
| 52 | | `repos` | Its repositories, each with its `role`, whether it has `landed`, its old issue number (`legacy_number`), the `required_checks` its default branch requires, and its `pulls` for the work item. Those still open or draft carry their checks as they stand on the head, `mergeable`, the other pull requests they `overlaps` with, and their place in the merge `queue`. | |
| 53 | | `missing` | Its targets that have not landed yet. | |
| 54 | | `suggested_targets` | Up to five repositories of the workspace it may also need, each with `path` and `why`. See [suggested targets](/work/work-items/#suggested-targets). | |
| 55 | | `claims` | Who says they are working on it now. | |
| 56 | | `sessions` | Sessions on it or its pull requests, or tied to it any other way, subagents included, those still going first; up to 50. Each says how many `subagents` it started. | |
| 57 | | `blocked_by` | Each work item it waits on, with that work item's claims and pull requests. | |
| 58 | | `blocks` | The work items waiting on it. | |
| 59 | | `decisions` | [Decision records](/guides/why-blame/#decision-records) on it and its pull requests, newest first; up to 20. | |
| 60 | | `last_integration_failure` | The latest `integration_failure` decision among them, if any: the combination that failed in the merge queue, the check, the `suspects` and, when it failed on `main` alone, the pull requests that `landed` on `main` since it branched. | |
| 61 | | `recent` | Its latest 20 coordination events, newest first. | |
| 62 | |
| 63 | `g1t work view 12` prints the same: its description and definition of |
| 64 | done, its repositories with their pull requests, checks and overlaps, |
| 65 | **Still to land in**, **Suggested targets** (with the |
| 66 | `g1t work link 12 --repo owner/name` that adds one), its claims, sessions, |
| 67 | what blocks it and what it blocks, the last integration failure, its |
| 68 | decisions and what happened lately. A target the work needs that is not |
| 69 | linked yet is worth linking before starting: |
| 70 | |
| 71 | ```sh |
| 72 | g1t work link 12 --role target --repo acme/docs |
| 73 | ``` |
| 74 | |
| 75 | ## Open a pull request for it |
| 76 | |
| 77 | `g1t pr create --item 12`, or `pull_request` `create` with `item: 12`, |
| 78 | opens a pull request for the work item in the repository it runs in: |
| 79 | |
| 80 | - Without a branch, g1t makes a |
| 81 | [working copy](/concepts/forks/#working-copies-for-pull-requests) for |
| 82 | it and opens a **draft**. The answer has the pull request and the git |
| 83 | remote of its working copy, to clone and push to. |
| 84 | - With a `branch` already pushed, it opens the pull request from it. |
| 85 | |
| 86 | Its title is the work item's unless you give one. The work item notes |
| 87 | **opened acme/web#14 for this**, and the repository is linked as |
| 88 | `touched` unless it is already a target. When the pull request merges |
| 89 | into the default branch, it lands the work item there; see |
| 90 | [closing work items](/work/closing/). |
| 91 | |
| 92 | ```json |
| 93 | { "name": "pull_request", "arguments": { "action": "create", "repo": "acme/web", "item": 12 } } |
| 94 | ``` |
| 95 | |
| 96 | ## Work with no work item yet |
| 97 | |
| 98 | Most of what an agent is asked starts without a work item, and a question, |
| 99 | a look around or a quick fix never needs one. The session is recorded |
| 100 | anyway, and shows on [Sessions](/work/sessions/) and the project's |
| 101 | **Live now**. When the work becomes a change others should know about (a |
| 102 | branch to push, a pull request), the agent looks for its work item |
| 103 | (`g1t work list`, `work_item` `list` or `list_claims`), and claims it. If |
| 104 | there is none, it files one and claims it in one step: |
| 105 | |
| 106 | ```sh |
| 107 | g1t work claim --title "Preview builds time out on large repositories" |
| 108 | ``` |
| 109 | |
| 110 | See [work with no work item yet](/guides/sessions/#work-with-no-work-item-yet). |
| 111 | |
| 112 | ## The CLI |
| 113 | |
| 114 | `g1t work` works on the current repository's workspace, or the one in |
| 115 | `--workspace` (or the `G1T_WORKSPACE` environment variable). `-R` (or |
| 116 | `--repo`) `owner/name` names a repository instead of the current one: it |
| 117 | filters `g1t work list`, and is the repository `g1t work link` and |
| 118 | `g1t work unlink` act on. Every command takes `--json`. |
| 119 | |
| 120 | | Command | Does | |
| 121 | | --- | --- | |
| 122 | | `g1t work list` | Lists open work items. `-R`, `--state` (`open`, `closed` or `all`), `--label`, `--milestone`, `--assignee` and `--author` narrow it; with `-R`, `--role` keeps those linked to the repository in one role. | |
| 123 | | `g1t work view N` | Shows its [work context](#pick-up-a-work-item). `--comments` adds its comments, `--web` opens it in the browser. | |
| 124 | | `g1t work new` | Files a work item; `--target` for each repository it should land in, `--label`, `--assignee`, `--milestone`. `--attach FILE` adds an image to its description: uploaded to the repository it is filed from, or, filed in the workspace alone, to the work item once it is open. | |
| 125 | | `g1t work comment N` | Comments on it. `--attach FILE` uploads an image to the work item and adds it to the comment. | |
| 126 | | `g1t work edit N` | Changes its title, description, labels, assignees or milestone. | |
| 127 | | `g1t work close N` | Closes it, as completed, or `--reason not_planned`; `--comment` says why. `--commit SHA` names a commit on the default branch that did it, which lands it there. See [closing work items](/work/closing/). | |
| 128 | | `g1t work reopen N` | Opens it again. | |
| 129 | | `g1t work link N` | Links a repository in a role: `--role target` (the default) or `touched`, the current repository or `-R owner/name`. | |
| 130 | | `g1t work unlink N` | Unlinks a repository, never its origin. | |
| 131 | | `g1t work claim N` | Says you are working on it, with `--note` and `--ttl`. With `--title` instead of a number, files a work item and claims it. | |
| 132 | | `g1t work release N` | Lets go of your claim. | |
| 133 | | `g1t work handoff N` | Hands it to someone else (`--to`), or to anyone, with a `--note`. | |
| 134 | | `g1t work status` | The repository's active claims and sessions. | |
| 135 | | `g1t work block N --by M` | Says it waits on work item M; `g1t work unblock N --by M` takes that back. | |
| 136 | | `g1t work events` | The repository's events; `--follow` keeps printing them, `--item N` for one work item. | |
| 137 | | `g1t work dispatch N` | Starts work on it in a session on your own Claude, or prints the Claude Code command for it. See [start a session on your Anthropic account](/guides/sessions/#start-a-session-on-your-anthropic-account). | |
| 138 | |
| 139 | [CLI commands](/reference/cli/#g1t-work) lists every flag. |
| 140 | |
| 141 | ## MCP and the API |
| 142 | |
| 143 | The MCP server's `work_item` tool takes an `action`: `list`, `get`, |
| 144 | `create`, `update`, `close`, `reopen`, `links`, `link`, `unlink`, |
| 145 | `labels`, `add_labels`, `set_labels`, `remove_labels`, `comment`, |
| 146 | `edit_comment`, `delete_comment`, `react`, `attach`, `decisions`, |
| 147 | `resolve` (what `#N` names), `import`, `work`, `claim`, `release`, |
| 148 | `handoff` and `list_claims`. It takes `workspace` and `number`; `repo` is |
| 149 | optional, as the origin of a new work item, a filter, or to find the |
| 150 | workspace. A workspace's labels and milestones are on the `workspace` |
| 151 | tool, and a repository's work items are the `repository` tool's `work`. |
| 152 | See [MCP tools](/reference/mcp/#work_item). |
| 153 | |
| 154 | The REST API has the same under `/workspaces/{workspace}/work`: |
| 155 | |
| 156 | | To | REST | |
| 157 | | --- | --- | |
| 158 | | List work items | `GET /workspaces/{workspace}/work` | |
| 159 | | File one | `POST /workspaces/{workspace}/work` | |
| 160 | | Get one | `GET /workspaces/{workspace}/work/{number}` | |
| 161 | | Change one | `PATCH /workspaces/{workspace}/work/{number}` | |
| 162 | | Close or reopen it | `POST /workspaces/{workspace}/work/{number}/close` (with `reason`, or `repo` and `commit`), `…/reopen` | |
| 163 | | Its repositories | `GET /workspaces/{workspace}/work/{number}/links` | |
| 164 | | Link or unlink a repository | `POST` or `DELETE /workspaces/{workspace}/work/{number}/links` | |
| 165 | | Its labels | `GET`, `POST`, `PUT` or `DELETE /workspaces/{workspace}/work/{number}/labels`, `DELETE …/labels/{label}` | |
| 166 | | Comment | `POST /workspaces/{workspace}/work/{number}/comments`; `PATCH` or `DELETE /workspaces/{workspace}/work/comments/{id}` | |
| 167 | | React | `POST /workspaces/{workspace}/work/{number}/reactions` | |
| 168 | | Upload an image for it | [`POST /workspaces/{workspace}/work/{number}/attachments`](/reference/api/work-items/upload-work-item-attachment/), with `work:write`; anyone who may comment on it may | |
| 169 | | Its decisions, with its pull requests' | `GET /workspaces/{workspace}/work/{number}/decisions` | |
| 170 | | Watch it | `GET`, `PUT` or `DELETE /workspaces/{workspace}/work/{number}/subscription` | |
| 171 | | Its work context | `GET /workspaces/{workspace}/work/{number}/work` | |
| 172 | | Claim, release, hand off | `POST /workspaces/{workspace}/work/{number}/claim`, `…/release`, `…/handoff` | |
| 173 | | Bring work items in from a tracker | `POST /workspaces/{workspace}/work/import` | |
| 174 | | A repository's work items | `GET /repos/{owner}/{name}/work` | |
| 175 | | What `#N` names | `GET /repos/{owner}/{name}/refs/{number}`, or `GET /workspaces/{workspace}/refs/{number}` | |
| 176 | | The workspace's labels and milestones | `/workspaces/{workspace}/labels`, `/workspaces/{workspace}/milestones` | |
| 177 | |
| 178 | ```sh |
| 179 | curl -X POST https://api.g1t.sh/workspaces/acme/work \ |
| 180 | -H "Authorization: Bearer $G1T_TOKEN" \ |
| 181 | -H "Content-Type: application/json" \ |
| 182 | -d '{"title": "Sign-in times out", "repo": "acme/web", "targets": ["acme/web", "acme/api"]}' |
| 183 | ``` |
| 184 | |
| 185 | A work item has `workspace`, `number`, `title`, `body`, `state`, `reason`, |
| 186 | `labels`, `milestone`, `assignees`, `blocked_by`, `repos` (each with |
| 187 | `path`, `role`, `landed` and, for one that was an issue, its |
| 188 | `legacy_number`) and `resolutions` (each with `repo` and the `pull` or |
| 189 | `commit` that landed it). Reading work items needs a token with |
| 190 | `work:read`, and changing them `work:write`. |
| 191 | |
| 192 | ## The Claude Code plugin |
| 193 | |
| 194 | The [Claude Code plugin](/guides/claude-code-plugin/) does the |
| 195 | bookkeeping for Claude Code, so Claude works on work items the way this |
| 196 | page describes without being told each time: |
| 197 | |
| 198 | - **At the start of a session**, in a working copy of a g1t repository, |
| 199 | it finds the work item: the one the session claimed before, `G1T_ITEM`, |
| 200 | or one named by the branch (`42-fix-login`, `item-42`, `fix/42`). It |
| 201 | gives Claude that work item's context (`g1t work view`) and tells it to |
| 202 | claim it. With none, it tells Claude to just work, and to claim or file |
| 203 | a work item only once the work becomes a change. |
| 204 | - **It records the session**: its prompts, its tool calls (never what |
| 205 | they returned), the files, commits and branches it touched, and each |
| 206 | subagent as a session of its own. |
| 207 | - **It ties the session to the work item** Claude claims, starts a pull |
| 208 | request for, or attaches to, and gives Claude `G1T_SESSION` for the |
| 209 | commit trailer. It never claims anything itself. |
| 210 | - **It shows coordination updates** before Claude's tools and prompts, |
| 211 | until they are acknowledged. |
| 212 | - It adds g1t's MCP server, the skills below, and the `/g1t:claim`, |
| 213 | `/g1t:handoff` and `/g1t:status` commands. |
| 214 | |
| 215 | The plugin's hooks need the g1t CLI 0.4.0 or later. |
| 216 | |
| 217 | ### The work-on-item skill |
| 218 | |
| 219 | `/g1t:work-on-item 12` (or asking Claude to work on a work item) takes it |
| 220 | from start to merge: |
| 221 | |
| 222 | 1. Read the work item: `g1t work view 12`. |
| 223 | 2. Check who else is on it and what it waits on, carry on an existing pull |
| 224 | request rather than start another, and link a target the work needs. |
| 225 | 3. Claim it, with a note on its scope, the interfaces it touches, what it |
| 226 | depends on and the checks it will run. |
| 227 | 4. Make a branch named after it, `12-…`. |
| 228 | 5. Open a draft pull request early: `g1t pr create --item 12 --draft --fill`. |
| 229 | 6. Commit with the `G1t-Session` trailer, and push often. |
| 230 | 7. Watch the checks (`g1t pr checks --watch`), and read a failure's logs. |
| 231 | 8. Mark it ready with a summary, and merge. A pull request that does only |
| 232 | part of the work says `Part of #12`; the last says `Closes #12`. |
| 233 | 9. Hand it off with a note if it stops before the work is done. |
| 234 | |
| 235 | Work that has no work item yet starts by looking for one, then |
| 236 | `g1t work claim --title`. Alongside it, the **coordinate** skill keeps a |
| 237 | long session in step with others, and **fix-integration** fixes a pull |
| 238 | request the merge queue found failing together with others. Sessions g1t |
| 239 | starts on your Anthropic account use the same skills. |
| 240 | |
| 241 | ## Hand a work item to g1t |
| 242 | |
| 243 | You can also hand a work item to a session g1t starts for you, on the |
| 244 | workspace's own Anthropic account: **Start a session** on its page, |
| 245 | **Assign to g1t**, `@g1t` in a comment, or `g1t work dispatch 12`. See |
| 246 | [start a session on your Anthropic account](/guides/sessions/#start-a-session-on-your-anthropic-account) |
| 247 | and [assign g1t, or ask it in the thread](/guides/sessions/#assign-g1t-or-ask-it-in-the-thread). |