| 1 | --- |
| 2 | title: Sessions, claims and dependencies |
| 3 | description: How agents and people on one repository see who is working on what, with sessions of their own harnesses, advisory claims on work items, what a work item is blocked by, and the one call that loads a work item's whole context. |
| 4 | --- |
| 5 | |
| 6 | When several agents and people work on one repository at once, each needs |
| 7 | to know what the others are doing. g1t keeps that around the |
| 8 | [work item](/guides/work-items/), which is the unit of work: its |
| 9 | description says what is wanted and what done means, its pull requests are |
| 10 | the proposals, and around it g1t records: |
| 11 | |
| 12 | - **Sessions**: one run of your own harness (a Claude Code session, a |
| 13 | Codex run) on the repository, attached to the work item and pull request |
| 14 | it works on. A session is recorded in the repository it is checked out |
| 15 | in; its work item is the workspace's. |
| 16 | - **Claims**: an advisory, expiring "I'm working on #12". Never a lock. |
| 17 | - **Dependencies**: the work items that have to land before this one. |
| 18 | |
| 19 | Until there is a work item, the session is the unit: work that starts from |
| 20 | a question or a quick request is recorded as a session titled with what it |
| 21 | is for, and shows to the team on its branch or pull request. It opens or |
| 22 | claims a work item only when it becomes a change others should know about; |
| 23 | see [Work with no work item yet](#work-with-no-work-item-yet). |
| 24 | |
| 25 | Nothing here waits on a harness. A harness that crashes, loses its |
| 26 | network or sends the same thing twice does no harm: sessions and claims |
| 27 | that go quiet are read as idle, ended or expired the next time anyone |
| 28 | looks, and starting a session or recording an entry again is a no-op. |
| 29 | What git and g1t record (commits, pull requests, checks, merges) is the |
| 30 | truth; sessions are the account of how it got there. |
| 31 | |
| 32 | ## On the site |
| 33 | |
| 34 | Everything here shows on g1t.sh as it happens, without reloading. |
| 35 | |
| 36 | - **The Sessions page**, `g1t.sh/<owner>/<repo>/sessions`, a tab beside |
| 37 | **Pull requests** and **Merge queue** (it used to be the repository's |
| 38 | **Work** page, and the old address redirects here): |
| 39 | - **Live now**: the active claims and the active and idle sessions, |
| 40 | grouped by the work item they are on, the most recently active first. |
| 41 | A work item with more than one claim is marked. Sessions on no work |
| 42 | item yet follow, grouped by their pull request, else by their branch (when it |
| 43 | is not the default branch), the most recently heard from first; those |
| 44 | on neither are last, under **No branch yet**. Each session shows its |
| 45 | title, who it acts for, its harness, its state, when it was last heard |
| 46 | from and its branch. A session with no title is named by what its |
| 47 | first prompt was for, else **Session on** its branch, else **Untitled |
| 48 | session**. A title that is only a tag, such as |
| 49 | `<pasted_content id="5c50">`, counts as no title. |
| 50 | - **Merge queue**: what is waiting to land and what is being tested, |
| 51 | as on the [Merge queue](/guides/merge-queue/#the-merge-queue-page) page. |
| 52 | - **What happened**: the latest 30 coordination events, from claims to |
| 53 | what the merge queue found when it combined changes. |
| 54 | - **Just landed**: the latest merges, each with a link to the session |
| 55 | behind it. |
| 56 | |
| 57 | With nothing going on, choose your client in the |
| 58 | [connection instructions](/guides/bring-your-own-agent/), or run |
| 59 | `g1t work claim <number>` from any harness. |
| 60 | - **A work item's Work panel**, at the top of its sidebar: its claims |
| 61 | (who, from which harness, since when and when each lapses; ones |
| 62 | released, expired or handed off lately are shown dimmed), the sessions on |
| 63 | it with their state and when each was last heard from, what |
| 64 | it is blocked by and where each of those stands, and the work items it |
| 65 | blocks. Its author and anyone with the Triage role change what it is |
| 66 | blocked by with **Edit**. Under its pull requests, the work item shows |
| 67 | the latest combination that failed in the merge queue, and its |
| 68 | [decision records](/guides/why-blame/#decision-records), each marked |
| 69 | **Claimed**, **Tested** or **Approved**. |
| 70 | - **A session's page**, `g1t.sh/<owner>/<repo>/sessions/<id>`, |
| 71 | opened from any of these: who ran it, in which harness and on which |
| 72 | model, how long it has run, the work items and pull requests it and its |
| 73 | subagents worked on (each says how it was tied), its subagents as a tree |
| 74 | you open one at a time (each with its kind, the task it was given, what |
| 75 | it touched and what it reported), the skills used, what was touched |
| 76 | (files, commits, branches, pull requests), and everything it recorded, |
| 77 | as it records it: its prompt folded, its messages formatted as they were |
| 78 | written, and the tool calls between them a line each (a command as code, |
| 79 | a file by its path, a g1t tool by what it did, such as *work item · claim*), |
| 80 | more than three in a row folded into one line that opens to them; a |
| 81 | long command and what a tool gave back open under its line. A |
| 82 | subagent's own page links back to the session that started it. |
| 83 | - **A work item's and a pull request's sessions**: every session tied to |
| 84 | it in any way, in any of the workspace's repositories, with its |
| 85 | subagents under it. |
| 86 | - **Start a session** on a work item, for members of a workspace with an |
| 87 | Anthropic AI provider: see |
| 88 | [Start a session on your Anthropic account](#start-a-session-on-your-anthropic-account). |
| 89 | |
| 90 | ## Picking up a work item |
| 91 | |
| 92 | Before working on a work item, load its whole context in one call: |
| 93 | `work_item` with `"action": "work"` over MCP, `g1t work view 12`, or |
| 94 | [`GET /workspaces/{workspace}/work/{number}/work`](/reference/api/work-items/get-work/): |
| 95 | |
| 96 | ```sh |
| 97 | curl https://api.g1t.sh/workspaces/acme/work/12/work \ |
| 98 | -H "Authorization: Bearer $G1T_TOKEN" |
| 99 | ``` |
| 100 | |
| 101 | | Field | What it holds | |
| 102 | | --- | --- | |
| 103 | | `item` | The work item, with its body and its repositories: each with its role and whether it has landed. | |
| 104 | | `missing` | Its targets that have not landed yet. | |
| 105 | | `suggested` | Repositories of the workspace it may also need, each with `why`. | |
| 106 | | `definition_of_done` | The items under its **Definition of done** heading. | |
| 107 | | `required_checks` | The checks every pull request into the default branch must pass. | |
| 108 | | `claims` | Who says they are working on it now. | |
| 109 | | `sessions` | Sessions on it or its pull requests, or tied to it any other way, subagents included, active ones first. Each says how many `subagents` it started. | |
| 110 | | `pulls` | Its pull requests, in every repository it links. Those still open or draft carry their `required_checks` as they stand on the head, `mergeable`, the other pull requests they `overlap`, and their place in the merge `queue`. | |
| 111 | | `blocked_by` | Each work item it waits on, with that work item's claims and pull requests. | |
| 112 | | `blocks` | The work items waiting on it. | |
| 113 | | `decisions` | [Decision records](/guides/why-blame/#decision-records) on it and its pull requests, newest first. | |
| 114 | | `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. | |
| 115 | | `recent` | Its latest 20 coordination events, newest first. | |
| 116 | |
| 117 | Then claim it, and start (or attach) your session. |
| 118 | |
| 119 | ## Sessions |
| 120 | |
| 121 | A session is one run of your harness on a repository. Start one when the |
| 122 | harness starts, keep it alive while it works, and end it when it stops. |
| 123 | |
| 124 | 1. **Start** it with `session` `start`, or |
| 125 | [`POST /repos/{owner}/{name}/sessions`](/reference/api/sessions/start-session/), |
| 126 | naming the `harness` (`claude_code`, `claude_managed_agents`, `codex`, |
| 127 | `cursor`, `copilot` or `other`) and the harness's own id for the session as |
| 128 | `harness_session_id`. Starting again with the same id returns the |
| 129 | session already started, so a hook can call it every time without |
| 130 | checking first. Give `item` (the work item's number in the |
| 131 | repository's workspace), `pull` and `branch` when you know them, and a |
| 132 | `title`: what the session is for, in a few words (up to 200 |
| 133 | characters). |
| 134 | 2. **Heartbeat** with `session` `update`, or |
| 135 | [`PATCH /repos/{owner}/{name}/sessions/{id}`](/reference/api/sessions/update-session/) |
| 136 | with an empty body. The same call attaches the session to a work item |
| 137 | or pull request, records the `head_commit` it pushed, or changes its |
| 138 | `title`. |
| 139 | 3. **Record** what happens with `session` `record`, or |
| 140 | [`POST /repos/{owner}/{name}/sessions/{id}/entries`](/reference/api/sessions/record-session-entries/): |
| 141 | prompts, reasoning, tool calls, notes and the skills it used (`skill`, |
| 142 | the skill's name only), up to 200 a request, and in `touched` what it |
| 143 | touched (see [What a session worked on](#what-a-session-worked-on)). |
| 144 | Give each entry a `key`, and recording it again does nothing. |
| 145 | 4. **End** it with `session` `end`, or |
| 146 | [`POST /repos/{owner}/{name}/sessions/{id}/end`](/reference/api/sessions/end-session/), |
| 147 | with its `result` when it has one: what it reported when it finished. |
| 148 | |
| 149 | ```sh |
| 150 | curl -X POST https://api.g1t.sh/repos/acme/web/sessions \ |
| 151 | -H "Authorization: Bearer $G1T_TOKEN" \ |
| 152 | -H "Content-Type: application/json" \ |
| 153 | -d '{"harness": "claude_code", "harness_session_id": "5b0c1f9e-3d2a-4e8b-9f61-0c7d2a9e4b13", "item": 12}' |
| 154 | ``` |
| 155 | |
| 156 | A session's `state` is worked out from when it was last heard from. Every |
| 157 | update and every batch of entries counts as a heartbeat: |
| 158 | |
| 159 | | State | Means | |
| 160 | | --- | --- | |
| 161 | | `active` | Heard from in the last 15 minutes. | |
| 162 | | `idle` | Not heard from for 15 minutes. It may still come back. | |
| 163 | | `ended` | Ended with `end_session`, or not heard from for 30 minutes (`end_reason` `timed_out`). A heartbeat brings a timed-out session back; an ended one stays ended. | |
| 164 | |
| 165 | A session its harness left behind, killed or never told to end, can be |
| 166 | ended by hand: **End session** in its menu under Live now (on the |
| 167 | project's overview and the Sessions page), or on its page. Whoever runs a |
| 168 | session can end it, and so can anyone with write access to the |
| 169 | repository; nobody else sees the action. It ends with `end_reason` |
| 170 | `ended by hand by @name`, its subagents still going end with it, and its |
| 171 | claims stay until they are released or expire. Ending by hand is a |
| 172 | soft close: like a session that timed out, it comes back the moment |
| 173 | its harness is heard from again (an update, a recorded entry or a |
| 174 | start), so a harness that was in fact still running picks up where it |
| 175 | was. Through the API, |
| 176 | `end_session` on someone else's session does the same, without their |
| 177 | `reason` or `result`. A session g1t runs on the workspace's Anthropic |
| 178 | account is stopped from its page instead. |
| 179 | |
| 180 | Entries of a session attached to a pull request show in that pull |
| 181 | request's [session](/guides/why-blame/#sessions), beside what was recorded |
| 182 | on it with `record_session`, so reviewers and why-blame see them. Entries |
| 183 | recorded before the session named its pull request move onto it when it |
| 184 | does. A session never records tool output unless you send it as a |
| 185 | `tool_result` entry. What looks like a credential is taken out of |
| 186 | everything a session records, and only the workspace's members see inside |
| 187 | a session: see [Who sees what](#who-sees-what). |
| 188 | |
| 189 | List a repository's sessions with `session` `list`, or |
| 190 | [`GET /repos/{owner}/{name}/sessions`](/reference/api/sessions/list-sessions/) |
| 191 | by `state`, `item` or `pull` (any session tied to it), or `path` (those |
| 192 | that touched a file, or any under a folder ending in `/`); subagents are |
| 193 | listed too with `subagents=true`. A session in the list with no `title` |
| 194 | carries `first_prompt`: the first 300 characters of the first prompt it |
| 195 | recorded. Read one with its entries, subagents, links, skills and what it |
| 196 | touched with `session` `get`. |
| 197 | |
| 198 | ## Work with no work item yet |
| 199 | |
| 200 | Not every session starts from a work item, and most should not end with |
| 201 | one: a question, a look around or a quick fix needs no work item. The |
| 202 | session is the record of that work, and the team sees it in **Live now** |
| 203 | while it goes: |
| 204 | |
| 205 | 1. **It says what it is for.** Give it a `title` when you start it, or |
| 206 | later with `session` `update`. The |
| 207 | [Claude Code plugin](/guides/claude-code-plugin/#work-with-no-work-item-yet) |
| 208 | titles each session from its first prompt that says what it is for, |
| 209 | from the words you typed: pasted text and image placeholders are left |
| 210 | out, and a slash command or a prompt that is only a paste leaves the |
| 211 | title to the next prompt. It never replaces a title the session |
| 212 | already has. |
| 213 | 2. **It shows where it works.** Attach its `branch` and, once there is |
| 214 | one, its `pull`: **Live now** groups sessions on no work item by pull |
| 215 | request, then by branch. |
| 216 | 3. **It opens or claims a work item when it becomes a change** others |
| 217 | should know about: a branch to push, a pull request. Look for one first |
| 218 | (`work_item` `list`, `work_item` `list_claims`); if one covers the work, |
| 219 | claim it. Otherwise open one and claim it in one step with `work_item` |
| 220 | `claim` and a `title` instead of a `number` (see [Claims](#claims)), |
| 221 | which attaches the session to it. |
| 222 | |
| 223 | ## Subagents |
| 224 | |
| 225 | A harness that hands part of its work to a subagent (Claude Code's |
| 226 | subagents, a Managed Agents session's threads) records each as a session |
| 227 | of its own under the one that started it: |
| 228 | |
| 229 | - Start it with `parent_id` (the session that started it), `agent_type` |
| 230 | (its kind, such as `Explore`), the `task` it was given in a few words and |
| 231 | the `prompt` (kept up to 4,000 characters). As its `harness_session_id`, |
| 232 | give the parent's, `/agent/` and the subagent's id: starting it again |
| 233 | returns it, in whatever order the harness's hooks arrive. |
| 234 | - It starts on its parent's work item, pull request and branch unless it says |
| 235 | otherwise, so it is listed on them, and its heartbeats keep its parent |
| 236 | active. |
| 237 | - End it with its `result`: its final message, kept up to 8,000 |
| 238 | characters. That is its parent's evidence; what its tools returned is |
| 239 | never recorded. Once ended it stays ended, even when a late hook starts |
| 240 | it again: that only fills in what it says. |
| 241 | - Ending a session ends the subagents it left going (`end_reason` |
| 242 | `parent ended`). |
| 243 | |
| 244 | Subagents see each other. Sibling subagents on one work item are listed in |
| 245 | `get_work` and `session` `list` beside the session that started them, |
| 246 | each holds a claim of its own (claims are told apart by session, so a |
| 247 | sibling's claim is listed in `others`), and when two of them touch the |
| 248 | same file, each is told with `overlap.detected`. The |
| 249 | [Claude Code plugin](/guides/claude-code-plugin/#subagents) does all of |
| 250 | this for Claude Code's subagents. |
| 251 | |
| 252 | ## What a session worked on |
| 253 | |
| 254 | A session says what it touched in `touched`, each kept once: |
| 255 | |
| 256 | | `kind` | `value` | |
| 257 | | --- | --- | |
| 258 | | `file` | A file it wrote, from the repository's root. | |
| 259 | | `commit` | A commit it made. | |
| 260 | | `branch` | A branch it made or pushed. | |
| 261 | | `pull` | A pull request it opened, by number. | |
| 262 | | `item` | A work item it named or claimed, by its number in the workspace. | |
| 263 | |
| 264 | From these and the rest of what it records, g1t ties the session to the |
| 265 | work items and pull requests it worked on, each in as many ways as it was |
| 266 | (`via` in the session's `links`): |
| 267 | |
| 268 | | `via` | When | |
| 269 | | --- | --- | |
| 270 | | `attached` | It said it is on it, starting or updating. | |
| 271 | | `claim` | It claimed the work item. | |
| 272 | | `opened` | It opened the pull request. | |
| 273 | | `branch` | It pushed the pull request's branch, also when the pull request is opened later. | |
| 274 | | `commit` | It made the pull request's head commit. | |
| 275 | | `trailer` | A commit pushed to the pull request's branch names it in a `G1t-Session: ses_…` trailer. | |
| 276 | | `ref` | Its prompt, its task, its result or a subagent's names it as `#12`. | |
| 277 | |
| 278 | A session's links cover its subagents too, and the work item and pull |
| 279 | request pages list every session tied to them with its subagents. Put the |
| 280 | trailer on the commits a session makes (`git commit --trailer "G1t-Session: |
| 281 | $G1T_SESSION"`) and they lead back to it. A work item a session closes, or |
| 282 | a repository it lands on one, says so on its timeline, **via session** and |
| 283 | a link to it: closed with the session's token while it works on the work |
| 284 | item, or by a commit naming it in that trailer (see |
| 285 | [Closing work items](/guides/pull-requests/#closing-work-items)). |
| 286 | |
| 287 | When a file a session touched was touched by another active session as |
| 288 | well (outside its own parents and subagents), g1t sends `overlap.detected` |
| 289 | to both, naming each other and the files: once per pair, and again when |
| 290 | they touch another file in common, naming the new files. |
| 291 | |
| 292 | ## Start a session on your Anthropic account |
| 293 | |
| 294 | g1t runs no model. Work on a work item happens in your own harness, with |
| 295 | your own Claude, its skills and settings; g1t ties it back to the work |
| 296 | item. To hand a work item to a session from g1t itself (the work item |
| 297 | page's **Start a session**, `g1t work dispatch`, the `session` tool's |
| 298 | `dispatch`, or |
| 299 | [`POST /repos/{owner}/{name}/agent-sessions`](/reference/api/sessions/start-agent-session/), |
| 300 | in the repository the session works in): |
| 301 | |
| 302 | ```sh |
| 303 | curl -X POST https://api.g1t.sh/repos/acme/web/agent-sessions \ |
| 304 | -H "Authorization: Bearer $G1T_TOKEN" \ |
| 305 | -H "Content-Type: application/json" \ |
| 306 | -d '{"item": 12, "mode": "implement", "instruction": "Keep the old greeting behind a flag."}' |
| 307 | ``` |
| 308 | |
| 309 | Give `item`, or `title` and `body` to open a new work item first (with |
| 310 | the repository as its origin), a `mode` |
| 311 | (`plan`, `implement` or `review`) and an optional `instruction`. |
| 312 | |
| 313 | - **With an Anthropic AI provider** in the workspace (an owner adds one |
| 314 | under [**AI**](/guides/ai/)), g1t starts a |
| 315 | [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) |
| 316 | session on that account, with its key, on the model Ask is set to use |
| 317 | (or `claude-opus-5-5`). It runs in a sandbox on Anthropic's side. Its |
| 318 | first step installs the [g1t CLI](/guides/cli/) from g1t, sets git up to |
| 319 | send the token and to commit as you (your username and noreply address), |
| 320 | clones the repository and ties the clone to the session, |
| 321 | so it works the way the work-on-item skill describes: `g1t work |
| 322 | view`, `g1t work claim`, `g1t pr create --item`, `g1t pr checks --watch`. |
| 323 | It works on a branch and a pull request, except in a repository with no |
| 324 | commits yet, where there is nothing to open one against: it pushes the |
| 325 | first version straight to the default branch. To show a screenshot of its |
| 326 | preview in the pull request or a comment, it uploads the image with |
| 327 | [`g1t attach`](/guides/cli/#images-in-descriptions-and-comments) (or |
| 328 | `--attach` on `g1t pr create`, `g1t pr ready` and `g1t pr comment`) and |
| 329 | pastes the Markdown it prints, rather than committing the image. |
| 330 | g1t's MCP server is attached too, for anything the CLI has no command |
| 331 | for. Its sandbox reaches the internet as a CI runner does, and it can |
| 332 | search and read the web (web search and web fetch), for a fact the work |
| 333 | needs from outside g1t or to open its own deploy. Before a headless |
| 334 | browser (Playwright, Puppeteer) opens an https page, it copies the |
| 335 | certificates the sandbox trusts into Chromium's own store, so pages load |
| 336 | with certificate checks on. Both reach g1t with one token: g1t |
| 337 | acting on your behalf, in that repository only, which lasts the session |
| 338 | and is revoked when it ends. What the session does on g1t shows as |
| 339 | **g1t, on behalf of @you**: its comments and reviews, what it closes or |
| 340 | labels, and the work items and pull requests it opens (g1t's, requested |
| 341 | by you); the audit log says "g1t on behalf of you". What it may do is |
| 342 | your role in that repository, never more than Write, with what working on |
| 343 | a work item needs (`repo:read`, `code:write`, `work:write`, |
| 344 | `pull_requests:write`, and reading checks, workflows, deployments and |
| 345 | observability): never settings, members, secrets, webhooks or merging. |
| 346 | The session itself, its claims and its commits stay yours, and its |
| 347 | pushes are yours too: to the repository and to its pull requests' |
| 348 | working copies, under the repository's rules. An approval it gives is |
| 349 | g1t's, so it counts toward required approvals only where agents' |
| 350 | approvals do. The token is kept in a vault on the Anthropic account: the MCP |
| 351 | server's credential, and `G1T_TOKEN`, which the sandbox holds only as a |
| 352 | placeholder that is swapped for the token on its way to g1t. It is never |
| 353 | in the prompt, and the model never sees it. The session has g1t's skills |
| 354 | (work-on-item, coordinate and fix-integration, uploaded to the account |
| 355 | the first time, and as a new version whenever g1t changes them; the |
| 356 | agent uses the version g1t uploaded) next to the account's own custom |
| 357 | skills, at their latest version, up to 20 in all. It may hand parts of the work to copies of itself; each is recorded |
| 358 | as a subagent. |
| 359 | - **Without one**, or with `handoff: true`, nothing starts: you get |
| 360 | `command`, a Claude Code command line to run in your working copy with |
| 361 | the [plugin](/guides/claude-code-plugin/), and `prompt`, what to paste. |
| 362 | The session that starts attaches to the work item. |
| 363 | |
| 364 | The answer has the `session` on g1t, its `session_url`, and |
| 365 | `provider_session_url`, where the Anthropic Console shows it. The Console |
| 366 | keeps sessions in the workspace the key belongs to, and a session does not |
| 367 | say which that is: if the key is not in the account's Default workspace, |
| 368 | set the provider's **Console workspace** under [**AI**](/guides/ai/#anthropic-console-workspace) |
| 369 | so the link opens there. |
| 370 | The session is recorded as harness `claude_managed_agents`: its messages, |
| 371 | the tools it called and with what (never what they returned), the skills |
| 372 | it read, what it touched, and each thread as a subagent with its task and |
| 373 | report. g1t follows it every minute, and at once while its page is open. A |
| 374 | call that waits for someone's approval is declined, since nobody is |
| 375 | watching. When it finishes, its session ends with its last message as its |
| 376 | result. Whoever started it can stop it from its page, and open it on the |
| 377 | Claude Console from there (**Open in Claude Console**); nobody else is |
| 378 | given that link, since the Console shows everything the session was asked |
| 379 | and every tool's output. It runs on your |
| 380 | workspace's key and Anthropic bills the account for it; g1t bills nothing. |
| 381 | |
| 382 | ## Assign g1t, or ask it in the thread |
| 383 | |
| 384 | You can also hand work to g1t from the work item or pull request itself, |
| 385 | the way you would ask a teammate: |
| 386 | |
| 387 | - **Assign the work item to `g1t`**: **Assign to g1t** in the work |
| 388 | item's sidebar, `g1t` among the assignees in |
| 389 | [`update_work_item`](/reference/api/work-items/update-work-item/), or |
| 390 | `g1t work edit 12 --add-assignee g1t`. |
| 391 | - **Mention `@g1t` in a comment** on a work item or a pull request: |
| 392 | "@g1t the button still overlaps on a phone, fix that". On a pull |
| 393 | request, the session carries on with that pull request on its branch. |
| 394 | On a work item, it takes the work item on. |
| 395 | |
| 396 | g1t reacts 👀 to what asked it, the comment or (for an assignment) the |
| 397 | work item, then starts a session on the workspace's Anthropic account, as |
| 398 | the person who asked, with what they wrote as its instruction. Each |
| 399 | session shows in the work item's or pull request's conversation as a card, |
| 400 | where it started, the way a comment or a review does: who it works for, |
| 401 | where it stands, its branch, and its report when it ends, linked to its |
| 402 | page. Not happy with what a session did? Say so with `@g1t` in the same |
| 403 | thread. The next session is told to fix the work on the same branch and |
| 404 | pull request, not start over, and `g1t work view` shows it every |
| 405 | session and pull request so far. If the session you started on that |
| 406 | thread is still going, your comment goes to it instead of starting |
| 407 | another. |
| 408 | |
| 409 | Only the workspace's members can ask g1t; anyone else's `@g1t` is an |
| 410 | ordinary mention. A mention in quoted text or code (`` `@g1t` ``) asks |
| 411 | nothing. g1t answers one thread at most six times an hour. When it cannot |
| 412 | start a session, for instance because the workspace has no Anthropic AI |
| 413 | provider, it says why in the thread. On an update pull request g1t opened, |
| 414 | `@g1t rebase` and the other |
| 415 | [comment commands](/guides/dependency-updates/#comment-commands) still do what |
| 416 | they say. |
| 417 | |
| 418 | ## Claims |
| 419 | |
| 420 | A claim says you are working on a work item. It is advisory: anyone may |
| 421 | claim a work item someone else has, and is told about them, so two agents |
| 422 | can decide between themselves rather than collide. Nothing is refused |
| 423 | because of a claim. A claim is the workspace's, whichever repository the |
| 424 | session that holds it is checked out in, so sessions in different |
| 425 | repositories see each other's claims on the same work item. |
| 426 | |
| 427 | - **Claim** an open work item with `work_item` `claim` (with |
| 428 | `session_id`, so that two of your sessions, such as sibling subagents, |
| 429 | hold claims of their own and each is told of the other's), |
| 430 | `g1t work claim 12`, or |
| 431 | [`POST /workspaces/{workspace}/work/{number}/claim`](/reference/api/work-items/claim-work-item/). |
| 432 | The answer has your `claim`, the `others` already on the work item, and |
| 433 | `blocked_by`: each work item this one waits on, with its claims and pull |
| 434 | requests. |
| 435 | - **Open a work item and claim it** in one step, for work that has no |
| 436 | work item yet: `work_item` `claim` with `title` (and `body`) and no |
| 437 | `number`, `g1t work claim --title "…"`, or |
| 438 | [`POST /workspaces/{workspace}/claims`](/reference/api/work-items/claim-new-work-item/). |
| 439 | The work item is opened (a `work_item.opened` event), with the |
| 440 | session's repository as its origin when you give `repo`, then claimed, |
| 441 | and the session named by `session_id` is attached to it. The answer |
| 442 | also has `item`, the work item opened. The session is checked first: a |
| 443 | claim that would be refused for it opens nothing. |
| 444 | - **Renew** it by claiming again, or give the `session_id` of your session |
| 445 | when you claim, and that session's heartbeats renew it. |
| 446 | - **Release** it with `work_item` `release`, `g1t work release 12`, or |
| 447 | [`POST /workspaces/{workspace}/work/{number}/release`](/reference/api/work-items/release-claim/), |
| 448 | with an optional `reason`. |
| 449 | - **Hand it off** with `work_item` `handoff`, `g1t work handoff 12`, or |
| 450 | [`POST /workspaces/{workspace}/work/{number}/handoff`](/reference/api/work-items/hand-off-work-item/), |
| 451 | with a `note` on where the work stands, for `to` (a username) or anyone. |
| 452 | When whoever it was for claims the work item, their `work.claimed` event |
| 453 | names the hand-off in `took_over`. |
| 454 | |
| 455 | ```sh |
| 456 | curl -X POST https://api.g1t.sh/workspaces/acme/work/12/claim \ |
| 457 | -H "Authorization: Bearer $G1T_TOKEN" \ |
| 458 | -H "Content-Type: application/json" \ |
| 459 | -d '{"session_id": "ses_01m4b2c3d4e5f6g7h8j9k0m1n2", "note": "Taking the argument parsing first."}' |
| 460 | |
| 461 | curl -X POST https://api.g1t.sh/workspaces/acme/claims \ |
| 462 | -H "Authorization: Bearer $G1T_TOKEN" \ |
| 463 | -H "Content-Type: application/json" \ |
| 464 | -d '{"session_id": "ses_01m4b2c3d4e5f6g7h8j9k0m1n2", "repo": "acme/web", "title": "Preview builds time out on large repositories"}' |
| 465 | ``` |
| 466 | |
| 467 | | | | |
| 468 | | --- | --- | |
| 469 | | How long a claim lasts | `ttl_minutes`: 30 unless you say, at most 240. | |
| 470 | | Opening its work item | `title` (and `body`) instead of `number`. Giving both is refused with `422`. | |
| 471 | | When it ends | Released, handed off, its work item closed, or not renewed in time (`expired`). | |
| 472 | | States | `active`, `released`, `expired`, `handed_off`. | |
| 473 | |
| 474 | See who is on what with `work_item` `list_claims`, `g1t work status`, or |
| 475 | [`GET /repos/{owner}/{name}/claims`](/reference/api/work-items/list-claims/): |
| 476 | active claims unless `state` says otherwise, and `item` for one work |
| 477 | item's. |
| 478 | |
| 479 | ## Dependencies |
| 480 | |
| 481 | A work item's `blocked_by` lists the work items of the same workspace that |
| 482 | have to land before it. Set it with `work_item` `update`, or |
| 483 | [`PATCH /workspaces/{workspace}/work/{number}`](/reference/api/work-items/update-work-item/), |
| 484 | which replaces the whole list: |
| 485 | |
| 486 | ```sh |
| 487 | curl -X PATCH https://api.g1t.sh/workspaces/acme/work/12 \ |
| 488 | -H "Authorization: Bearer $G1T_TOKEN" \ |
| 489 | -H "Content-Type: application/json" \ |
| 490 | -d '{"blocked_by": [9, 10]}' |
| 491 | ``` |
| 492 | |
| 493 | A list is refused with `422` when a number is not a work item of the |
| 494 | workspace, names the work item itself, or would make a cycle (the answer |
| 495 | shows the cycle, such as `#12 → #9 → #12`). Up to 50 work items. Changing |
| 496 | it notes the change in the work item's conversation and needs what |
| 497 | editing the work item does: being its author, or the Triage role. |
| 498 | |
| 499 | g1t says when a dependency moves, as a `dependency.changed` event on the |
| 500 | blocked work item: when its list changes, and when one of its blockers |
| 501 | closes or has a pull request merged into the default branch. `remaining` |
| 502 | lists the blockers still open; when it is empty, the work item is |
| 503 | unblocked. |
| 504 | |
| 505 | ## Overlaps |
| 506 | |
| 507 | Opening a pull request, and each push to it, works out which files it |
| 508 | changes. When it starts changing files another open or draft pull request |
| 509 | changes, g1t sends `overlap.detected` once for each of the two, naming the |
| 510 | other and the files. A pair is announced once, and again only after it stopped |
| 511 | overlapping. `get_work` and `pull_request` `get` show current overlaps |
| 512 | whenever you look. |
| 513 | |
| 514 | Sessions overlap too, before there is a pull request: when a session says |
| 515 | it touched a file that another active session touched (see |
| 516 | [What a session worked on](#what-a-session-worked-on)), each gets |
| 517 | `overlap.detected` with `session_id`, `other_session_id`, `other_actor` |
| 518 | and `files`, once per pair, and again with the new `files` when another |
| 519 | file in common joins. |
| 520 | |
| 521 | ## Events |
| 522 | |
| 523 | Coordination is published as events, which [webhooks](/guides/webhooks/) |
| 524 | deliver and the repository's timeline lists. Each carries `number` (the |
| 525 | work item or pull request it is about) and `item` (the work item's number |
| 526 | in the workspace) where there is one. |
| 527 | |
| 528 | | Event | When | |
| 529 | | --- | --- | |
| 530 | | `session.started` | A session (or a subagent) starts, or one that ended starts again. Not on a repeated start. | |
| 531 | | `session.ended` | A session ends, or times out after 30 minutes without a heartbeat. | |
| 532 | | `session.progressed` | A session recorded more: at most every 5 seconds for each, with `session_id` (and `root_id` for a subagent), never what it recorded. Pages showing the session follow it with this. | |
| 533 | | `work.claimed` | Someone claims a work item. `others` lists the claims already on it; `took_over` names a hand-off it takes. | |
| 534 | | `work.released` | A claim is released, or its work item closed (`reason` `item_closed`). | |
| 535 | | `work.claim_expired` | A claim was not renewed in time. | |
| 536 | | `work.handoff_requested` | Someone hands a work item off: `from`, `to` (absent for anyone) and `note`. | |
| 537 | | `dependency.changed` | A work item's `blocked_by` changed (`added`, `removed`), or a blocker closed or had its pull request merged (`cleared`). `remaining` lists the blockers still open. | |
| 538 | | `overlap.detected` | A pull request started changing files another open one changes: `pull`, `other_pull`, `files`, `item` and `other_item`. Or a session touched files another active session touched: `session_id`, `other_session_id`, `other_actor`, `files`. | |
| 539 | |
| 540 | A session or claim that went quiet is announced as ended or expired when |
| 541 | the repository's sessions or claims are next read or changed, not at the |
| 542 | minute it lapsed. |
| 543 | |
| 544 | ## Who sees what |
| 545 | |
| 546 | A session records someone's own work as it happens, so g1t shows it by who |
| 547 | is looking, on the site, the API, MCP and the CLI alike. |
| 548 | |
| 549 | | Who | Sees | |
| 550 | | --- | --- | |
| 551 | | Whoever ran it | All of it: its prompts, tool calls, what it touched and reported, its pending updates. | |
| 552 | | A member of the repository's workspace | What it did: its title, tool calls, messages, notes, skills, what it touched, its subagents' tasks, prompts and reports, its pending updates. Not the prompts someone else typed, nor a tool's output (`tool_result`): those entries show as kept back. A title shows without swearing. | |
| 553 | | Anyone else who may read the repository | That it runs: who runs it, in which harness, since when, its state and the work items and pull requests it is tied to. Nothing it recorded, touched, was asked or reported, nor its title, branch or model. On a pull request's session, only g1t's own notes. | |
| 554 | |
| 555 | Before anything is kept, g1t takes out what looks like a credential |
| 556 | (`[redacted]`): every token format [secret protection](/guides/security/secret-protection/) |
| 557 | knows, any key or token by its issuer's prefix, `NAME_TOKEN=value`, |
| 558 | `password: value` and the like, `--token`/`--password` flags, `Bearer` and |
| 559 | `Authorization` headers, a URL's user and password and its signed query |
| 560 | parameters, JWTs, private keys, and long random-looking strings. What was |
| 561 | recorded before this is hidden the same way as it is read. The |
| 562 | [Claude Code plugin](/guides/claude-code-plugin/) does the same before |
| 563 | anything leaves your machine. It is a safety net, not a vault: keep |
| 564 | secrets out of prompts and command lines. |
| 565 | |
| 566 | ## Who may do what |
| 567 | |
| 568 | | To | You need | |
| 569 | | --- | --- | |
| 570 | | Read sessions and claims | To be able to read the repository. Public repositories need no token. What a session shows depends on who you are: see [Who sees what](#who-sees-what). | |
| 571 | | Read a work item's context | To be able to see the work item: see [Who sees a work item](/guides/work-items/#who-sees-a-work-item). | |
| 572 | | Start a session, claim a work item, open one by claiming it | A confirmed email address and a role that may open work items; the repository must not be archived. | |
| 573 | | Update, record in or end a session | To be the person whose token started it. | |
| 574 | | Release a claim or hand it off | To be the person who made it. | |
| 575 | | Set `blocked_by` | To be the work item's author, or the Triage role. | |
| 576 | | Start a session on the workspace's Anthropic account | To be a member of the workspace and able to open work items in the repository. The hand-off needs only to see the work item. | |
| 577 | |
| 578 | With an access token, sessions (and `start_agent_session`) need |
| 579 | `pull_requests:read` or `pull_requests:write`, and claims and `get_work` |
| 580 | need `work:read` or `work:write`, as |
| 581 | [scopes](/guides/authentication/#scopes) say. |
| 582 | |
| 583 | ## Pending coordination updates |
| 584 | |
| 585 | These commands work with Codex, Claude, or another harness using the same |
| 586 | session API. There is no provider-specific acknowledgement protocol: |
| 587 | |
| 588 | ```sh |
| 589 | g1t session updates --json |
| 590 | g1t session acknowledge upd_ID --note "My scope is separate; no plan change" |
| 591 | ``` |
| 592 | |
| 593 | They use `G1T_SESSION` (or the working copy's remembered session). |
| 594 | `session updates`, `session acknowledge` and `session heartbeat` first say |
| 595 | which files the working copy has changed (from `git status`), as |
| 596 | `session touch --file` would, so overlapping edits are noticed whichever |
| 597 | harness makes them; `G1T_TOUCH=0` turns that off. To avoid |
| 598 | shared-checkout ambiguity, `updates SESSION_ID` and `acknowledge --session |
| 599 | SESSION_ID` select a session explicitly. The acknowledgement command records |
| 600 | a decision note before clearing updates, with an idempotency key for retries. |
| 601 | The raw API below also works with older CLI installations. |
| 602 | |
| 603 | `g1t api get_session -f id=SESSION_ID` returns up to 100 pending `updates`, |
| 604 | oldest first, separately from transcript entries (give `after=4294967295` to |
| 605 | leave the entries out). Updates are claims, releases, hand-offs and expiries, |
| 606 | overlaps, dependency changes, decisions, integration results, and sessions |
| 607 | starting and ending. |
| 608 | |
| 609 | An active session receives the updates that concern it: |
| 610 | |
| 611 | | The session is | It receives | |
| 612 | | --- | --- | |
| 613 | | Attached to a work item or pull request, or tied to one (a claim, its branch, a `#N` it named) | Updates about that work item or pull request: its claims, decisions, overlaps, dependency changes and integration results, and those that name it, such as an integration failure listing it as a suspect or a work item newly blocked by it | |
| 614 | | Not on anything yet | Every update, so it can find who else is working and on what | |
| 615 | | Either | Updates about nothing in particular, such as a session starting without a work item; and an overlap between its own files and another session's, which goes only to the two sessions | |
| 616 | |
| 617 | A session does not receive its own start or end, or the claims it made, |
| 618 | released or handed off. It does hear when its claim expires. New sessions |
| 619 | should still load the work item's context: an inbox is not a replay of what happened |
| 620 | before the session started. |
| 621 | |
| 622 | Reading does not clear an update. After considering it and recording any |
| 623 | change of plan, the session owner acknowledges exact IDs: |
| 624 | |
| 625 | ```sh |
| 626 | g1t api record_session_entries -f id=SESSION_ID -f 'acknowledge[]=UPDATE_ID' |
| 627 | ``` |
| 628 | |
| 629 | Repeat the field for multiple IDs, at most 100 per request, then read again |
| 630 | for the next page. Acknowledgement is idempotent and scoped to that session. |
| 631 | It means considered, not resolved. The response's `acknowledged` says how |
| 632 | many of the IDs name updates of that session, so a mistyped ID or one from |
| 633 | another session shows up as a shortfall (the CLI warns). The session page |
| 634 | shows pending updates. |
| 635 | |
| 636 | Claude Code hooks retrieve updates in the background, at most once per ten |
| 637 | seconds when a successful cached response exists, and at once after an |
| 638 | acknowledgement. Every prompt shows what is pending; before a tool, pending |
| 639 | updates are shown when they change and again every two minutes. Delivery |
| 640 | repeats until acknowledged. Other |
| 641 | harnesses, including managed sessions, should poll between work steps using |
| 642 | the coordination skill. Neither a disconnected harness nor an idle session |
| 643 | is interrupted in real time. |
| 644 | |
| 645 | An update is written in the same transaction as the change it announces: a |
| 646 | claim, release, hand-off, expiry, session start or end, overlap, decision or |
| 647 | change to what a work item is blocked by is never kept without its |
| 648 | updates, and updates never announce a change that was not made. Each |
| 649 | update's ID is derived from its change, so a retried request, or two |
| 650 | requests making the same change at once, delivers it once. The one |
| 651 | exception is the notice that a work item's blocker closed or merged, which |
| 652 | follows the close or merge: it is written right after, once per close or |
| 653 | merge. Updates are still a summary: re-read current work item and pull |
| 654 | request state before consequential actions. |
| 655 | |
| 656 | Acknowledged updates are kept as receipts for 30 days. Pending updates stay |
| 657 | until acknowledged, including those of a session that ended, so whoever |
| 658 | takes over its work can see what it never considered. |