| 1 | --- |
| 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. |
| 4 | --- |
| 5 | |
| 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. |
| 12 | |
| 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. |
| 17 | |
| 18 | ## Record a session |
| 19 | |
| 20 | Start a session when the harness starts, keep it alive while it works, and |
| 21 | end it when it stops. |
| 22 | |
| 23 | 1. **Start** it with `session` `start`, `g1t session start`, or |
| 24 | [`POST /repos/{owner}/{name}/sessions`](/reference/api/sessions/start-session/), |
| 25 | naming the `harness` (`claude_code`, `codex`, `cursor`, `copilot` or |
| 26 | `other`) and the harness's own id for the session as |
| 27 | `harness_session_id`. Starting again with the same id returns the |
| 28 | session already started, so a hook can call it every time without |
| 29 | checking first. Give `item` (the work item's number in the |
| 30 | repository's workspace), `pull` and `branch` when you know them, and a |
| 31 | `title` only if you can name the whole job in a few words (up to 200 |
| 32 | characters): otherwise g1t names it (see |
| 33 | [session titles](/work/session-titles/)). |
| 34 | 2. **Heartbeat** with `session` `update`, `g1t session heartbeat`, or |
| 35 | [`PATCH /repos/{owner}/{name}/sessions/{id}`](/reference/api/sessions/update-session/) |
| 36 | with an empty body. The same call attaches the session to a work item |
| 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. |
| 40 | 3. **Record** what happens with `session` `record`, or |
| 41 | [`POST /repos/{owner}/{name}/sessions/{id}/entries`](/reference/api/sessions/record-session-entries/): |
| 42 | prompts, reasoning, tool calls, notes and the skills it used (`skill`, |
| 43 | the skill's name only), up to 200 a request, and in `touched` what it |
| 44 | touched (see [what a session records](/work/sessions/#what-a-session-records)). |
| 45 | Give each entry a `key`, and recording it again does nothing. |
| 46 | 4. **End** it with `session` `end`, `g1t session end`, or |
| 47 | [`POST /repos/{owner}/{name}/sessions/{id}/end`](/reference/api/sessions/end-session/), |
| 48 | with its `result` when it has one: what it reported when it finished. |
| 49 | |
| 50 | ```sh |
| 51 | curl -X POST https://api.g1t.sh/repos/acme/web/sessions \ |
| 52 | -H "Authorization: Bearer $G1T_TOKEN" \ |
| 53 | -H "Content-Type: application/json" \ |
| 54 | -d '{"harness": "claude_code", "harness_session_id": "5b0c1f9e-3d2a-4e8b-9f61-0c7d2a9e4b13", "item": 12}' |
| 55 | ``` |
| 56 | |
| 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`. |
| 62 | |
| 63 | Entries of a session attached to a pull request show in that pull |
| 64 | request's [session](/guides/why-blame/#sessions), beside what was recorded |
| 65 | on it with `record_session`, so reviewers and why-blame see them. Entries |
| 66 | recorded before the session named its pull request move onto it when it |
| 67 | does. A session never records tool output unless you send it as a |
| 68 | `tool_result` entry. What looks like a credential is taken out of |
| 69 | everything a session records, and only the workspace's members see inside |
| 70 | a session: see [who sees what](/work/sessions/#who-sees-what). |
| 71 | |
| 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). |
| 76 | |
| 77 | ## Work with no work item yet |
| 78 | |
| 79 | Not every session starts from a work item, and most should not end with |
| 80 | one: a question, a look around or a quick fix needs no work item. The |
| 81 | session is the record of that work, and the team sees it in **Live now**, |
| 82 | on **Sessions** and on the project's overview, while it goes: |
| 83 | |
| 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. |
| 89 | 2. **It shows where it works.** Attach its `branch` and, once there is |
| 90 | one, its `pull`: the project's **Live now** groups sessions on no work |
| 91 | item by pull request, then by branch. |
| 92 | 3. **It opens or claims a work item when it becomes a change** others |
| 93 | should know about: a branch to push, a pull request. Look for one first |
| 94 | (`work_item` `list`, `work_item` `list_claims`); if one covers the work, |
| 95 | claim it. Otherwise open one and claim it in one step with `work_item` |
| 96 | `claim` and a `title` instead of a `number` (see [claims](/work/claims-and-dependencies/#claims)), |
| 97 | which attaches the session to it. |
| 98 | |
| 99 | ## Subagents |
| 100 | |
| 101 | A harness that hands part of its work to a subagent (Claude Code's |
| 102 | subagents, a Managed Agents session's threads) records each as a session |
| 103 | of its own under the one that started it: |
| 104 | |
| 105 | - Start it with `parent_id` (the session that started it), `agent_type` |
| 106 | (its kind, such as `Explore`), the `task` it was given in a few words and |
| 107 | the `prompt` (kept up to 4,000 characters). As its `harness_session_id`, |
| 108 | give the parent's, `/agent/` and the subagent's id: starting it again |
| 109 | returns it, in whatever order the harness's hooks arrive. |
| 110 | - It starts on its parent's work item, pull request and branch unless it says |
| 111 | otherwise, so it is listed on them, and its heartbeats keep its parent |
| 112 | active. |
| 113 | - End it with its `result`: its final message, kept up to 8,000 |
| 114 | characters. That is its parent's evidence; what its tools returned is |
| 115 | never recorded. Once ended it stays ended, even when a late hook starts |
| 116 | it again: that only fills in what it says. |
| 117 | - Ending a session ends the subagents it left going (`end_reason` |
| 118 | `parent ended`). |
| 119 | |
| 120 | Subagents see each other. Sibling subagents on one work item are listed in |
| 121 | `get_work` and `session` `list` beside the session that started them, |
| 122 | each holds a claim of its own (claims are told apart by session, so a |
| 123 | sibling's claim is listed in `others`), and when two of them touch the |
| 124 | same file, each is told with `overlap.detected`. The |
| 125 | [Claude Code plugin](/guides/claude-code-plugin/#subagents) does all of |
| 126 | this for Claude Code's subagents. |
| 127 | |
| 128 | ## Start a session on your Anthropic account |
| 129 | |
| 130 | g1t runs no model. Work on a work item happens in your own harness, with |
| 131 | your own Claude, its skills and settings; g1t ties it back to the work |
| 132 | item. To hand a work item to a session from g1t itself (the work item |
| 133 | page's **Start a session**, `g1t work dispatch`, the `session` tool's |
| 134 | `dispatch`, or |
| 135 | [`POST /repos/{owner}/{name}/agent-sessions`](/reference/api/sessions/start-agent-session/), |
| 136 | in the repository the session works in): |
| 137 | |
| 138 | ```sh |
| 139 | curl -X POST https://api.g1t.sh/repos/acme/web/agent-sessions \ |
| 140 | -H "Authorization: Bearer $G1T_TOKEN" \ |
| 141 | -H "Content-Type: application/json" \ |
| 142 | -d '{"item": 12, "mode": "implement", "instruction": "Keep the old greeting behind a flag."}' |
| 143 | ``` |
| 144 | |
| 145 | Give `item`, or `title` and `body` to open a new work item first (with |
| 146 | the repository as its origin), a `mode` |
| 147 | (`plan`, `implement` or `review`) and an optional `instruction`. |
| 148 | |
| 149 | - **With an Anthropic AI provider** in the workspace (an owner adds one |
| 150 | under [**AI**](/guides/ai/)), g1t starts a |
| 151 | [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) |
| 152 | session on that account, with its key, on the model Ask is set to use |
| 153 | (or `claude-opus-5-5`). It runs in a sandbox on Anthropic's side. Its |
| 154 | first step installs the [g1t CLI](/guides/cli/) from g1t, sets git up to |
| 155 | send the token and to commit as you (your username and noreply address), |
| 156 | clones the repository and ties the clone to the session, |
| 157 | so it works the way the work-on-item skill describes: `g1t work |
| 158 | view`, `g1t work claim`, `g1t pr create --item`, `g1t pr checks --watch`. |
| 159 | It works on a branch and a pull request, except in a repository with no |
| 160 | commits yet, where there is nothing to open one against: it pushes the |
| 161 | first version straight to the default branch. To show a screenshot of its |
| 162 | preview in the pull request or a comment, it uploads the image with |
| 163 | [`g1t attach`](/guides/cli/#images-in-descriptions-and-comments) (or |
| 164 | `--attach` on `g1t pr create`, `g1t pr ready` and `g1t pr comment`) and |
| 165 | pastes the Markdown it prints, rather than committing the image. |
| 166 | g1t's MCP server is attached too, for anything the CLI has no command |
| 167 | for. Its sandbox reaches the internet as a CI runner does, and it can |
| 168 | search and read the web (web search and web fetch), for a fact the work |
| 169 | needs from outside g1t or to open its own deploy. Before a headless |
| 170 | browser (Playwright, Puppeteer) opens an https page, it copies the |
| 171 | certificates the sandbox trusts into Chromium's own store, so pages load |
| 172 | with certificate checks on. Both reach g1t with one token: g1t |
| 173 | acting on your behalf, in that repository only, which lasts the session |
| 174 | and is revoked when it ends. What the session does on g1t shows as |
| 175 | **g1t, on behalf of @you**: its comments and reviews, what it closes or |
| 176 | labels, and the work items and pull requests it opens (g1t's, requested |
| 177 | by you); the audit log says "g1t on behalf of you". What it may do is |
| 178 | your role in that repository, never more than Write, with what working on |
| 179 | a work item needs (`repo:read`, `code:write`, `work:write`, |
| 180 | `pull_requests:write`, and reading checks, workflows, deployments and |
| 181 | observability): never settings, members, secrets, webhooks or merging. |
| 182 | The session itself, its claims and its commits stay yours, and its |
| 183 | pushes are yours too: to the repository and to its pull requests' |
| 184 | working copies, under the repository's rules. An approval it gives is |
| 185 | g1t's, so it counts toward required approvals only where agents' |
| 186 | approvals do. The token is kept in a vault on the Anthropic account: the MCP |
| 187 | server's credential, and `G1T_TOKEN`, which the sandbox holds only as a |
| 188 | placeholder that is swapped for the token on its way to g1t. It is never |
| 189 | in the prompt, and the model never sees it. The session has g1t's skills |
| 190 | (work-on-item, coordinate and fix-integration, uploaded to the account |
| 191 | the first time, and as a new version whenever g1t changes them; the |
| 192 | agent uses the version g1t uploaded) next to the account's own custom |
| 193 | skills, at their latest version, up to 20 in all. It may hand parts of the work to copies of itself; each is recorded |
| 194 | as a subagent. |
| 195 | - **Without one**, or with `handoff: true`, nothing starts: you get |
| 196 | `command`, a Claude Code command line to run in your working copy with |
| 197 | the [plugin](/guides/claude-code-plugin/), and `prompt`, what to paste. |
| 198 | The session that starts attaches to the work item. |
| 199 | |
| 200 | The answer has the `session` on g1t, its `session_url`, and |
| 201 | `provider_session_url`, where the Anthropic Console shows it. The Console |
| 202 | keeps sessions in the workspace the key belongs to, and a session does not |
| 203 | say which that is: if the key is not in the account's Default workspace, |
| 204 | set the provider's **Console workspace** under [**AI**](/guides/ai/#anthropic-console-workspace) |
| 205 | so the link opens there. |
| 206 | The session is recorded as harness `claude_managed_agents`: its messages, |
| 207 | the tools it called and with what (never what they returned), the skills |
| 208 | it read, what it touched, and each thread as a subagent with its task and |
| 209 | report. g1t follows it every minute, and at once while its page is open. A |
| 210 | call that waits for someone's approval is declined, since nobody is |
| 211 | watching. When it finishes, its session ends with its last message as its |
| 212 | result. Whoever started it can stop it from its page, and open it on the |
| 213 | Claude Console from there (**Open in Claude Console**); nobody else is |
| 214 | given that link, since the Console shows everything the session was asked |
| 215 | and every tool's output. It runs on your |
| 216 | workspace's key and Anthropic bills the account for it; g1t bills nothing. |
| 217 | |
| 218 | ## Assign g1t, or ask it in the thread |
| 219 | |
| 220 | You can also hand work to g1t from the work item or pull request itself, |
| 221 | the way you would ask a teammate: |
| 222 | |
| 223 | - **Assign the work item to `g1t`**: **Assign to g1t** in the work |
| 224 | item's sidebar, `g1t` among the assignees in |
| 225 | [`update_work_item`](/reference/api/work-items/update-work-item/), or |
| 226 | `g1t work edit 12 --add-assignee g1t`. |
| 227 | - **Mention `@g1t` in a comment** on a work item or a pull request: |
| 228 | "@g1t the button still overlaps on a phone, fix that". On a pull |
| 229 | request, the session carries on with that pull request on its branch. |
| 230 | On a work item, it takes the work item on. |
| 231 | |
| 232 | g1t reacts 👀 to what asked it, the comment or (for an assignment) the |
| 233 | work item, then starts a session on the workspace's Anthropic account, as |
| 234 | the person who asked, with what they wrote as its instruction. Each |
| 235 | session shows in the work item's or pull request's conversation as a card, |
| 236 | where it started, the way a comment or a review does: who it works for, |
| 237 | where it stands, its branch, and its report when it ends, linked to its |
| 238 | page. Not happy with what a session did? Say so with `@g1t` in the same |
| 239 | thread. The next session is told to fix the work on the same branch and |
| 240 | pull request, not start over, and `g1t work view` shows it every |
| 241 | session and pull request so far. If the session you started on that |
| 242 | thread is still going, your comment goes to it instead of starting |
| 243 | another. |
| 244 | |
| 245 | Only the workspace's members can ask g1t; anyone else's `@g1t` is an |
| 246 | ordinary mention. A mention in quoted text or code (`` `@g1t` ``) asks |
| 247 | nothing. g1t answers one thread at most six times an hour. When it cannot |
| 248 | start a session, for instance because the workspace has no Anthropic AI |
| 249 | provider, it says why in the thread. On an update pull request g1t opened, |
| 250 | `@g1t rebase` and the other |
| 251 | [comment commands](/guides/dependency-updates/#comment-commands) still do what |
| 252 | they say. |