Skip to content
Sign up

flagon-io/g1t

public
00

Where people and agents ship software together. The open-source git platform for the whole job: issues, agents, checks and deploys to the edge.

gitagentscloudflarerustforgemcp

Commit

Merge branch 'worktree-agent-ae2e89030ac3bac85' into round2

G1T-Session:
ses_01m560bz6eeqc8v1hrrha03pap
syntaqxcommitted Parents05f0b0526a7342Browse files
111 files+2432−163347 files not counted0/111 viewed
+0−0

Binary or large file; its contents are not shown.

+107−62
33 import { defineConfig } from 'astro/config';
44
55 import { generateApiReference } from './scripts/api-reference.mjs';
6+import { movedParts, pages } from './scripts/moved.mjs';
67
78 // A page per REST operation, written from the OpenAPI document.
89 const apiGroups = generateApiReference();
910
11+// Pages that moved, so links already shared still arrive. A key with a
12+// #heading is a part of a page that moved on its own (scripts/moved.mjs).
13+const moved = {
14+ '/guides/inbox/': '/guides/notifications/',
15+ '/guides/mirroring/': '/guides/github/',
16+ '/guides/today/': '/guides/home/',
17+ // g1t no longer runs agents of its own: coding agents connect to it.
18+ '/guides/g1t-agents/': '/guides/bring-your-own-agent/',
19+ '/guides/working-with-g1t/': '/guides/bring-your-own-agent/',
20+ '/guides/agents/': '/guides/bring-your-own-agent/',
21+ '/guides/agent-abilities/': '/guides/bring-your-own-agent/',
22+ '/guides/agent-access/': '/guides/bring-your-own-agent/',
23+ '/guides/agent-memory/': '/guides/bring-your-own-agent/',
24+ '/guides/agent-routines/': '/guides/bring-your-own-agent/',
25+ '/guides/agent-sessions/': '/guides/why-blame/',
26+ '/guides/agent-skills/': '/guides/bring-your-own-agent/',
27+ '/guides/agent-budgets/': '/guides/usage-and-billing/',
28+ '/guides/agents-and-memory/': '/guides/bring-your-own-agent/',
29+ '/guides/talking-to-agents/': '/guides/bring-your-own-agent/',
30+ '/guides/chat-app/': '/guides/chat/',
31+ '/guides/customize/': '/guides/bring-your-own-agent/',
32+ '/guides/marketplace/': '/guides/bring-your-own-agent/',
33+ '/guides/models/': '/guides/ai/',
34+ '/guides/ai-gateway/': '/guides/ai/',
35+ '/guides/context-hub/': '/guides/bring-your-own-agent/',
36+ // Project and workspace memory is gone: harnesses keep their own.
37+ '/guides/memory/': '/guides/bring-your-own-agent/',
38+ '/guides/spend/': '/guides/usage-and-billing/',
39+ '/guides/outcomes/': '/work/milestones/',
40+ // Issues became workspace work items: their operations moved with them.
41+ '/reference/api/issues/list-issues/': '/reference/api/work-items/list-work-items/',
42+ '/reference/api/issues/create-issue/': '/reference/api/work-items/open-work-item/',
43+ '/reference/api/issues/get-issue/': '/reference/api/work-items/get-work-item/',
44+ '/reference/api/issues/update-issue/': '/reference/api/work-items/update-work-item/',
45+ '/reference/api/issues/close-issue/': '/reference/api/work-items/close-work-item/',
46+ '/reference/api/issues/reopen-issue/': '/reference/api/work-items/reopen-work-item/',
47+ '/reference/api/integrations/import-issue/': '/reference/api/work-items/import-work-items/',
48+ '/reference/api/issues/list-issue-labels/': '/reference/api/work-items/list-work-item-labels/',
49+ '/reference/api/issues/add-issue-labels/': '/reference/api/work-items/add-work-item-labels/',
50+ '/reference/api/issues/set-issue-labels/': '/reference/api/work-items/set-work-item-labels/',
51+ '/reference/api/issues/remove-issue-labels/': '/reference/api/work-items/remove-work-item-labels/',
52+ '/reference/api/issues/remove-issue-label/': '/reference/api/work-items/remove-work-item-label/',
53+ '/reference/api/issues/add-comment/': '/reference/api/work-items/add-work-item-comment/',
54+ '/reference/api/issues/edit-comment/': '/reference/api/work-items/edit-work-item-comment/',
55+ '/reference/api/issues/delete-comment/': '/reference/api/work-items/delete-work-item-comment/',
56+ '/reference/api/issues/react/': '/reference/api/work-items/react-to-work-item/',
57+ '/reference/api/issues/upload-attachment/': '/reference/api/work-items/upload-attachment/',
58+ '/reference/api/decisions-and-why/list-issue-decisions/': '/reference/api/work-items/list-work-item-decisions/',
59+ '/reference/api/claims-and-work/get-work/': '/reference/api/work-items/get-work/',
60+ '/reference/api/claims-and-work/claim-issue/': '/reference/api/work-items/claim-work-item/',
61+ '/reference/api/claims-and-work/claim-new-issue/': '/reference/api/work-items/claim-new-work-item/',
62+ '/reference/api/claims-and-work/list-claims/': '/reference/api/work-items/list-claims/',
63+ '/reference/api/claims-and-work/release-claim/': '/reference/api/work-items/release-claim/',
64+ '/reference/api/claims-and-work/hand-off-issue/': '/reference/api/work-items/hand-off-work-item/',
65+ '/reference/api/notifications/get-issue-subscription/': '/reference/api/notifications/get-work-item-subscription/',
66+ '/reference/api/notifications/set-issue-subscription/': '/reference/api/notifications/set-work-item-subscription/',
67+ '/reference/api/notifications/delete-issue-subscription/': '/reference/api/notifications/delete-work-item-subscription/',
68+ // Work has a section of its own, as it has in the app.
69+ '/guides/work-items/': '/work/work-items/',
70+ '/guides/work-items/#open-a-work-item': '/work/work-items/#file-a-work-item',
71+ '/guides/work-items/#the-work-list': '/work/#the-work-list',
72+ '/guides/work-items/#the-board': '/work/board/',
73+ '/guides/work-items/#closing-a-work-item': '/work/closing/',
74+ '/guides/work-items/#labels-and-milestones': '/work/labels/',
75+ '/guides/work-items/#work-on-one': '/work/agents/',
76+ '/guides/work-items/#the-cli': '/work/agents/#the-cli',
77+ '/guides/work-items/#mcp-and-the-api': '/work/agents/#mcp-and-the-api',
78+ '/guides/labels/': '/work/labels/',
79+ '/guides/milestones/': '/work/milestones/',
80+ '/about/issues-became-work-items/': '/work/from-issues/',
81+ // Sessions' pages, titles and claims moved to Work; recording a
82+ // session from a harness stayed.
83+ '/guides/sessions/#sessions': '/guides/sessions/#record-a-session',
84+ '/guides/sessions/#the-sessions-page': '/work/sessions/',
85+ '/guides/sessions/#on-the-site': '/work/sessions/#sessions-elsewhere-on-the-site',
86+ '/guides/sessions/#session-titles': '/work/session-titles/',
87+ '/guides/sessions/#picking-up-a-work-item': '/work/agents/#pick-up-a-work-item',
88+ '/guides/sessions/#what-a-session-worked-on': '/work/sessions/#what-a-session-records',
89+ '/guides/sessions/#claims': '/work/claims-and-dependencies/#claims',
90+ '/guides/sessions/#dependencies': '/work/claims-and-dependencies/#dependencies',
91+ '/guides/sessions/#overlaps': '/work/claims-and-dependencies/#overlaps',
92+ '/guides/sessions/#events': '/work/claims-and-dependencies/#events',
93+ '/guides/sessions/#who-sees-what': '/work/sessions/#who-sees-what',
94+ '/guides/sessions/#who-may-do-what': '/work/claims-and-dependencies/#who-may-do-what',
95+ '/guides/sessions/#pending-coordination-updates': '/work/claims-and-dependencies/#coordination-updates',
96+};
97+
1098 export default defineConfig({
1199 site: 'https://docs.g1t.sh',
12− // Pages that moved, so links already shared still arrive.
13− redirects: {
14− '/guides/inbox/': '/guides/notifications/',
15− '/guides/mirroring/': '/guides/github/',
16− '/guides/today/': '/guides/home/',
17− // g1t no longer runs agents of its own: coding agents connect to it.
18− '/guides/g1t-agents/': '/guides/bring-your-own-agent/',
19− '/guides/working-with-g1t/': '/guides/bring-your-own-agent/',
20− '/guides/agents/': '/guides/bring-your-own-agent/',
21− '/guides/agent-abilities/': '/guides/bring-your-own-agent/',
22− '/guides/agent-access/': '/guides/bring-your-own-agent/',
23− '/guides/agent-memory/': '/guides/bring-your-own-agent/',
24− '/guides/agent-routines/': '/guides/bring-your-own-agent/',
25− '/guides/agent-sessions/': '/guides/why-blame/',
26− '/guides/agent-skills/': '/guides/bring-your-own-agent/',
27− '/guides/agent-budgets/': '/guides/usage-and-billing/',
28− '/guides/agents-and-memory/': '/guides/bring-your-own-agent/',
29− '/guides/talking-to-agents/': '/guides/bring-your-own-agent/',
30− '/guides/chat-app/': '/guides/chat/',
31− '/guides/customize/': '/guides/bring-your-own-agent/',
32− '/guides/marketplace/': '/guides/bring-your-own-agent/',
33− '/guides/models/': '/guides/ai/',
34− '/guides/ai-gateway/': '/guides/ai/',
35− '/guides/context-hub/': '/guides/bring-your-own-agent/',
36− // Project and workspace memory is gone: harnesses keep their own.
37− '/guides/memory/': '/guides/bring-your-own-agent/',
38− '/guides/spend/': '/guides/usage-and-billing/',
39− '/guides/outcomes/': '/guides/milestones/',
40− // Issues became workspace work items: their operations moved with them.
41− '/reference/api/issues/list-issues/': '/reference/api/work-items/list-work-items/',
42− '/reference/api/issues/create-issue/': '/reference/api/work-items/open-work-item/',
43− '/reference/api/issues/get-issue/': '/reference/api/work-items/get-work-item/',
44− '/reference/api/issues/update-issue/': '/reference/api/work-items/update-work-item/',
45− '/reference/api/issues/close-issue/': '/reference/api/work-items/close-work-item/',
46− '/reference/api/issues/reopen-issue/': '/reference/api/work-items/reopen-work-item/',
47− '/reference/api/integrations/import-issue/': '/reference/api/work-items/import-work-items/',
48− '/reference/api/issues/list-issue-labels/': '/reference/api/work-items/list-work-item-labels/',
49− '/reference/api/issues/add-issue-labels/': '/reference/api/work-items/add-work-item-labels/',
50− '/reference/api/issues/set-issue-labels/': '/reference/api/work-items/set-work-item-labels/',
51− '/reference/api/issues/remove-issue-labels/': '/reference/api/work-items/remove-work-item-labels/',
52− '/reference/api/issues/remove-issue-label/': '/reference/api/work-items/remove-work-item-label/',
53− '/reference/api/issues/add-comment/': '/reference/api/work-items/add-work-item-comment/',
54− '/reference/api/issues/edit-comment/': '/reference/api/work-items/edit-work-item-comment/',
55− '/reference/api/issues/delete-comment/': '/reference/api/work-items/delete-work-item-comment/',
56− '/reference/api/issues/react/': '/reference/api/work-items/react-to-work-item/',
57− '/reference/api/issues/upload-attachment/': '/reference/api/work-items/upload-attachment/',
58− '/reference/api/decisions-and-why/list-issue-decisions/': '/reference/api/work-items/list-work-item-decisions/',
59− '/reference/api/claims-and-work/get-work/': '/reference/api/work-items/get-work/',
60− '/reference/api/claims-and-work/claim-issue/': '/reference/api/work-items/claim-work-item/',
61− '/reference/api/claims-and-work/claim-new-issue/': '/reference/api/work-items/claim-new-work-item/',
62− '/reference/api/claims-and-work/list-claims/': '/reference/api/work-items/list-claims/',
63− '/reference/api/claims-and-work/release-claim/': '/reference/api/work-items/release-claim/',
64− '/reference/api/claims-and-work/hand-off-issue/': '/reference/api/work-items/hand-off-work-item/',
65− '/reference/api/notifications/get-issue-subscription/': '/reference/api/notifications/get-work-item-subscription/',
66− '/reference/api/notifications/set-issue-subscription/': '/reference/api/notifications/set-work-item-subscription/',
67− '/reference/api/notifications/delete-issue-subscription/': '/reference/api/notifications/delete-work-item-subscription/',
68− },
100+ redirects: pages(moved),
69101 integrations: [
102+ movedParts(moved),
70103 starlight({
71104 title: 'g1t docs',
72105 description: 'Guides and reference for g1t, the code platform for your team and its coding agents.',
132165 { label: 'How g1t works', slug: 'concepts/overview' },
133166 { label: 'The g1t CLI', slug: 'guides/cli' },
134167 { label: 'Home', slug: 'guides/home' },
135− { label: 'Work items', slug: 'guides/work-items' },
136168 { label: 'Ask g1t', slug: 'guides/ask' },
137169 { label: 'AI providers', slug: 'guides/ai' },
138170 { label: 'Notifications', slug: 'guides/notifications' },
143175 ],
144176 },
145177 {
178+ label: 'Work',
179+ items: [
180+ { label: 'Work', slug: 'work' },
181+ { label: 'Work items', slug: 'work/work-items' },
182+ { label: 'The Board', slug: 'work/board' },
183+ { label: 'Closing work items', slug: 'work/closing' },
184+ { label: 'Labels', slug: 'work/labels' },
185+ { label: 'Milestones', slug: 'work/milestones' },
186+ { label: 'Sessions', slug: 'work/sessions' },
187+ { label: 'Session titles', slug: 'work/session-titles' },
188+ { label: 'Claims and dependencies', slug: 'work/claims-and-dependencies' },
189+ { label: 'Working with agents', slug: 'work/agents' },
190+ { label: 'Issues became work items', slug: 'work/from-issues' },
191+ ],
192+ },
193+ {
146194 label: 'Chat',
147195 items: [
148196 { label: 'Chat', slug: 'guides/chat' },
187235 { label: 'Connect a coding agent', slug: 'guides/bring-your-own-agent' },
188236 { label: 'Build and ship an app with an agent', slug: 'guides/build-and-ship' },
189237 { label: 'Claude Code plugin', slug: 'guides/claude-code-plugin' },
190− { label: 'Sessions, claims and dependencies', slug: 'guides/sessions' },
238+ { label: 'Recording sessions', slug: 'guides/sessions' },
191239 { label: 'Sessions and why-blame', slug: 'guides/why-blame' },
192240 ],
193241 },
207255 { label: 'Pull requests and checks', slug: 'guides/pull-requests' },
208256 { label: 'Checks', slug: 'guides/checks' },
209257 { label: 'Pull requests into other branches', slug: 'guides/base-branches' },
210− { label: 'Labels', slug: 'guides/labels' },
211− { label: 'Milestones', slug: 'guides/milestones' },
212258 { label: 'The merge queue', slug: 'guides/merge-queue' },
213259 { label: 'Rules', slug: 'guides/rules' },
214260 { label: 'CODEOWNERS', slug: 'guides/codeowners' },
277323 label: 'About',
278324 items: [
279325 { label: "What g1t can't do yet", slug: 'about/limitations' },
280− { label: 'Issues became work items', slug: 'about/issues-became-work-items' },
281326 { label: 'An open letter to Cloudflare', slug: 'about/open-letter-to-cloudflare' },
282327 ],
283328 },
+54−0
1+// @ts-check
2+/**
3+ * Pages that moved, and parts of pages that moved on their own.
4+ *
5+ * astro.config.mjs lists them as `'/old/': '/new/'`, and a part of a page
6+ * as `'/old/#heading': '/new/#heading'`. Astro's redirects take the pages.
7+ * A redirect never sees a link's #fragment, so the parts are this
8+ * integration's: once the site is built, it puts a short script at the top
9+ * of each old address's page (the redirect, or the page itself when it is
10+ * still there) that sends a link to a moved part on to where it went. On a
11+ * redirect, a link to any other part keeps its #fragment, since the parts
12+ * of a moved page keep their names.
13+ */
14+import { readFile, writeFile } from 'node:fs/promises';
15+// readFile throws for an old address with no page, so a moved part never
16+// names a page the build does not make.
17+import { fileURLToPath } from 'node:url';
18+
19+/** @param {Record<string, string>} moved */
20+export function pages(moved) {
21+ return Object.fromEntries(Object.entries(moved).filter(([from]) => !from.includes('#')));
22+}
23+
24+/** @param {Record<string, string>} moved @returns {import('astro').AstroIntegration} */
25+export function movedParts(moved) {
26+ return {
27+ name: 'g1t-moved-parts',
28+ hooks: {
29+ 'astro:build:done': async ({ dir, logger }) => {
30+ /** @type {Map<string, Record<string, string>>} */
31+ const parts = new Map();
32+ for (const [from, to] of Object.entries(moved)) {
33+ const [page, part] = from.split('#');
34+ if (!part) continue;
35+ parts.set(page, { ...parts.get(page), [part]: to });
36+ }
37+ for (const [page, map] of parts) {
38+ const file = fileURLToPath(new URL(`.${page}index.html`, dir));
39+ const html = await readFile(file, 'utf8');
40+ const whole = moved[page] ?? '';
41+ const script =
42+ `<script>(function(){var p=${JSON.stringify(map)},w=${JSON.stringify(whole)},h=location.hash,` +
43+ `t=p[decodeURIComponent(h.slice(1))]||(w&&w+h);if(t)location.replace(t)})()</script>`;
44+ // First in the page, before a redirect's own refresh. Astro's
45+ // redirect pages have no <head> tag, Starlight's pages do.
46+ const at = /<head[^>]*>/i.exec(html) ?? /<!doctype html>/i.exec(html);
47+ const end = at ? at.index + at[0].length : 0;
48+ await writeFile(file, html.slice(0, end) + script + html.slice(end));
49+ }
50+ logger.info(`${parts.size} pages send links to their moved parts on`);
51+ },
52+ },
53+ };
54+}
+0−89
1−---
2−title: Issues became work items
3−description: Issues moved out of repositories into workspace-level work items. What happened to the issues, labels and milestones you had, why old links still work, and what to change in scripts and agents.
4−---
5−
6−Issues used to belong to one repository each. They are now
7−[work items](/guides/work-items/), which belong to the workspace and can
8−link several repositories. **Work**, after **Home** in the left rail,
9−replaces each repository's **Issues** tab.
10−
11−## What happened to your issues
12−
13−Every issue became a work item, with everything it had: its title and
14−description, comments, reactions, labels, assignees, milestone, claims,
15−sessions, pull requests and what it was blocked by.
16−
17−- **It has a new number.** Work items are numbered once for the whole
18− workspace, and each issue was given the next number, oldest first, above
19− every number any of the workspace's repositories had used. So an issue
20− number and a work item number never mean two things.
21−- **Its repository is its origin.** The work item links the repository
22− the issue was in as its `origin`, and keeps the old number there. Its
23− pull requests' repositories are linked as `touched`.
24−- **Pull requests kept their numbers.** New ones take the workspace's next
25− number.
26−- **Who can see it did not change.** Anyone who could read the repository
27− still sees the work item filed there. Members of the workspace now see
28− every work item in it.
29−
30−## Old links still work
31−
32−- `g1t.sh/<owner>/<repo>/issues/12` redirects to the work item that issue
33− became, at `g1t.sh/<owner>/-/work/<number>`. **Issues**, **New issue**,
34− **Labels** and **Milestones** under a repository redirect to **Work**:
35− the repository's issue list to the Work list filtered to it, and its
36− labels and milestones to the workspace's. A milestone's own old address,
37− `…/milestones/3`, lands on the milestones list, since milestones were
38− renumbered.
39−- A person's **Issues** tab is their **Work items** tab, at
40− `g1t.sh/u/<name>/items`.
41−- `#12` and `owner/repo#12` in descriptions, comments and commit messages
42− written before still link to that issue's work item.
43−- `Closes #12` in history still points at the right work item.
44−- A repository has no **Work** or **Sessions** page of its own, and
45− `g1t.sh/<owner>/<repo>/work` and `…/sessions` are not found. Its claims
46− and sessions are on the workspace's
47− [Sessions](/guides/sessions/#the-sessions-page), filtered to it:
48− `g1t.sh/<workspace>/-/sessions?repo=<name>`. A session's page is
49− `g1t.sh/<workspace>/-/sessions/<id>`, and a pull request's recorded
50− session is its **Session** tab, `…/pull/<number>/session`.
51−
52−## Labels and milestones
53−
54−Labels and milestones now belong to the workspace, too.
55−
56−- Labels with the same name in several repositories became one label. The
57− one made first kept its color and description.
58−- Milestones were renumbered in the workspace. Each records the
59− repository it came from, and every work item and pull request in it
60− stayed in it.
61−
62−## What to change
63−
64−Nothing that reads links or references needs to change. What calls g1t by
65−name does:
66−
67−| Was | Now |
68−| --- | --- |
69−| `g1t issue …` | `g1t work …`: `list`, `view`, `new`, `comment`, `edit`, `close`, `reopen` |
70−| `g1t browse --issues` | `g1t browse --work` |
71−| `g1t work context N` | `g1t work view N` |
72−| `g1t work list` (claims and sessions) | `g1t work status` |
73−| `--issue N` on `g1t pr create`, `g1t session …` and `g1t work events` | `--item N` |
74−| The MCP `issue` tool | `work_item`, with `workspace` and `number` |
75−| `pull_request` `create` with `issue` | `pull_request` `create` with `item` |
76−| `/repos/{owner}/{name}/issues…` | `/workspaces/{workspace}/work…` |
77−| Repository labels and milestones routes | `/workspaces/{workspace}/labels` and `/workspaces/{workspace}/milestones` |
78−| `issue.*` events and webhooks | `work_item.*`. Webhooks you had were moved over for you. |
79−| `issue` and `other_issue` in event payloads | `item` and `other_item` |
80−| Workflows `on: issues` and `on: issue_comment`, and `permissions: { issues: … }` | `on: work_item`, `on: work_item_comment` and `permissions: { work: … }`. The old names still read but start and grant nothing, and the workflow's page says so. |
81−| The repository settings `has_issues` and `auto_close_issues` | `has_work_items` and `auto_close_items` |
82−| Search `is:issue` and `type: issues` | `is:item` and `type: items` |
83−| `issues:read`, `issues:write` scopes | `work:read`, `work:write` |
84−| `/g1t:work-on-issue` in Claude Code | `/g1t:work-on-item`, with the plugin 0.3.0 and the CLI 0.4.0 or later |
85−
86−There are no aliases for the old names: a script that calls one gets an
87−error, not a silent change. Numbers in your own data, such as a tracker
88−that stored `owner/repo#12`, still resolve, but a work item's own number
89−is the one to keep from now on.
+2−2
2222 | Access token | `g1t_…`, personal or a workspace's, with scopes | The API, MCP, git, the CLI | `user_for_access_token` |
2323 | OAuth access token | Issued by `POST /oauth/token`, refreshed with `g1r_…` | MCP clients, the phone app, apps you authorise | `user_for_access_token` |
2424 | Job token | `G1T_TOKEN` in a workflow job | Actions, for that job alone | `user_for_access_token` |
25−| Run credential | Made per sandbox run, up to 6 hours, or per [session](/guides/sessions/) g1t starts on Claude Managed Agents, up to 12 | Sandboxes; a session's agent, for the API, MCP, git and the CLI | `user_for_access_token` |
25+| Run credential | Made per sandbox run, up to 6 hours, or per [session](/guides/sessions/#start-a-session-on-your-anthropic-account) g1t starts on Claude Managed Agents, up to 12 | Sandboxes; a session's agent, for the API, MCP, git and the CLI | `user_for_access_token` |
2626 | git password | Your account's password | git, only without two-factor authentication | `user_for_git_credentials` |
2727
2828 The CLI signs in with the device flow of RFC 8628 (`/device/code`, then
6767 | Repository | Read, Triage, Write, Maintain and Admin, given to a person, a team, or everyone in the workspace as its base permission |
6868 | Outside collaborators | A repository role for someone who is not a member |
6969
70−A [work item](/guides/work-items/) belongs to the workspace, so it has no
70+A [work item](/work/work-items/) belongs to the workspace, so it has no
7171 repository role of its own. `item_role` gives the viewer the higher of
7272 their role through workspace membership and their permission on the work
7373 item's origin repository, if it has one. `can_item` and `check_item` judge
+4−4
1515 ## Work items and pull requests
1616
1717 A work item belongs to a workspace, not to a repository
18−([Work items](/guides/work-items/)). `work_items` holds them, numbered per
18+([Work items](/work/work-items/)). `work_items` holds them, numbered per
1919 workspace, with no repository of their own. `work_item_repos` links each
2020 to any number of the workspace's repositories, one row per repository, in
2121 a role:
7676 as `work.migrated`, for the other services to rewrite what they keep. Old
7777 `/<owner>/<repo>/issues/<n>` links and `#N` references resolve through
7878 `legacy_number` ([Issues became work
79−items](/about/issues-became-work-items/)).
79+items](/work/from-issues/)).
8080
8181 ## Coordination
8282
117117 is blocked by and blocks, its decision records, and its latest
118118 coordination events. A session's entries on a pull request are what
119119 **Blame** reads to show the agent's account of a line ([Sessions and
120−why-blame](/guides/why-blame/)). [Sessions, claims and
121−dependencies](/guides/sessions/) has the calls.
120+why-blame](/guides/why-blame/)). [Claims and
121+dependencies](/work/claims-and-dependencies/) has the calls.
122122
123123 ## Checks and statuses
124124
+1−1
3939 your minutes, just because you copied it.
4040 - **Work items** filed in it. A fork usually exists to change code and
4141 propose it back; the conversation stays on the parent's
42− [work items](/guides/work-items/). Turn them on in the
42+ [work items](/work/work-items/). Turn them on in the
4343 fork's settings if it becomes a project of its own.
4444
4545 Deployments stay off until the fork's own project is set up.
+7−7
3636
3737 A work item says what should change. People open them, coding agents open
3838 them, and so can anything with an access token, such as an error tracker
39−reporting a crash. They are under **Work**, after **Home** in the left
40−rail; see [work items](/guides/work-items/).
39+reporting a crash. They are under **Work**, after **Home** and
40+**Explore** in the left rail; see [work items](/work/work-items/).
4141
4242 A work item has:
4343
6060 A workspace starts with a set of labels such as `bug`, `enhancement` and
6161 `question`, shared by all its repositories; anyone with the Triage role
6262 can make more as they label. A work item or pull request carries up to 20.
63−See [labels](/guides/labels/).
63+See [labels](/work/labels/).
6464
6565 ## Pull requests
6666
221221 the `session` tool or `g1t session`. A session is recorded in the repository it
222222 is checked out in, and tied to the work item it claimed and the pull
223223 request it opened. People read it on the pull request's **Session** tab,
224−on the work item, and on the workspace's **Sessions**, in the rail after
225−**Work**, which shows who is working on what right now across its
226−repositories. See
227−[sessions, claims and dependencies](/guides/sessions/).
224+on the work item, and in **Work**'s **Sessions**
225+(`g1t.sh/<workspace>/-/work/sessions`), which shows who is working on
226+what right now across its repositories. See
227+[sessions](/work/sessions/) and [claims and dependencies](/work/claims-and-dependencies/).
228228
229229 Each entry is tied to the commit that was the head when it was recorded,
230230 so **Blame** on any file can show not only the commit that last changed a
+1−1
112112
113113 ### Work items
114114
115−[Work items](/guides/work-items/) belong to the workspace, not to one
115+[Work items](/work/work-items/) belong to the workspace, not to one
116116 repository, and so do its labels and milestones.
117117
118118 - The workspace's members see every work item.
+1−1
2929
3030 | On GitHub | On g1t |
3131 | --- | --- |
32−| `on:` `push` (branches, tags, paths), `pull_request`, `pull_request_target`, `work_item`, `work_item_comment`, `pull_request_review`, `schedule`, `workflow_dispatch`, `workflow_run`, `merge_group`, `create`, `delete`, `repository_dispatch`, `release`, `deployment`, `deployment_status` | The same, from g1t's own pushes, pull requests, [work items](/guides/work-items/) linked to the repository, comments, [releases](#releases), [deployments](#deployments) and [merge queue](/guides/merge-queue/). `work_item` and `work_item_comment` are g1t's own, in place of GitHub's `issues` and `issue_comment`, with `github.event.work_item` in place of `github.event.issue`; `work_item_comment` runs for comments on pull requests too, with `github.event.work_item.pull_request` set. A workflow on `issues` or `issue_comment` still reads, but starts nothing, and its page says to write `work_item` or `work_item_comment`. `create` starts on each new branch or tag, at its commit; `delete` on each branch or tag a push deletes, on the default branch's latest commit, with `github.event.ref` and `github.event.ref_type` naming what went. As on GitHub, neither takes `branches` or `tags` filters: a workflow on them runs for every branch and tag. `repository_dispatch` starts on [a dispatch event](#repository-dispatch). |
32+| `on:` `push` (branches, tags, paths), `pull_request`, `pull_request_target`, `work_item`, `work_item_comment`, `pull_request_review`, `schedule`, `workflow_dispatch`, `workflow_run`, `merge_group`, `create`, `delete`, `repository_dispatch`, `release`, `deployment`, `deployment_status` | The same, from g1t's own pushes, pull requests, [work items](/work/work-items/) linked to the repository, comments, [releases](#releases), [deployments](#deployments) and [merge queue](/guides/merge-queue/). `work_item` and `work_item_comment` are g1t's own, in place of GitHub's `issues` and `issue_comment`, with `github.event.work_item` in place of `github.event.issue`; `work_item_comment` runs for comments on pull requests too, with `github.event.work_item.pull_request` set. A workflow on `issues` or `issue_comment` still reads, but starts nothing, and its page says to write `work_item` or `work_item_comment`. `create` starts on each new branch or tag, at its commit; `delete` on each branch or tag a push deletes, on the default branch's latest commit, with `github.event.ref` and `github.event.ref_type` naming what went. As on GitHub, neither takes `branches` or `tags` filters: a workflow on them runs for every branch and tag. `repository_dispatch` starts on [a dispatch event](#repository-dispatch). |
3333 | `jobs`, `needs`, `if`, `outputs`, `env`, `defaults`, `timeout-minutes`, `continue-on-error` | The same. |
3434 | `timeout-minutes` and `continue-on-error` on a step | The same, for `run:` and `uses:` steps alike. A `uses:` step's action is stopped at its limit, with every process it started; a step inside a composite action stops at its own limit or the `uses:` step's, whichever comes first. A step stopped this way fails, unless `continue-on-error` lets the job go on. |
3535 | `strategy.matrix` with `include` and `exclude`, `fail-fast`, `max-parallel`, a matrix from `fromJSON(needs.…)` | The same. |
+2−2
158158 Nothing starts until you choose on the card:
159159
160160 - **Start session** runs it on your workspace's Anthropic account as a
161− [Claude Managed Agents session](/guides/sessions/), with g1t's tools and
161+ [Claude Managed Agents session](/guides/sessions/#start-a-session-on-your-anthropic-account), with g1t's tools and
162162 skills beside your own. It shows when an owner has connected Anthropic.
163163 - **Copy Claude Code command** copies a `claude` command that runs it on
164164 your computer with the [g1t plugin](/guides/claude-code-plugin/), with
165165 your own skills, settings and subagents.
166166
167167 Either way the session is tied to the work item: it shows on the work
168−item, on the workspace's [Sessions](/guides/sessions/#the-sessions-page)
168+item, on the workspace's [Sessions](/work/sessions/)
169169 and on its own session page, with
170170 its subagents, and Ask can tell you where it stands. If a session already
171171 holds the work item, Ask
+1−1
874874 | `packages:read` | Pull container images and install private [packages](/guides/packages/). Public ones need no scope. |
875875 | `packages:write` | Push container images and publish packages; with the Admin role on a package, change its settings |
876876 | `packages:delete` | Delete and restore packages and their versions |
877−| `work:read` | Read [work items](/guides/work-items/) and their comments, and the workspace's [labels](/guides/labels/) and [milestones](/guides/milestones/) |
877+| `work:read` | Read [work items](/work/work-items/) and their comments, and the workspace's [labels](/work/labels/) and [milestones](/work/milestones/) |
878878 | `work:write` | Open, edit, link, claim, close, comment on and react to work items; manage labels and milestones |
879879 | `pull_requests:read` | Read pull requests, their changes, sessions and merge queues |
880880 | `pull_requests:write` | Open, review, comment on, close and merge pull requests |
+1−1
4444 | Required checks, approvals, being up to date | As the rules covering it ask | As the rules covering it ask; nothing when none cover it |
4545 | [Merge queue](/guides/merge-queue/) | Joins it, when a rule requires it | Never; it merges directly |
4646 | Catching up | Merges the default branch in | Merges its base in |
47−| Its [work item](/guides/work-items/) | Records the repository as landed when it merges, and closes once every target has | Nothing lands; it stays open |
47+| Its [work item](/work/work-items/) | Records the repository as landed when it merges, and closes once every target has | Nothing lands; it stays open |
4848
4949 Merging still needs the Write role. Under **Settings → Rules**, **What holds
5050 for a branch** shows every rule that covers a branch.
+3−3
1616 | Push code | git over HTTPS, signed in with `g1t auth setup-git` or an [access token](/guides/authentication/#access-tokens) |
1717 | Start the agent when something happens | [Webhooks](/guides/webhooks/), or a [workflow](/guides/actions/) on `work_item` or `work_item_comment` |
1818 | Show people how a change was made | The pull request's [session](/guides/why-blame/#sessions) |
19−| See who is working on what, and not collide | [Sessions, claims and dependencies](/guides/sessions/) |
19+| See who is working on what, and not collide | [Claims and dependencies](/work/claims-and-dependencies/) |
2020 | Script anything else | The [REST API](/reference/api/), which has the same operations as the tools |
2121
2222 The agent runs where you run it: on your machine, in your CI, or on a
129129 anyway (`session` with `start`), with a `title` saying what it is for: the
130130 team sees it in **Live now** on the project's overview, under its pull
131131 request or branch, and on the workspace's
132−[Sessions](/guides/sessions/#the-sessions-page). When the work becomes a change others
132+[Sessions](/work/sessions/). When the work becomes a change others
133133 should know about (a branch to push, a pull request), look for its work
134134 item (`work_item` with `list` or `list_claims`) and claim it. If there is
135135 none, `work_item` with `claim`, a `title` and no `number` opens one, with
215215 put secrets in a session: g1t takes out what looks like a credential, and
216216 shows what a session recorded only to the workspace's members (a prompt
217217 only to whoever typed it), but that is a safety net. See
218−[Who sees what](/guides/sessions/#who-sees-what).
218+[Who sees what](/work/sessions/#who-sees-what).
219219
220220 ### Recording sessions automatically
221221
+1−1
121121 into the default branch closes the work item. The trailer ties each commit,
122122 and the pull request it lands in, to the session; the pull request's
123123 **Session** tab shows how it was made. See
124− [Sessions, claims and dependencies](/guides/sessions/).
124+ [Sessions](/work/sessions/).
125125
126126 With no workflows in `.g1t/workflows` there are no checks to wait for.
127127 To have the agent add CI, ask for it; pushing a workflow file needs the
+5−5
9393 titles, and what subagents were asked and reported; g1t does it again as
9494 it records. Your prompts show only to you; the workspace's members see the
9595 rest, and anyone else who can read the repository sees only that the
96−session runs ([Who sees what](/guides/sessions/#who-sees-what)).
96+session runs ([Who sees what](/work/sessions/#who-sees-what)).
9797
9898 | When | The hook runs | What g1t receives |
9999 | --- | --- | --- |
185185 name the whole job: g1t keeps that title, unless the session goes on to
186186 other work items or pull requests, when it is named again as it ends.
187187 Rename a session on its page to pin your own title: g1t and Claude never
188− replace it. See [Session titles](/guides/sessions/#session-titles).
188+ replace it. See [Session titles](/work/session-titles/).
189189 2. **It shows to the team.** The project's overview lists it in **Live
190190 now** under its pull request, else its branch, else under **No branch
191191 yet**, with who it is for, Claude Code, its state, when it was last
192192 heard from and its branch; the workspace's
193− [Sessions](/guides/sessions/#the-sessions-page) lists it with the rest.
193+ [Sessions](/work/sessions/) lists it with the rest.
194194 3. **It gets a work item when it becomes a change** others should know
195195 about: a branch to push, a pull request. Claude is told to look for a
196196 work item first (`g1t work list`) and claim it with `g1t work claim N`,
289289 out of date, and said the same way.
290290
291291 A CLI older than 0.3.3 records sessions but cannot acknowledge
292−[coordination updates](/guides/sessions/#pending-coordination-updates). The hooks then show
292+[coordination updates](/work/claims-and-dependencies/#coordination-updates). The hooks then show
293293 pending updates only when they change, not before every prompt, and ask
294294 Claude to tell you once to update the CLI.
295295
317317
318318 A recorded session can be read on its own page, linked from the work item, the
319319 pull request's **Session** tab and the workspace's
320−[Sessions](/guides/sessions/#the-sessions-page): who ran
320+[Sessions](/work/sessions/): who ran
321321 it, its subagents as a tree, the skills used, what it touched, and the
322322 work items and pull requests it worked on.
323323
+2−2
252252 g1t work reopen 12
253253 ```
254254
255−[Work items](/guides/work-items/) belong to the workspace, and `g1t work`
255+[Work items](/work/work-items/) belong to the workspace, and `g1t work`
256256 works on the current repository's workspace, or the one in `--workspace`
257257 (or `G1T_WORKSPACE`). `-R` filters `g1t work list` to the work items
258258 linked to that repository, and names the repository `g1t work link` and
465465 | `g1t session updates [ID]` | What other sessions did that concerns this one (claims, overlaps, dependency changes, decisions, merge queue results), oldest first, up to 100. Reading never clears them. It first says which files the working copy changed, so overlapping edits are noticed (`G1T_TOUCH=0` turns that off). |
466466 | `g1t session acknowledge ID... --note TEXT` | Records your decision about those updates (what changes in your plan, or why nothing does) and clears exactly the IDs given, for this session only; `--session` names another of yours. Saying the same again does nothing. |
467467 | `g1t session end` | Ends it, with an optional `--reason` and `--result` (what it reported; `-` reads it from stdin), and forgets it. Its subagents still going end with it. |
468−| `g1t session list` | The repository's sessions; `--state active`, `--item`, `--pull` (any session tied to it), `--path` (those that touched a file, or a folder ending in `/`), `--subagents` to list subagents under the sessions that started them. `--workspace` (this repository's workspace) or `--workspace SLUG` lists the sessions of every repository of a workspace instead, narrowed by `--harness`, `--person`, `--in NAME` (a repository of it), `--state`, `--item` and `--subagents`; see [the Sessions page](/guides/sessions/#the-sessions-page). |
468+| `g1t session list` | The repository's sessions; `--state active`, `--item`, `--pull` (any session tied to it), `--path` (those that touched a file, or a folder ending in `/`), `--subagents` to list subagents under the sessions that started them. `--workspace` (this repository's workspace) or `--workspace SLUG` lists the sessions of every repository of a workspace instead, narrowed by `--harness`, `--person`, `--in NAME` (a repository of it), `--state`, `--item` and `--subagents`; see [the Sessions page](/work/sessions/). |
469469 | `g1t session view [ID]` | A session and what it recorded, its subagents and their results, the work items and pull requests it worked on, and the skills used; the current one without an id. |
470470
471471 The id is kept in `.git/g1t/session`, in the working copy's own git
+2−2
512512 | `reviewers` | Usernames whose review is asked for when the pull request opens. A team (`org/team`) is skipped. Also applies to security updates. | |
513513 | `registries` | The [registries](#private-registries) the entry uses: a list of names, or `"*"` for all of them. | |
514514 | `target-branch` | The branch updates start from and merge into. Its manifests are read, each update is made from it, and its pull request's [base](/guides/base-branches/) is that branch. The default branch's protection does not cover it. | The default branch |
515−| `labels` | The [labels](/guides/labels/) put on each pull request. A label the repository lacks is created. `labels: []` puts none on. | `dependencies` and the ecosystem's label |
516−| `milestone` | The number of a [milestone](/guides/milestones/) to put each pull request in. A number the repository has no milestone for is skipped. | |
515+| `labels` | The [labels](/work/labels/) put on each pull request. A label the repository lacks is created. `labels: []` puts none on. | `dependencies` and the ecosystem's label |
516+| `milestone` | The number of a [milestone](/work/milestones/) to put each pull request in. A number the repository has no milestone for is skipped. | |
517517 | `vendor` | Read. Vendored copies of dependencies are not updated. | `false` |
518518 | `insecure-external-code-execution` | Read. g1t never runs a manifest's code while updating it. | |
519519 | `name` | A name for the entry, 3 to 100 characters, shown in the footer of its pull requests. | |
+2−2
327327 - **It lands the work items its commits name.** A commit pushed to the
328328 default branch whose message says `Fixes #12`, `Closes #12` or another
329329 closing keyword marks this repository as landed on that
330− [work item](/guides/work-items/), and the work item records which commit
330+ [work item](/work/work-items/), and the work item records which commit
331331 landed it and who pushed it. The work item closes as completed once every
332332 repository it targets has landed, or at once when it has no target.
333333 `Part of #12` links the commit without landing anything. Up to 250
344344 A repository whose **Land work items with merged linked pull requests**
345345 setting is off lands no work items either way. In a commit message on g1t,
346346 `#12` links to that work item or pull request; see
347−[one number for the workspace](/guides/work-items/#one-number-for-the-workspace).
347+[one number for the workspace](/work/work-items/#one-number-for-the-workspace).
348348
349349 ## Limits
350350
+1−1
8383 GitHub account, and import from the accounts an owner connected.
8484 4. Tick the repositories to bring across. You see only repositories that
8585 both you and the app can reach.
86−5. Choose whether to copy their issues, as [work items](/guides/work-items/).
86+5. Choose whether to copy their issues, as [work items](/work/work-items/).
8787 6. Choose **Bring to g1t**.
8888
8989 Each repository becomes a repository on g1t with the same name, private if
+1−1
323323 | Commits are pushed to a project's default branch, or a tag is pushed | The workspace's projects (the first 25) |
324324 | A pull request is opened, reviewed, merged or closed, a comment changes, or a work item linked to one of them changes | The same projects |
325325 | A workflow run or a job in it starts or finishes, a build or deployment moves, or a release or package is published | The same projects |
326−| A [session](/guides/sessions/) starts or ends | The same projects |
326+| A [session](/work/sessions/) starts or ends | The same projects |
327327 | Something comes to need you, or you deal with it elsewhere | Your notifications |
328328
329329 A busy workspace sends changes all the time, so Home refreshes a second
+1−1
9292
9393 ## Alerts
9494
95−An alert source opens [work items](/guides/work-items/) filed in one
95+An alert source opens [work items](/work/work-items/) filed in one
9696 repository, their origin. Each problem it reports is one work item:
9797
9898 - **The first alert** opens a work item labelled `bug` (or the label you set)
+0−124
1−---
2−title: Labels
3−description: Say what a work item or pull request is with colored labels, filter lists by them, and manage your workspace's labels.
4−---
5−
6−A label says what a work item or a pull request is: a `bug`, a `question`,
7−`good first issue`. Labels belong to the workspace, so every repository in
8−it uses the same ones, each with a name, a color and a description. Work
9−items and pull requests carry them by name, lists show them as colored
10−chips, and you can filter either list by one.
11−
12−## The labels a workspace starts with
13−
14−A new workspace starts with these:
15−
16−| Label | Color | Description |
17−| --- | --- | --- |
18−| `bug` | `d73a4a` | Something isn't working |
19−| `documentation` | `0075ca` | Improvements or additions to documentation |
20−| `duplicate` | `cfd3d7` | This work item or pull request already exists |
21−| `enhancement` | `a2eeef` | New feature or request |
22−| `good first issue` | `7057ff` | Good for newcomers |
23−| `help wanted` | `008672` | Extra attention is needed |
24−| `invalid` | `e4e669` | This doesn't seem right |
25−| `question` | `d876e3` | Further information is requested |
26−| `wontfix` | `ffffff` | This will not be worked on |
27−| `dependencies` | `0366d6` | Updates a dependency |
28−| `security` | `ee0701` | A security fix or a vulnerability |
29−
30−Labels used to belong to each repository. When they moved to the
31−workspace, labels with the same name became one, and the one made first
32−kept its color and description; see
33−[Issues became work items](/about/issues-became-work-items/#labels-and-milestones).
34−To add the defaults a workspace lacks:
35−
36−1. Open **Work**, then **Labels**.
37−2. Choose **Add the default labels**.
38−
39−Labels the workspace has already are left as they are.
40−
41−## Put labels on a work item or a pull request
42−
43−1. Open the work item or pull request.
44−2. In the sidebar, choose the settings icon beside **Labels**.
45−3. Tick labels on and off. Type to find one by its name or description.
46−4. Close the menu. The labels save as it closes.
47−
48−Each label put on or taken off is noted in the conversation, and is a
49−`work_item.labeled` or `work_item.unlabeled` event (`pull.labeled` and
50−`pull.unlabeled` on a pull request).
51−
52−Who may do this:
53−
54−- The author of a work item or a pull request, and whoever asked g1t for
55− one, may use the workspace's labels on it.
56−- Anyone with the Triage [role](/guides/access-and-roles/) or higher may
57− label anything, and make a label as they go: type a name the workspace
58− does not have, and choose **Create**.
59−
60−A work item or a pull request carries at most 20 labels.
61−
62−You can label a work item as you open it, too: tick labels on **New work
63−item**, or with the Write role, type new ones beside them.
64−
65−## Filter by a label
66−
67−On **Work** or **Pull requests**, choose **Label** and pick one. The
68−address keeps it, as `?label=bug`, so the filtered list can be shared. You
69−can also write it as `?q=label:bug`, with quotes around a name with
70−spaces: `?q=label:"good first issue"`. **Clear filters** shows everything
71−again.
72−
73−## Manage the workspace's labels
74−
75−Open **Work**, then **Labels**, at `g1t.sh/<workspace>/-/work/labels`. It
76−lists every label with its description and how many work items and pull
77−requests carry it; choose a count to see them. Search finds a label by its
78−name or description.
79−
80−With the Write role in the workspace or higher you can (applying labels
81−needs only Triage):
82−
83−| To | Do this |
84−| --- | --- |
85−| Make a label | **New label**: a name (lowercase, at most 50 characters), a description (at most 100), and a color. |
86−| Change one | **Edit**. Renaming a label renames it on every work item and pull request that carries it, in every repository. |
87−| Delete one | **Delete**. It comes off everything that carries it. This cannot be undone. |
88−
89−Names are lowercase and unique in a workspace: `Bug` and `bug` are the
90−same label.
91−
92−## Labels and g1t
93−
94−- [Dependency updates](/guides/dependency-updates/) carry `dependencies`
95− and their ecosystem's label (`javascript`, `rust`, `go`, `python`, …)
96− unless `labels` in the file says otherwise. Labels the workspace lacks
97− are made for them.
98−- [Workflows](/guides/actions/) can start on `labeled` and `unlabeled`
99− activity of `pull_request`.
100−
101−## From the API
102−
103−| To | REST | MCP |
104−| --- | --- | --- |
105−| List labels | `GET /workspaces/{workspace}/labels` | `workspace` `list_labels` |
106−| Make one | `POST /workspaces/{workspace}/labels` | `workspace` `create_label` |
107−| Change one | `PATCH /workspaces/{workspace}/labels/{label}` | `workspace` `update_label` |
108−| Delete one | `DELETE /workspaces/{workspace}/labels/{label}` | `workspace` `delete_label` |
109−| Add the defaults | `POST /workspaces/{workspace}/labels/defaults` | `workspace` `add_default_labels` |
110−
111−URL-encode a label's spaces in a path: `good%20first%20issue`.
112−
113−```sh
114−curl -X POST https://api.g1t.sh/workspaces/acme/labels \
115− -H "Authorization: Bearer $G1T_TOKEN" \
116− -H "Content-Type: application/json" \
117− -d '{"name": "needs design", "color": "fbca04"}'
118−```
119−
120−`labels` on the work item routes (`POST /workspaces/{workspace}/work` and
121−`PATCH /workspaces/{workspace}/work/{number}`, the `work_item` tool's
122−`create` and `update`) and on `update_pull_request` set an item's labels,
123−and `label` filters `list_work_items` and `list_pull_requests`. Managing
124−labels needs a token with `work:write`, and listing them `work:read`.
+2−2
194194
195195 ### Work items
196196
197−On **Settings → Repository**, under **Features**. [Work items](/guides/work-items/)
197+On **Settings → Repository**, under **Features**. [Work items](/work/work-items/)
198198 belong to the workspace; these settings say how this repository takes part.
199199
200200 | Setting | Field | Default | What it does |
347347
348348 Everything stays with the repository: its git data, pull requests,
349349 workflow runs, deployments, settings, secrets and webhooks, and the
350−[work items](/guides/work-items/) linked to it stay linked. Its old address
350+[work items](/work/work-items/) linked to it stay linked. Its old address
351351 keeps working, the same way as after a
352352 [transfer](/guides/transferring-repositories/#old-addresses):
353353
+2−2
268268 4. A [decision record](/guides/why-blame/#decision-records) of kind
269269 `integration_failure`, confidence `tested`, keeps it, with the
270270 combination, the check, the suspects, `bisected` and `landed` as
271− evidence. [`get_work`](/guides/sessions/)'s `last_integration_failure`
271+ evidence. [`get_work`](/work/agents/#pick-up-a-work-item)'s `last_integration_failure`
272272 is the latest of these.
273273 5. The `integration.failed` [event](/guides/webhooks/#events) carries the
274274 same to webhooks and to anyone following the repository's events:
287287 one that answers for it marked, the check that failed (linked to its run),
288288 what it fails with, and the fix once one is recorded. Its work item shows the
289289 same under its pull requests, and the workspace's
290−[Sessions](/guides/sessions/#the-sessions-page) lists it under **What
290+[Sessions](/work/sessions/) lists it under **What
291291 happened**.
292292
293293 ### Getting back in the queue
+0−96
1−---
2−title: Milestones
3−description: Gather work items and pull requests from across your workspace under a goal and a due date, and see how much of it is done.
4−---
5−
6−A milestone gathers work items and pull requests under one goal, such as a
7−release, with an optional due date. Milestones belong to the workspace, so
8−one can hold work from any of its repositories. Its page shows everything
9−in it and how far along it is: the share of its work items and pull
10−requests that are closed. A merged pull request counts as closed.
11−
12−## Make a milestone
13−
14−You need the Triage [role](/guides/access-and-roles/) in the workspace or
15−higher.
16−
17−1. Open **Work**, then **Milestones**.
18−2. Choose **New milestone**.
19−3. Give it a title, unique in the workspace, and if you like a due date
20− and a description. The description is Markdown.
21−4. Choose **Create milestone**.
22−
23−Milestones are numbered from 1 in each workspace, apart from work items
24−and pull requests. The number is in its address:
25−`g1t.sh/<workspace>/-/work/milestones/3`.
26−
27−Milestones used to belong to each repository. When they moved to the
28−workspace they were numbered again, and each records the repository it
29−came from; see
30−[Issues became work items](/about/issues-became-work-items/#labels-and-milestones).
31−
32−## Put a work item or a pull request in one
33−
34−1. Open the work item or pull request.
35−2. In the sidebar, choose the settings icon beside **Milestone**.
36−3. Pick a milestone, or **Clear milestone** to take it out.
37−
38−An item is in at most one milestone. Moving it is noted in the
39−conversation, and is a `work_item.milestoned` or `work_item.demilestoned`
40−event (`pull.milestoned` and `pull.demilestoned` on a pull request). With
41−the Triage role you can also choose a milestone on **New work item**.
42−
43−## Follow its progress
44−
45−**Milestones** lists open milestones soonest due first, then those without
46−a due date; **Closed** lists the rest, most recently closed first. Each
47−shows its due date, how many of its items are open and closed, and a bar
48−of how much is done. One whose due date has passed says how late it is.
49−
50−A milestone's page lists its open and closed work items and pull
51−requests, newest first. On **Work** or **Pull requests**, choose
52−**Milestone** to filter the list by one; the address keeps it as
53−`?milestone=3`.
54−
55−## Change, close or delete one
56−
57−With the Write role in the workspace or higher, on **Milestones** or a
58−milestone's page (putting a work item in one needs only Triage):
59−
60−| To | Do this |
61−| --- | --- |
62−| Change its title, due date or description | **Edit**, on its page. |
63−| Close it, once it is done | **Close**. **Reopen** opens it again. |
64−| Delete it | **Delete**. What was in it stays as it is, in no milestone. This cannot be undone. |
65−
66−## From the API
67−
68−| To | REST | MCP |
69−| --- | --- | --- |
70−| List milestones | `GET /workspaces/{workspace}/milestones`, `state` to filter | `workspace` `list_milestones` |
71−| Get one with its items | `GET /workspaces/{workspace}/milestones/{milestone}` | `workspace` `get_milestone` |
72−| Make one | `POST /workspaces/{workspace}/milestones` | `workspace` `create_milestone` |
73−| Change one | `PATCH /workspaces/{workspace}/milestones/{milestone}` | `workspace` `update_milestone` |
74−| Delete one | `DELETE /workspaces/{workspace}/milestones/{milestone}` | `workspace` `delete_milestone` |
75−
76−A milestone has `number`, `title`, `description`, `due_on` (`YYYY-MM-DD`),
77−`state` (`open` or `closed`), `open_items` and `closed_items`. Send
78−`"due_on": ""` to clear a due date, and `"state": "closed"` to close it.
79−
80−```sh
81−curl -X POST https://api.g1t.sh/workspaces/acme/milestones \
82− -H "Authorization: Bearer $G1T_TOKEN" \
83− -H "Content-Type: application/json" \
84− -d '{"title": "Launch", "due_on": "2026-10-14"}'
85−```
86−
87−`milestone`, a milestone's number, puts an item in it when you open or
88−change a work item (`POST /workspaces/{workspace}/work`,
89−`PATCH /workspaces/{workspace}/work/{number}`) and on
90−`update_pull_request`; `null` or `0` takes it out. Work items and pull
91−requests carry `milestone` as `{"number", "title"}`, and `milestone`
92−filters `list_work_items` and `list_pull_requests`. Managing milestones
93−needs a token with `work:write`, and reading them `work:read`.
94−
95−[Dependency updates](/guides/dependency-updates/) put their pull requests
96−in the milestone their entry's `milestone` names.
+26−22
55
66 The phone app is meant to be g1t on Android and iOS, with its own
77 screens for what you do away from a desk: triaging and discussing
8−[work items](/guides/work-items/) in Work, talking with your team in
8+[work items](/work/work-items/) in Work, talking with your team in
99 Chat, with notifications on your phone, and reviewing pull requests in
1010 Code. Everything else opens on the site, in your phone's browser.
1111
5151 | Tab | What is on it |
5252 | --- | --- |
5353 | **Home** | Coming. Opens Home on the site meanwhile. |
54−| **Work** | The workspace's work items and their Board, for every member, Code access or not. **Sessions** opens from the icon in its header. See [Work](#work). |
54+| **Work** | The workspace's work items, their Board and the sessions working on them: **Items**, **Board** and **Sessions** at its top. For every member, Code access or not. See [Work](#work) and [Sessions](#sessions). |
5555 | **Chat** | Your starred conversations, channels and direct messages, with what is unread, moving live. See [Chat](#chat). |
5656 | **Notifications** | Coming. Opens your notifications on the site meanwhile; messages to you already arrive [on the phone](#notifications). |
57−| **More** | **Sessions** first (see [Sessions](#sessions)), then **Code**, for members with Code access; whether this phone gets notifications, your workspaces, how you signed in, and **Sign out**. |
57+| **More** | **Explore** first, which opens on the site, then **Code**, for members with Code access; whether this phone gets notifications, your workspaces, how you signed in, and **Sign out**. |
5858
5959 **Code**, under **More**, is the workspace's repositories, each with its
6060 pull requests and its **Work**: the work items linked to it. A pull
6363
6464 ## Work
6565
66−Work on the phone is the site's [Work](/guides/work-items/), laid out for
67−one hand. A switch at its top, **Items | Board**, chooses between the
68−list and the Board.
66+Work on the phone is the site's [Work](/work/), laid out for one hand. A
67+switch at its top, **Items | Board | Sessions**, chooses between the list,
68+the Board and [Sessions](#sessions).
6969
70−- **The list** shows the workspace's open work items, newest first: each
71− with its number, title, state, labels and the repositories it is linked
72− to, which fold into "+2" past the first few. Pull down to read it
73− again; it loads more as you near its end.
70+- **The list** shows the workspace's work items, newest first, with
71+ **Open**, **Closed** and **All** under the switch: each with its number,
72+ title, state, labels and the repositories it is linked to, which fold
73+ into "+2" past the first few. Pull down to read it again; it loads more
74+ as you near its end.
7475 - **Filters** are in a sheet: tap the filter button in the header, a
7576 filter's chip above the list, or **Work** in the bar again. Choose the
7677 state, **Assigned to me**, a label, a milestone, a repository and its role.
8485 done, or as not planned), reopens it, links a repository as a target,
8586 copies its link, or opens it on the site. Tap a repository to open it or
8687 unlink it.
87−- **New work item** (the **+** on Work) takes a title, a description,
88+- **New work item** (**+ New** on Work) takes a title, a description,
8889 labels and the repositories it should land in; none is fine. Opened from
89− a repository's Work, that repository is its origin.
90−- **The Board** is the site's [Board](/guides/work-items/#the-board):
90+ the list filtered to a repository, that repository is its origin, and
91+ starts as a target too.
92+- **The Board** is the site's [Board](/work/board/):
9193 **Backlog**, **In progress**, **In review**, **Landing** and **Done**,
92− each card a work item with who or which session is on it. Tap a card to
93− open the work item.
94+ one under another, with a chip for each to show one alone. Each card is
95+ a work item with who or which session is on it. Tap a card to open the
96+ work item.
9497
9598 ## Sessions
9699
97−**Sessions** is the site's [Sessions](/guides/sessions/#the-sessions-page):
98−the sessions at work across the workspace. Open it from the icon in
99−Work's header, or first in **More**.
100+**Sessions** is the site's [Sessions](/work/sessions/),
101+a section of Work: the sessions at work across the workspace. Choose
102+**Sessions** at the top of **Work**, beside **Items** and **Board**.
100103
101104 - **Everything**, **Live** and **Recent** at the top choose what it
102105 lists. Pull down to read it again.
103−- **Filters** are in a sheet: **Started by me**, and a repository.
106+- **Filters** are in a sheet: **Started by me**, and a repository. Tap
107+ **Work** in the bar again to open it.
104108 - **A session** shows its facts (who, harness, repository, branch, state,
105109 when it was last heard from), what it is working on (its work item and
106110 pull request), its subagents as a tree, the files it touched, and its
183187 | `g1t://<workspace>/-/work/<number>` | The work item |
184188 | `g1t://<workspace>/-/work/new` | A new work item |
185189 | `g1t://<workspace>/-/work/board` | Work, on the Board |
186−| `g1t://<workspace>/-/sessions` | Sessions |
187−| `g1t://<workspace>/-/sessions/<id>` | The session |
190+| `g1t://<workspace>/-/work/sessions`, with its filters (`?state=live&repo=web`) | Work, on Sessions |
191+| `g1t://<workspace>/-/work/sessions/<id>` | The session |
188192 | `g1t://<workspace>/-/chat`, `…/-/chat/<channel>`, `…/-/chat/dm/<id>` | Chat, or the conversation, in that workspace |
189193 | `g1t://<owner>/<repo>` | The repository |
190194 | `g1t://<owner>/<repo>/pull/<number>` | The pull request |
192196
193197 The same paths as `https://g1t.sh/…` links, such as
194198 `https://g1t.sh/<workspace>/-/work/<number>` or
195−`https://g1t.sh/<workspace>/-/sessions/<id>`, open these screens once
199+`https://g1t.sh/<workspace>/-/work/sessions/<id>`, open these screens once
196200 g1t.sh publishes the files Android and iOS check first (see
197201 [below](#whats-not-there-yet)). The workspace's labels and milestones open
198202 on the site.
+2−2
1919
2020 Notifications hold one **thread** for each thing you were told about:
2121
22−- a [work item](/guides/work-items/)
22+- a [work item](/work/work-items/)
2323 - a pull request
2424 - a workflow on one branch
2525 - a deployment: a project's production, or one pull request's preview
207207 | **Tags** | A tag is pushed or deleted, or a release is published. |
208208 | **Pull requests** | One is opened, updated, reviewed, commented on, checked, merged or closed. |
209209 | **Work**, filtered or not, and its **Board** | Any of the workspace's work items is opened, changed, labeled, linked, claimed, commented on, closed or reopened. |
210−| **Sessions** | A session in one of the workspace's repositories starts, records or ends. |
210+| Work's **Sessions** | A session in one of the workspace's repositories starts, records or ends. |
211211 | A **pull request** | Commits are pushed to it, its checks report, someone reviews or comments, or it is merged or closed. New items join its timeline where you are reading; if you are at the end of the page, it follows them down. |
212212 | A **work item** | Someone comments on it or changes it, links a repository, claims it, or a pull request for it lands. If you are at the end of the page, it follows new items down. |
213213 | **Actions** and a **run** | A run starts, one of its jobs starts or finishes, or the run finishes. A running job's log streams on its own. |
+3−3
3737 | --- | --- | --- |
3838 | **Overview** | `g1t.sh/<workspace>/<project>` | What it is and its links; production wherever it is deployed, or for a library its packages; what is in progress, active branches, the latest commits, and its About. See [the overview](#the-overview). |
3939 | **Code** | `…/code` | The repository's files, commits and branches. |
40−| **Work** | `g1t.sh/<workspace>/-/work?repo=<name>` | The workspace's [work items](/guides/work-items/) linked to the repository. |
40+| **Work** | `g1t.sh/<workspace>/-/work?repo=<name>` | The workspace's [work items](/work/work-items/) linked to the repository. |
4141 | **Pull requests**, **Merge queue** | `…/pulls` and so on | As they always were. A pull request's **Session** tab is at `…/pull/<number>/session`. |
42−| **Sessions** | `g1t.sh/<workspace>/-/sessions?repo=<name>` | The workspace's [sessions](/guides/sessions/#the-sessions-page) in the repository. |
42+| **Sessions** | `g1t.sh/<workspace>/-/work/sessions?repo=<name>` | The workspace's [sessions](/work/sessions/) in the repository. |
4343 | **Actions** | `…/actions` | [GitHub Actions workflows](/guides/actions/). |
4444 | **Deployments** | `…/deployments` | What is up now and every build. |
4545 | **Settings** | `…/settings` | See below. |
7373 | **Facts** | Under production: its latest release (or, where the card does not already say it, production's state), how often checks pass, and either how many changes pass on the first try and what is open, or, for people with a role when [Observability](/guides/observability/) has data, requests and the error rate over the last day with how many errors are open. |
7474 | **Code** | One line to the repository: its name, default branch and when it was last pushed to, linking to **Code**. |
7575 | **Needs you** | For someone signed in: what is waiting on them, such as a failed production build or a pull request to merge or review. |
76−| **Live now** | The people and coding agents working on it: each work item with its [claims and sessions](/guides/sessions/), the harness each came from and who it acts for, and sessions on no work item yet. The workspace's [Sessions](/guides/sessions/#the-sessions-page), filtered to the repository (`g1t.sh/<workspace>/-/sessions?repo=<name>`), has everything. With nobody working, people with a role see how to [connect a coding agent](/guides/bring-your-own-agent/). |
76+| **Live now** | The people and coding agents working on it: each work item with its [claims and sessions](/work/claims-and-dependencies/), the harness each came from and who it acts for, and sessions on no work item yet. Work's [Sessions](/work/sessions/), filtered to the repository (`g1t.sh/<workspace>/-/work/sessions?repo=<name>`), has everything. With nobody working, people with a role see how to [connect a coding agent](/guides/bring-your-own-agent/). |
7777 | **Previews** | For people with a role: the pull requests' previews that are up. |
7878 | **Deployments** | Each environment's latest deployment and when. |
7979 | **Observability** | For people with a role, when there is data: the last day's requests, an hour a bar, latency, and the newest open errors. |
+12−62
529529
530530 When a pull request merges into the default branch, it lands its
531531 repository on the work item it was made for, and on every work item its
532−title or description names after a closing keyword: `close`, `closes`,
533−`closed`, `fix`, `fixes`, `fixed`, `resolve`, `resolves` or `resolved`, in
534−any case, with or without a colon:
535−
536−```text
537−Fixes #12. Resolves: #14, closes acme/api#15
538−```
539−
540−Landing marks the pull request's repository as landed on the work item and
541−records a resolution: the repository and the pull request. The work item
542−closes as completed when it has no target repositories, or once every
543−target has landed; until then it stays open, and its page says which
544−targets are missing. See [work items](/guides/work-items/#closing-a-work-item).
545−
546−`Part of #12` (also `Part of acme/api#12`, or `Refs #12`) links the pull
547−request to the work item, and its repository as touched, without landing
548−anything: use it for a pull request that does only part of a repository's
549−share.
532+title or description names after a closing keyword (`Closes #12`,
533+`Fixes #12`, `Resolves #12`, and their other forms). A work item closes
534+once every repository it targets has landed, or at the first landing when
535+it has no target. `Part of #12` (or `Refs #12`) links the pull request
536+without landing anything. Commits pushed to the default branch land work
537+items the same way.
550538
551−`#12` and `owner/name#12` name work items of the repository's own
552−workspace, whichever of its repositories they are written in. A work item
553−of another workspace is never closed. The pull request's `closes` lists
554−the work items it will land on, in the order named, and `parts` the ones it
555−is part of. Merging into any other branch lands nothing. A repository can
556−turn this off with `auto_close_items`; its pull requests then land nothing
557−when they merge.
558−
559−Commit messages land work items the same way. When a push to the default
560−branch brings in a commit whose message names a work item after a closing
561−keyword, the commit's repository lands on it. This applies to commits
562−pushed directly, merged in a clone, or landed by a pull request, and up to
563−250 commits per push are read. The work item's timeline says who pushed
564−it and **landed this in** that commit, its page shows the commit beside
565−the repository, and the commit's page lists the work items it landed on.
566−The resolution records the commit as `commit` and who pushed it as
567−`pushed_by`, and `work_item.closed`, when it closes, carries the commit as
568−`commit`; reopening a work item clears its resolutions. A push that makes
569−a new branch reads none of its commits, since they were pushed before,
570−except a repository's first push, which makes its default branch:
571−`Closes #1` in the first version of a new repository lands on #1. Commits
572−pushed to other branches land nothing until they reach the default branch,
573−and `auto_close_items` turns this off as well.
574−
575−A commit that is already on the default branch can land a work item later,
576−say one pushed before the work item was open or while `auto_close_items`
577−was off: [`close_work_item`](/reference/api/work-items/close-work-item/)
578−with `repo` and `commit` (its full hash), `g1t work close 12 --commit
579−<hash>` in the repository, or the `work_item` tool's `close` with `repo`
580−and `commit`. The commit's message must name the work item after a closing
581−keyword. Its repository then lands in that commit, the way a push of it
582−would have, by whoever did it. A commit that is not on the default branch,
583−or whose message does not name the work item, is refused, and so is a work
584−item that is already closed.
585−
586−A work item's timeline links whatever landed it: **landed this in** a
587−commit links the commit, **landed this by merging #14** links the pull
588−request, and when it was done in a [session](/guides/sessions/) the line
589−ends **via session**, linking that session. That session is the one the
590−closing commit names in a `G1t-Session: ses_…` trailer, or, for a work item
591−closed with a token (from an agent, the CLI or the MCP server), the
592−closer's own session on the work item that is still going.
593−`work_item.closed` carries it as `session`. A work item closed on the site
594−says only who closed it.
539+The pull request's `closes` lists the work items it will land on, in the
540+order named, and `parts` the ones it is part of. Merging into any other
541+branch lands nothing, and a repository can turn this off with
542+`auto_close_items`. [Closing work items](/work/closing/) has the whole of
543+it: the keywords, landing target by target, commits, closing by hand or
544+with a commit, and reopening.
595545
596546 Wherever a commit's message shows, `#12` links to that work item or pull
597547 request, with its title and state when you hover over it. Old issue
+1−1
129129 - A work item is shown to the members of its workspace, and to anyone who
130130 can read the repository it was filed in (its origin). One filed in a
131131 public repository is shown to everyone; one with no origin only to
132− members. See [who sees a work item](/guides/work-items/#who-sees-a-work-item).
132+ members. See [who sees a work item](/work/work-items/#who-sees-a-work-item).
133133 - People and workspaces are public, as their pages are. Search never shows
134134 which workspaces someone belongs to.
135135
+42−534
11 ---
2−title: Sessions, claims and dependencies
3−description: How agents and people see who is working on what, in a repository and across the workspace on Sessions, 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.
2+title: Recording sessions
3+description: How a harness records its sessions on g1t, with the API, MCP or the CLI. Start, heartbeat, record and end a session, record subagents, work before there is a work item, and have g1t start sessions on your Anthropic account.
44 ---
55
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:
6+A [session](/work/sessions/) is one run of your harness on a repository:
7+a Claude Code session, a Codex run. This page is for whoever wires a
8+harness up to g1t: how a session is started, kept alive, recorded and
9+ended, and how its subagents are recorded. The
10+[Claude Code plugin](/guides/claude-code-plugin/) does all of it for
11+Claude Code; other harnesses call the same API.
1112
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.
13+What sessions are for, and how the team sees them, is under Work:
14+[Sessions](/work/sessions/), [session titles](/work/session-titles/), and
15+[claims and dependencies](/work/claims-and-dependencies/), which keep
16+sessions out of each other's way.
1817
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, named by g1t from
21−what it does ([Session titles](#session-titles)), 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).
18+## Record a session
2419
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−## The Sessions page
20+Start a session when the harness starts, keep it alive while it works, and
21+end it when it stops.
3322
34−**Sessions** is in the left rail, directly after **Work**, at
35−`g1t.sh/<workspace>/-/sessions`. It shows what is cooking across the
36−workspace: the sessions in every one of its repositories you can read,
37−as they happen, without reloading.
38−
39−- **Live now**: the active and idle sessions, the most recently heard
40− from first. Each card shows the session's title, who it acts for, its
41− harness, its repository and branch, the work item and pull request it
42− is on, when it was last heard from, how many subagents it has, and
43− whether it is live or idle. A session with no title is named by what
44− its first prompt was for, else **Session on** its branch, else
45− **Untitled session**. A title that is only a tag, such as
46− `<pasted_content id="5c50">`, counts as no title.
47−- **Merge queue**: each repository's merge queue that has something
48− waiting, as on its [Merge queue](/guides/merge-queue/#the-merge-queue-page)
49− page.
50−- **Just landed**: the pull requests merged lately, across the
51− repositories, each with a link to the session behind it.
52−- **What happened**: the latest coordination events across the
53− repositories: claims, sessions starting and ending, overlaps, and what
54− the merge queue found when it combined changes.
55−- **Recent**: the sessions that ended lately.
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−
61−Narrow it by repository (`?repo=web`), person (`?person=<username>`),
62−harness (`?harness=codex`), kind (`?kind=hosted`) and state. The address
63−keeps the filters, so a filtered view can be shared. A repository's
64−sessions are Sessions filtered to it,
65−`g1t.sh/<workspace>/-/sessions?repo=<name>`: a repository has no
66−Sessions page of its own.
67−
68−Every kind of session is listed in this one place:
69−
70−| Kind | Is |
71−| --- | --- |
72−| `harness` | A run of someone's own harness (Claude Code, Codex, Cursor, Copilot or another), with its [subagents](#subagents) under it. |
73−| `hosted` | A session started on g1t, from a work item or the web, on the workspace's Anthropic provider: harness `claude_managed_agents`. See [Start a session on your Anthropic account](#start-a-session-on-your-anthropic-account). |
74−| `agent` | g1t's own agent at work on a pull request. Only the workspace's members see these. |
75−| `recorded` | A session recorded on a pull request with no session of its own. It opens on the pull request's **Session** tab, `g1t.sh/<owner>/<repo>/pull/<number>/session`. |
76−
77−**A session's page** is `g1t.sh/<workspace>/-/sessions/<id>` (the
78−`ses_…` id), opened from Sessions or from anywhere the session is listed:
79−who ran it, in which harness and on which model, how long it has run, its
80−repository, the work items and pull requests it and its subagents worked
81−on (each says how it was tied), its subagents as a tree you open one at a
82−time (each with its kind, the task it was given, what it touched and what
83−it reported), the skills used, what was touched (files, commits, branches,
84−pull requests), and everything it recorded, as it records it: its prompt
85−folded, its messages formatted as they were written, and the tool calls
86−between them a line each (a command as code, a file by its path, a g1t
87−tool by what it did, such as *work item · claim*), more than three in a
88−row folded into one line that opens to them; a long command and what a
89−tool gave back open under its line. A subagent's own page links back to
90−the session that started it.
91−
92−The same list is in the API, MCP and the CLI:
93−[`GET /workspaces/{workspace}/sessions`](/reference/api/sessions/list-workspace-sessions/)
94−by `state` (`live`, `recent` or `ended`), `kind` (`harness`, `hosted`,
95−`agent` or `recorded`), `harness`, `person`, `repo`, `item`, `subagents`
96−and `limit`, which returns the `sessions`, each repository's `queue`, what
97−`landed` and the `repos` it covers;
98−[`GET /workspaces/{workspace}/sessions/{id}`](/reference/api/sessions/get-workspace-session/)
99−for one session, with its `repo`. Over MCP, the `session` tool's `list`
100−takes `workspace` instead of `repo`, and `get` takes `workspace` and `id`.
101−From the CLI:
102−
103−```sh
104−g1t session list --workspace # this repository's workspace
105−g1t session list --workspace acme --in web # one repository of it
106−g1t session list --workspace --harness codex --state active
107−```
108−
109−`--workspace` takes a slug, or none for the current repository's
110−workspace; `--harness`, `--person`, `--in NAME` (a repository of it),
111−`--state` (active or idle: what is going now; ended), `--item` and `--subagents` narrow it.
112−
113−## On the site
114−
115−Besides **Sessions**, sessions and claims show where the work is, as it
116−happens, without reloading.
117−
118−- **A work item's Work panel**, at the top of its sidebar: its claims
119− (who, from which harness, since when and when each lapses; ones
120− released, expired or handed off lately are shown dimmed), the sessions on
121− it with their state and when each was last heard from, what
122− it is blocked by and where each of those stands, and the work items it
123− blocks. Its author and anyone with the Triage role change what it is
124− blocked by with **Edit**. Under its pull requests, the work item shows
125− the latest combination that failed in the merge queue, and its
126− [decision records](/guides/why-blame/#decision-records), each marked
127− **Claimed**, **Tested** or **Approved**.
128−- **A work item's and a pull request's sessions**: every session tied to
129− it in any way, in any of the workspace's repositories, with its
130− subagents under it. A pull request's **Session** tab,
131− `g1t.sh/<owner>/<repo>/pull/<number>/session`, is what was recorded on
132− it.
133−- **A project's overview**: **Live now**, the people and coding agents
134− working on that repository, grouped by work item, then by pull request
135− or branch. See [the overview](/guides/projects/#the-overview).
136−- **Start a session** on a work item, for members of a workspace with an
137− Anthropic AI provider: see
138− [Start a session on your Anthropic account](#start-a-session-on-your-anthropic-account).
139−
140−## Session titles
141−
142−A session's title names the whole of its work, and settles instead of
143−following each turn. Each title says where it came from (`title_source`)
144−and when it settled (`title_settled_at`):
145−
146−| Source | What it is |
147−| --- | --- |
148−| `prompt` | Provisional: what its first prompt asked for (its first line or sentence, without pasted text, image placeholders, code or markdown). Shown muted. |
149−| `item`, `pull`, `summary` | Settled by g1t from the session's record. |
150−| `agent` | Its harness or agent named it (`title` on start or update, `g1t session attach --title`). |
151−| `person` | Someone renamed it on its page: pinned. Neither g1t nor the agent replaces it. **Let g1t name it** unpins it. |
152−
153−g1t settles a provisional title once there is enough to go on: the session
154−claims or is attached to a work item, opens or pushes a pull request,
155−records three prompts, or has run for 30 minutes. It names it again only
156−when what the session works on changes (another work item or pull
157−request, or many more prompts), at most every 20 minutes and only when the
158−new title says something else, and a last time when the session ends,
159−from everything it did. An agent's own title is kept, unless the session
160−went on to other work items or pull requests after it was named, when it
161−is named again as it ends.
162−
163−With an [AI provider](/guides/ai/) chosen for Ask, the provider names the
164−session in a few words, on its fast model, from a short digest of the
165−record: its work items and pull requests, its prompts (as recorded, with
166−credentials taken out), its subagents' tasks, where it changed files, its
167−commits and what it reported. A session is asked about at most five times,
168−and one whose work is a single work item or pull request takes that title
169−without asking. Without a provider, or when it fails, the title is the
170−work item's, else the pull request's, else what the session's most telling
171−prompt asks for, without greetings and preambles ("This project used
172−to…", "I think", "So"). A subagent goes by its task and is not titled.
173−
174−## Picking up a work item
175−
176−Before working on a work item, load its whole context in one call:
177−`work_item` with `"action": "work"` over MCP, `g1t work view 12`, or
178−[`GET /workspaces/{workspace}/work/{number}/work`](/reference/api/work-items/get-work/):
179−
180−```sh
181−curl https://api.g1t.sh/workspaces/acme/work/12/work \
182− -H "Authorization: Bearer $G1T_TOKEN"
183−```
184−
185−| Field | What it holds |
186−| --- | --- |
187−| `item` | The work item, with its body and its repositories: each with its role and whether it has landed. |
188−| `missing` | Its targets that have not landed yet. |
189−| `suggested` | Repositories of the workspace it may also need, each with `why`. |
190−| `definition_of_done` | The items under its **Definition of done** heading. |
191−| `required_checks` | The checks every pull request into the default branch must pass. |
192−| `claims` | Who says they are working on it now. |
193−| `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. |
194−| `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`. |
195−| `blocked_by` | Each work item it waits on, with that work item's claims and pull requests. |
196−| `blocks` | The work items waiting on it. |
197−| `decisions` | [Decision records](/guides/why-blame/#decision-records) on it and its pull requests, newest first. |
198−| `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. |
199−| `recent` | Its latest 20 coordination events, newest first. |
200−
201−Then claim it, and start (or attach) your session.
202−
203−## Sessions
204−
205−A session is one run of your harness on a repository. Start one when the
206−harness starts, keep it alive while it works, and end it when it stops.
207−
208−1. **Start** it with `session` `start`, or
23+1. **Start** it with `session` `start`, `g1t session start`, or
20924 [`POST /repos/{owner}/{name}/sessions`](/reference/api/sessions/start-session/),
210− naming the `harness` (`claude_code`, `claude_managed_agents`, `codex`,
211− `cursor`, `copilot` or `other`) and the harness's own id for the session as
25+ naming the `harness` (`claude_code`, `codex`, `cursor`, `copilot` or
26+ `other`) and the harness's own id for the session as
21227 `harness_session_id`. Starting again with the same id returns the
21328 session already started, so a hook can call it every time without
21429 checking first. Give `item` (the work item's number in the
21530 repository's workspace), `pull` and `branch` when you know them, and a
21631 `title` only if you can name the whole job in a few words (up to 200
217− characters): otherwise g1t names it (see [Session titles](#session-titles)).
218−2. **Heartbeat** with `session` `update`, or
32+ characters): otherwise g1t names it (see
33+ [session titles](/work/session-titles/)).
34+2. **Heartbeat** with `session` `update`, `g1t session heartbeat`, or
21935 [`PATCH /repos/{owner}/{name}/sessions/{id}`](/reference/api/sessions/update-session/)
22036 with an empty body. The same call attaches the session to a work item
221− or pull request, records the `head_commit` it pushed, or names it
222− (`title`; a title a person pinned stays).
37+ or pull request (`g1t session attach --item 12`), records the
38+ `head_commit` it pushed, or names it (`title`; a title a person pinned
39+ stays). A heartbeat also renews the session's claims.
22340 3. **Record** what happens with `session` `record`, or
22441 [`POST /repos/{owner}/{name}/sessions/{id}/entries`](/reference/api/sessions/record-session-entries/):
22542 prompts, reasoning, tool calls, notes and the skills it used (`skill`,
22643 the skill's name only), up to 200 a request, and in `touched` what it
227− touched (see [What a session worked on](#what-a-session-worked-on)).
44+ touched (see [what a session records](/work/sessions/#what-a-session-records)).
22845 Give each entry a `key`, and recording it again does nothing.
229−4. **End** it with `session` `end`, or
46+4. **End** it with `session` `end`, `g1t session end`, or
23047 [`POST /repos/{owner}/{name}/sessions/{id}/end`](/reference/api/sessions/end-session/),
23148 with its `result` when it has one: what it reported when it finished.
23249
23754 -d '{"harness": "claude_code", "harness_session_id": "5b0c1f9e-3d2a-4e8b-9f61-0c7d2a9e4b13", "item": 12}'
23855 ```
23956
240−A session's `state` is worked out from when it was last heard from. Every
241−update and every batch of entries counts as a heartbeat:
242−
243−| State | Means |
244−| --- | --- |
245−| `active` | Heard from in the last 15 minutes. |
246−| `idle` | Not heard from for 15 minutes. It may still come back. |
247−| `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. |
248−
249−A session its harness left behind, killed or never told to end, can be
250−ended by hand: **End session** in its menu under Live now (on the
251−project's overview and on **Sessions**), or on its page. Whoever runs a
252−session can end it, and so can anyone with write access to the
253−repository; nobody else sees the action. It ends with `end_reason`
254−`ended by hand by @name`, its subagents still going end with it, and its
255−claims stay until they are released or expire. Ending by hand is a
256−soft close: like a session that timed out, it comes back the moment
257−its harness is heard from again (an update, a recorded entry or a
258−start), so a harness that was in fact still running picks up where it
259−was. Through the API,
260−`end_session` on someone else's session does the same, without their
261−`reason` or `result`. A session g1t runs on the workspace's Anthropic
262−account is stopped from its page instead.
57+Every update and every batch of entries counts as a heartbeat. A session
58+not heard from for 15 minutes is idle, and after 30 minutes it ends as
59+timed out, until a heartbeat brings it back; see
60+[states](/work/sessions/#states). A session g1t runs on the workspace's
61+Anthropic account is recorded as harness `claude_managed_agents`.
26362
26463 Entries of a session attached to a pull request show in that pull
26564 request's [session](/guides/why-blame/#sessions), beside what was recorded
26867 does. A session never records tool output unless you send it as a
26968 `tool_result` entry. What looks like a credential is taken out of
27069 everything a session records, and only the workspace's members see inside
271−a session: see [Who sees what](#who-sees-what).
70+a session: see [who sees what](/work/sessions/#who-sees-what).
27271
273−List a repository's sessions with `session` `list`, or
274−[`GET /repos/{owner}/{name}/sessions`](/reference/api/sessions/list-sessions/)
275−by `state`, `item` or `pull` (any session tied to it), or `path` (those
276−that touched a file, or any under a folder ending in `/`); subagents are
277−listed too with `subagents=true`. A session in the list with no `title`
278−carries `first_prompt`: the first 300 characters of the first prompt it
279−recorded. Read one with its entries, subagents, links, skills and what it
280−touched with `session` `get`. For the sessions of every repository of a
281−workspace, see [The Sessions page](#the-sessions-page).
72+Updating, recording in and ending a session needs the token that started
73+it; starting one needs a confirmed email address and a role that may file
74+work items. With an access token, sessions need `pull_requests:write`.
75+See [who may do what](/work/claims-and-dependencies/#who-may-do-what).
28276
28377 ## Work with no work item yet
28478
28781 session is the record of that work, and the team sees it in **Live now**,
28882 on **Sessions** and on the project's overview, while it goes:
28983
290−1. **It says what it is for.** Give it a `title` when you start it, or
291− later with `session` `update`. The
292− [Claude Code plugin](/guides/claude-code-plugin/#work-with-no-work-item-yet)
293− titles each session from its first prompt that says what it is for,
294− from the words you typed: pasted text and image placeholders are left
295− out, and a slash command or a prompt that is only a paste leaves the
296− title to the next prompt. It never replaces a title the session
297− already has.
84+1. **It says what it is for.** g1t names it from what it does, first
85+ from its first prompt, then from its whole record (see
86+ [session titles](/work/session-titles/)). Give it a `title` yourself,
87+ when you start it or later with `session` `update`, only if you can
88+ name the whole job.
29889 2. **It shows where it works.** Attach its `branch` and, once there is
29990 one, its `pull`: the project's **Live now** groups sessions on no work
30091 item by pull request, then by branch.
30293 should know about: a branch to push, a pull request. Look for one first
30394 (`work_item` `list`, `work_item` `list_claims`); if one covers the work,
30495 claim it. Otherwise open one and claim it in one step with `work_item`
305− `claim` and a `title` instead of a `number` (see [Claims](#claims)),
96+ `claim` and a `title` instead of a `number` (see [claims](/work/claims-and-dependencies/#claims)),
30697 which attaches the session to it.
30798
30899 ## Subagents
333124 same file, each is told with `overlap.detected`. The
334125 [Claude Code plugin](/guides/claude-code-plugin/#subagents) does all of
335126 this for Claude Code's subagents.
336−
337−## What a session worked on
338−
339−A session says what it touched in `touched`, each kept once:
340−
341−| `kind` | `value` |
342−| --- | --- |
343−| `file` | A file it wrote, from the repository's root. |
344−| `commit` | A commit it made. |
345−| `branch` | A branch it made or pushed. |
346−| `pull` | A pull request it opened, by number. |
347−| `item` | A work item it named or claimed, by its number in the workspace. |
348−
349−From these and the rest of what it records, g1t ties the session to the
350−work items and pull requests it worked on, each in as many ways as it was
351−(`via` in the session's `links`):
352−
353−| `via` | When |
354−| --- | --- |
355−| `attached` | It said it is on it, starting or updating. |
356−| `claim` | It claimed the work item. |
357−| `opened` | It opened the pull request. |
358−| `branch` | It pushed the pull request's branch, also when the pull request is opened later. |
359−| `commit` | It made the pull request's head commit. |
360−| `trailer` | A commit pushed to the pull request's branch names it in a `G1t-Session: ses_…` trailer. |
361−| `ref` | Its prompt, its task, its result or a subagent's names it as `#12`. |
362−
363−A session's links cover its subagents too, and the work item and pull
364−request pages list every session tied to them with its subagents. Put the
365−trailer on the commits a session makes (`git commit --trailer "G1t-Session:
366−$G1T_SESSION"`) and they lead back to it. A work item a session closes, or
367−a repository it lands on one, says so on its timeline, **via session** and
368−a link to it: closed with the session's token while it works on the work
369−item, or by a commit naming it in that trailer (see
370−[Closing work items](/guides/pull-requests/#closing-work-items)).
371−
372−When a file a session touched was touched by another active session as
373−well (outside its own parents and subagents), g1t sends `overlap.detected`
374−to both, naming each other and the files: once per pair, and again when
375−they touch another file in common, naming the new files.
376127
377128 ## Start a session on your Anthropic account
378129
499250 `@g1t rebase` and the other
500251 [comment commands](/guides/dependency-updates/#comment-commands) still do what
501252 they say.
502−
503−## Claims
504−
505−A claim says you are working on a work item. It is advisory: anyone may
506−claim a work item someone else has, and is told about them, so two agents
507−can decide between themselves rather than collide. Nothing is refused
508−because of a claim. A claim is the workspace's, whichever repository the
509−session that holds it is checked out in, so sessions in different
510−repositories see each other's claims on the same work item.
511−
512−- **Claim** an open work item with `work_item` `claim` (with
513− `session_id`, so that two of your sessions, such as sibling subagents,
514− hold claims of their own and each is told of the other's),
515− `g1t work claim 12`, or
516− [`POST /workspaces/{workspace}/work/{number}/claim`](/reference/api/work-items/claim-work-item/).
517− The answer has your `claim`, the `others` already on the work item, and
518− `blocked_by`: each work item this one waits on, with its claims and pull
519− requests.
520−- **Open a work item and claim it** in one step, for work that has no
521− work item yet: `work_item` `claim` with `title` (and `body`) and no
522− `number`, `g1t work claim --title "…"`, or
523− [`POST /workspaces/{workspace}/claims`](/reference/api/work-items/claim-new-work-item/).
524− The work item is opened (a `work_item.opened` event), with the
525− session's repository as its origin when you give `repo`, then claimed,
526− and the session named by `session_id` is attached to it. The answer
527− also has `item`, the work item opened. The session is checked first: a
528− claim that would be refused for it opens nothing.
529−- **Renew** it by claiming again, or give the `session_id` of your session
530− when you claim, and that session's heartbeats renew it.
531−- **Release** it with `work_item` `release`, `g1t work release 12`, or
532− [`POST /workspaces/{workspace}/work/{number}/release`](/reference/api/work-items/release-claim/),
533− with an optional `reason`.
534−- **Hand it off** with `work_item` `handoff`, `g1t work handoff 12`, or
535− [`POST /workspaces/{workspace}/work/{number}/handoff`](/reference/api/work-items/hand-off-work-item/),
536− with a `note` on where the work stands, for `to` (a username) or anyone.
537− When whoever it was for claims the work item, their `work.claimed` event
538− names the hand-off in `took_over`.
539−
540−```sh
541−curl -X POST https://api.g1t.sh/workspaces/acme/work/12/claim \
542− -H "Authorization: Bearer $G1T_TOKEN" \
543− -H "Content-Type: application/json" \
544− -d '{"session_id": "ses_01m4b2c3d4e5f6g7h8j9k0m1n2", "note": "Taking the argument parsing first."}'
545−
546−curl -X POST https://api.g1t.sh/workspaces/acme/claims \
547− -H "Authorization: Bearer $G1T_TOKEN" \
548− -H "Content-Type: application/json" \
549− -d '{"session_id": "ses_01m4b2c3d4e5f6g7h8j9k0m1n2", "repo": "acme/web", "title": "Preview builds time out on large repositories"}'
550−```
551−
552−| | |
553−| --- | --- |
554−| How long a claim lasts | `ttl_minutes`: 30 unless you say, at most 240. |
555−| Opening its work item | `title` (and `body`) instead of `number`. Giving both is refused with `422`. |
556−| When it ends | Released, handed off, its work item closed, or not renewed in time (`expired`). |
557−| States | `active`, `released`, `expired`, `handed_off`. |
558−
559−See who is on what with `work_item` `list_claims`, `g1t work status`, or
560−[`GET /repos/{owner}/{name}/claims`](/reference/api/work-items/list-claims/):
561−active claims unless `state` says otherwise, and `item` for one work
562−item's.
563−
564−## Dependencies
565−
566−A work item's `blocked_by` lists the work items of the same workspace that
567−have to land before it. Set it with `work_item` `update`, or
568−[`PATCH /workspaces/{workspace}/work/{number}`](/reference/api/work-items/update-work-item/),
569−which replaces the whole list:
570−
571−```sh
572−curl -X PATCH https://api.g1t.sh/workspaces/acme/work/12 \
573− -H "Authorization: Bearer $G1T_TOKEN" \
574− -H "Content-Type: application/json" \
575− -d '{"blocked_by": [9, 10]}'
576−```
577−
578−A list is refused with `422` when a number is not a work item of the
579−workspace, names the work item itself, or would make a cycle (the answer
580−shows the cycle, such as `#12 → #9 → #12`). Up to 50 work items. Changing
581−it notes the change in the work item's conversation and needs what
582−editing the work item does: being its author, or the Triage role.
583−
584−g1t says when a dependency moves, as a `dependency.changed` event on the
585−blocked work item: when its list changes, and when one of its blockers
586−closes or has a pull request merged into the default branch. `remaining`
587−lists the blockers still open; when it is empty, the work item is
588−unblocked.
589−
590−## Overlaps
591−
592−Opening a pull request, and each push to it, works out which files it
593−changes. When it starts changing files another open or draft pull request
594−changes, g1t sends `overlap.detected` once for each of the two, naming the
595−other and the files. A pair is announced once, and again only after it stopped
596−overlapping. `get_work` and `pull_request` `get` show current overlaps
597−whenever you look.
598−
599−Sessions overlap too, before there is a pull request: when a session says
600−it touched a file that another active session touched (see
601−[What a session worked on](#what-a-session-worked-on)), each gets
602−`overlap.detected` with `session_id`, `other_session_id`, `other_actor`
603−and `files`, once per pair, and again with the new `files` when another
604−file in common joins.
605−
606−## Events
607−
608−Coordination is published as events, which [webhooks](/guides/webhooks/)
609−deliver and the repository's timeline lists. Each carries `number` (the
610−work item or pull request it is about) and `item` (the work item's number
611−in the workspace) where there is one.
612−
613−| Event | When |
614−| --- | --- |
615−| `session.started` | A session (or a subagent) starts, or one that ended starts again. Not on a repeated start. |
616−| `session.ended` | A session ends, or times out after 30 minutes without a heartbeat. |
617−| `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. |
618−| `work.claimed` | Someone claims a work item. `others` lists the claims already on it; `took_over` names a hand-off it takes. |
619−| `work.released` | A claim is released, or its work item closed (`reason` `item_closed`). |
620−| `work.claim_expired` | A claim was not renewed in time. |
621−| `work.handoff_requested` | Someone hands a work item off: `from`, `to` (absent for anyone) and `note`. |
622−| `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. |
623−| `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`. |
624−
625−A session or claim that went quiet is announced as ended or expired when
626−the repository's sessions or claims are next read or changed, not at the
627−minute it lapsed.
628−
629−## Who sees what
630−
631−A session records someone's own work as it happens, so g1t shows it by who
632−is looking, on the site, the API, MCP and the CLI alike.
633−
634−| Who | Sees |
635−| --- | --- |
636−| Whoever ran it | All of it: its prompts, tool calls, what it touched and reported, its pending updates. |
637−| 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. |
638−| 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. |
639−
640−Before anything is kept, g1t takes out what looks like a credential
641−(`[redacted]`): every token format [secret protection](/guides/security/secret-protection/)
642−knows, any key or token by its issuer's prefix, `NAME_TOKEN=value`,
643−`password: value` and the like, `--token`/`--password` flags, `Bearer` and
644−`Authorization` headers, a URL's user and password and its signed query
645−parameters, JWTs, private keys, and long random-looking strings. What was
646−recorded before this is hidden the same way as it is read. The
647−[Claude Code plugin](/guides/claude-code-plugin/) does the same before
648−anything leaves your machine. It is a safety net, not a vault: keep
649−secrets out of prompts and command lines.
650−
651−## Who may do what
652−
653−| To | You need |
654−| --- | --- |
655−| 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). |
656−| Read a workspace's **Sessions** | It lists the sessions of the workspace's repositories you can read; g1t's own agent's sessions only for members. |
657−| 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). |
658−| 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. |
659−| Update, record in or end a session | To be the person whose token started it. |
660−| Release a claim or hand it off | To be the person who made it. |
661−| Set `blocked_by` | To be the work item's author, or the Triage role. |
662−| 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. |
663−
664−With an access token, sessions (and `start_agent_session`) need
665−`pull_requests:read` or `pull_requests:write`, and claims and `get_work`
666−need `work:read` or `work:write`, as
667−[scopes](/guides/authentication/#scopes) say.
668−
669−## Pending coordination updates
670−
671−These commands work with Codex, Claude, or another harness using the same
672−session API. There is no provider-specific acknowledgement protocol:
673−
674−```sh
675−g1t session updates --json
676−g1t session acknowledge upd_ID --note "My scope is separate; no plan change"
677−```
678−
679−They use `G1T_SESSION` (or the working copy's remembered session).
680−`session updates`, `session acknowledge` and `session heartbeat` first say
681−which files the working copy has changed (from `git status`), as
682−`session touch --file` would, so overlapping edits are noticed whichever
683−harness makes them; `G1T_TOUCH=0` turns that off. To avoid
684−shared-checkout ambiguity, `updates SESSION_ID` and `acknowledge --session
685−SESSION_ID` select a session explicitly. The acknowledgement command records
686−a decision note before clearing updates, with an idempotency key for retries.
687−The raw API below also works with older CLI installations.
688−
689−`g1t api get_session -f id=SESSION_ID` returns up to 100 pending `updates`,
690−oldest first, separately from transcript entries (give `after=4294967295` to
691−leave the entries out). Updates are claims, releases, hand-offs and expiries,
692−overlaps, dependency changes, decisions, integration results, and sessions
693−starting and ending.
694−
695−An active session receives the updates that concern it:
696−
697−| The session is | It receives |
698−| --- | --- |
699−| 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 |
700−| Not on anything yet | Every update, so it can find who else is working and on what |
701−| 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 |
702−
703−A session does not receive its own start or end, or the claims it made,
704−released or handed off. It does hear when its claim expires. New sessions
705−should still load the work item's context: an inbox is not a replay of what happened
706−before the session started.
707−
708−Reading does not clear an update. After considering it and recording any
709−change of plan, the session owner acknowledges exact IDs:
710−
711−```sh
712−g1t api record_session_entries -f id=SESSION_ID -f 'acknowledge[]=UPDATE_ID'
713−```
714−
715−Repeat the field for multiple IDs, at most 100 per request, then read again
716−for the next page. Acknowledgement is idempotent and scoped to that session.
717−It means considered, not resolved. The response's `acknowledged` says how
718−many of the IDs name updates of that session, so a mistyped ID or one from
719−another session shows up as a shortfall (the CLI warns). The session page
720−shows pending updates.
721−
722−Claude Code hooks retrieve updates in the background, at most once per ten
723−seconds when a successful cached response exists, and at once after an
724−acknowledgement. Every prompt shows what is pending; before a tool, pending
725−updates are shown when they change and again every two minutes. Delivery
726−repeats until acknowledged. Other
727−harnesses, including managed sessions, should poll between work steps using
728−the coordination skill. Neither a disconnected harness nor an idle session
729−is interrupted in real time.
730−
731−An update is written in the same transaction as the change it announces: a
732−claim, release, hand-off, expiry, session start or end, overlap, decision or
733−change to what a work item is blocked by is never kept without its
734−updates, and updates never announce a change that was not made. Each
735−update's ID is derived from its change, so a retried request, or two
736−requests making the same change at once, delivers it once. The one
737−exception is the notice that a work item's blocker closed or merged, which
738−follows the close or merge: it is written right after, once per close or
739−merge. Updates are still a summary: re-read current work item and pull
740−request state before consequential actions.
741−
742−Acknowledged updates are kept as receipts for 30 days. Pending updates stay
743−until acknowledged, including those of a session that ended, so whoever
744−takes over its work can see what it never considered.
+1−1
7878
7979 | | |
8080 | --- | --- |
81−| Work items | [Work items](/guides/work-items/) belong to the workspace, so they stay in the old one, with their numbers. |
81+| Work items | [Work items](/work/work-items/) belong to the workspace, so they stay in the old one, with their numbers. |
8282 | Labels and milestones | They are the workspace's, and stay with it. |
8383 | Workspace secrets and variables | The old workspace's stop reaching the repository; the new workspace's start, if they reach every repository or name this one. |
8484 | Workspace webhooks | The old workspace's stop hearing about the repository; the new one's start. |
+8−8
1212
1313 | | Sent the events of | Managed by | Where |
1414 | --- | --- | --- | --- |
15−| A repository's | That repository, and the [work items](/guides/work-items/) linked to it | People with the Admin [role](/guides/access-and-roles/) on it | The project's **Settings → Webhooks** |
15+| A repository's | That repository, and the [work items](/work/work-items/) linked to it | People with the Admin [role](/guides/access-and-roles/) on it | The project's **Settings → Webhooks** |
1616 | A workspace's | Every repository in the workspace, all its work items, the workspace's own [packages](/guides/packages/), and its [teams](/guides/teams/) | Owners | The workspace's **Settings → Webhooks** |
1717
1818 Seeing a repository's webhooks, and their deliveries, needs Admin too: the
9191 | `workspace.member_joined` | A person became a member of the [workspace](/guides/workspaces/#when-someone-joins). Sent to the workspace's webhooks. `data.workspace_id`, `data.workspace` (its slug), `data.user_id`, `data.username`, `data.role` (`owner` or `member`) and `data.how`: `invitation` (they accepted an invitation), `joined` (they used an invite code that names the workspace) or `created` (they made the workspace and are its first owner). |
9292 | `repo.archived`, `repo.unarchived` | It was made read-only, or writable again. |
9393 | `repo.deleted`, `repo.restored`, `repo.purged` | It was deleted, restored within its 30 days, or removed for good. |
94−| `work_item.labeled`, `work_item.unlabeled`, `pull.labeled`, `pull.unlabeled` | A [label](/guides/labels/) was put on a work item or a pull request, or taken off: one event for each label. `data.number` and `data.label` (`name` and `color`). |
95−| `work_item.milestoned`, `work_item.demilestoned`, `pull.milestoned`, `pull.demilestoned` | A work item or a pull request was put in a [milestone](/guides/milestones/), or taken out of one. `data.milestone` (`number` and `title`). Moving it from one to another is both. |
94+| `work_item.labeled`, `work_item.unlabeled`, `pull.labeled`, `pull.unlabeled` | A [label](/work/labels/) was put on a work item or a pull request, or taken off: one event for each label. `data.number` and `data.label` (`name` and `color`). |
95+| `work_item.milestoned`, `work_item.demilestoned`, `pull.milestoned`, `pull.demilestoned` | A work item or a pull request was put in a [milestone](/work/milestones/), or taken out of one. `data.milestone` (`number` and `title`). Moving it from one to another is both. |
9696 | `pull.base_changed` | The branch a pull request merges into changed. `data.base` names it. See [pull requests into other branches](/guides/base-branches/). |
97−| `work_item.opened`, `work_item.updated`, `work_item.assigned`, `work_item.closed`, `work_item.reopened` | A [work item](/guides/work-items/) changed. `data.workspace`, `data.number`, `data.item_id`, `data.repo_ids` and `data.author` (`id` and `username`); on close, `data.reason`, `data.resolution` when a landing closed it (the `repo` and the `pull` request or default-branch `commit` that landed it), and `data.session` when it was closed in a session; on assignment, `data.assignees` and the newly assigned `data.added`. |
97+| `work_item.opened`, `work_item.updated`, `work_item.assigned`, `work_item.closed`, `work_item.reopened` | A [work item](/work/work-items/) changed. `data.workspace`, `data.number`, `data.item_id`, `data.repo_ids` and `data.author` (`id` and `username`); on close, `data.reason`, `data.resolution` when a landing closed it (the `repo` and the `pull` request or default-branch `commit` that landed it), and `data.session` when it was closed in a session; on assignment, `data.assignees` and the newly assigned `data.added`. |
9898 | `work_item.linked`, `work_item.unlinked` | A repository was linked to a work item in a role, or unlinked. `data.workspace`, `data.number`, `data.item_id`, `data.repo_ids`, `data.repo` (`owner/name`) and `data.role`. |
9999 | `work_item.landed` | A pull request or a default-branch commit landed a work item in one of its repositories. `data.resolution` (the `repo`, and the `pull` or `commit`) and `data.missing`, the targets it has still to land in. When nothing is left, `work_item.closed` follows. |
100100 | `comment.created` | A comment or review on a work item or pull request. |
129129 | `integration.passed` | A pull request's combined state passed in the merge queue: `pull` and `combination`. |
130130 | `decision.recorded` | A [decision record](/guides/why-blame/#decision-records) was kept on a work item or pull request: `decision`, with `number` and `item`. |
131131 | `session.appended` | A pull request's [session](/guides/why-blame/#sessions) grew: a coding agent recorded entries with `record_session`, a session on it recorded some, or g1t noted a merge queue failure. Busy: choose it only if you need it. |
132−| `session.started`, `session.ended` | A [session](/guides/sessions/#sessions) of someone's harness started (not on a repeated start), or ended or timed out. `data.session`, and `data.number` (its pull request, else its work item) and `data.item`. |
133−| `work.claimed`, `work.released`, `work.claim_expired`, `work.handoff_requested` | A [claim](/guides/sessions/#claims) on a work item was made, released, expired or handed off. `data.number` and `data.item` (the work item), `data.claim`; on `work.claimed`, `data.others` (the other active claims) and `data.took_over`; on `work.released`, `data.reason`; on a hand-off, `data.from`, `data.to` and `data.note`. |
134−| `dependency.changed` | What a work item is [blocked by](/guides/sessions/#dependencies) changed, or a blocker closed or had its pull request merged. `data.number` (the blocked work item), `data.blocked_by`, `data.added`, `data.removed`, `data.cleared`, `data.remaining` (blockers still open) and `data.merged_pull`. |
135−| `overlap.detected` | A push made a pull request [change files another open one changes](/guides/sessions/#overlaps). Sent once for each of the two: `data.pull`, `data.other_pull`, `data.files`, `data.item` and `data.other_item`. |
132+| `session.started`, `session.ended` | A [session](/guides/sessions/#record-a-session) of someone's harness started (not on a repeated start), or ended or timed out. `data.session`, and `data.number` (its pull request, else its work item) and `data.item`. |
133+| `work.claimed`, `work.released`, `work.claim_expired`, `work.handoff_requested` | A [claim](/work/claims-and-dependencies/#claims) on a work item was made, released, expired or handed off. `data.number` and `data.item` (the work item), `data.claim`; on `work.claimed`, `data.others` (the other active claims) and `data.took_over`; on `work.released`, `data.reason`; on a hand-off, `data.from`, `data.to` and `data.note`. |
134+| `dependency.changed` | What a work item is [blocked by](/work/claims-and-dependencies/#dependencies) changed, or a blocker closed or had its pull request merged. `data.number` (the blocked work item), `data.blocked_by`, `data.added`, `data.removed`, `data.cleared`, `data.remaining` (blockers still open) and `data.merged_pull`. |
135+| `overlap.detected` | A push made a pull request [change files another open one changes](/work/claims-and-dependencies/#overlaps). Sent once for each of the two: `data.pull`, `data.other_pull`, `data.files`, `data.item` and `data.other_item`. |
136136
137137 [Managing a repository](/guides/managing-repositories/) says what each of
138138 the `repo.` and `branch.` changes does.
+2−2
1111
1212 A pull request's session records how the change was made, entry by entry,
1313 as it happens. Entries come from `record_session` on the pull request, and
14−from any [harness session](/guides/sessions/#sessions) attached to it:
14+from any [harness session](/guides/sessions/#record-a-session) attached to it:
1515
1616 | Kind | What it holds |
1717 | --- | --- |
3131 Outside the workspace only g1t's notes show there, and members see a
3232 prompt or a tool's output only when it is their own; what looks like a
3333 credential is taken out of all of it
34−([Who sees what](/guides/sessions/#who-sees-what)). Still, do not put
34+([Who sees what](/work/sessions/#who-sees-what)). Still, do not put
3535 secrets in one.
3636
3737 ### Recording a session
+0−282
Loading the diff…
+6−7
Loading the diff…
+6−5
Loading the diff…
+1−1
Loading the diff…
+3−3
Loading the diff…
+1−1
Loading the diff…
+8−8
Loading the diff…
+247−0
Loading the diff…
+70−0
Loading the diff…
+254−0
Loading the diff…
+162−0
Loading the diff…
+89−0
Loading the diff…
+150−0
Loading the diff…
+124−0
Loading the diff…
+96−0
Loading the diff…
+93−0
Loading the diff…
+274−0
Loading the diff…
+205−0
Loading the diff…
+0−0

Binary or large file; its contents are not shown.

+1−0
Loading the diff…
+3−2
Loading the diff…
+12−6
Loading the diff…
+1−1
Loading the diff…
+75−24
Loading the diff…
+15−12
Loading the diff…
+1−1
Loading the diff…
+0−232
Loading the diff…
+220−0
Loading the diff…
+15−0
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…
Loading the diff…

Comments

Sign in to comment.