| 1 | --- |
| 2 | title: Sessions |
| 3 | description: The work being done, as it happens. Sessions lists every run of people's coding agents, and of g1t's, across the workspace, live; a session's page shows what it worked on, what it touched and everything it recorded. |
| 4 | --- |
| 5 | |
| 6 | A session is one run of a coding agent on a repository: a Claude Code |
| 7 | session, a Codex run, a session g1t started on your Anthropic account. |
| 8 | Work items are what a workspace means to do; sessions are that work being |
| 9 | done. Each is recorded as it goes, tied to the work items and pull |
| 10 | requests it works on, and shown to the team while it runs. |
| 11 | |
| 12 | Not every session starts from a work item. A question, a look around or a |
| 13 | quick fix needs none: the session is the record of that work, named by g1t |
| 14 | from what it does (see [session titles](/work/session-titles/)), and it |
| 15 | claims or files a work item only when it becomes a change others should |
| 16 | know about. |
| 17 | |
| 18 | Nothing here waits on a harness. A harness that crashes, loses its network |
| 19 | or sends the same thing twice does no harm: a session that goes quiet is |
| 20 | read as idle, then ended, the next time anyone looks, and recording the |
| 21 | same thing again is a no-op. What git and g1t record (commits, pull |
| 22 | requests, checks, merges) is the truth; sessions are the account of how it |
| 23 | got there. |
| 24 | |
| 25 | To record your own harness's sessions, see |
| 26 | [recording sessions](/guides/sessions/), or install the |
| 27 | [Claude Code plugin](/guides/claude-code-plugin/), which does it for you. |
| 28 | |
| 29 | ## The Sessions pages |
| 30 | |
| 31 | **Sessions** is the second section of Work's sidebar, at |
| 32 | `g1t.sh/<workspace>/-/work/sessions`. It shows the sessions in every one |
| 33 | of the workspace's repositories you can read. |
| 34 | |
| 35 | **Live now** is what is cooking right now: |
| 36 | |
| 37 | - **Live now**: the active and idle sessions, the most recently heard |
| 38 | from first, and how many are going and idle. Each card shows the |
| 39 | session's title, who it acts for, its harness, its repository and |
| 40 | branch, the work item and pull request it is on, when it was last heard |
| 41 | from, how many subagents it has, and whether it is live or idle. |
| 42 | - **Merge queue**: each repository's merge queue that has something |
| 43 | waiting, as on its [Merge queue](/guides/merge-queue/#the-merge-queue-page) |
| 44 | page. |
| 45 | - **Just landed**: the pull requests merged lately, each with its work |
| 46 | item, who merged it, and **Why**, a link to the session behind it. |
| 47 | - **What happened**: the latest coordination events across the |
| 48 | repositories: claims, sessions starting and ending, overlaps, and what |
| 49 | the merge queue found when it combined changes. |
| 50 | - **Recent**: the sessions that ended lately. |
| 51 | |
| 52 | **Recent**, in the sidebar, is every session in one list, live or ended, |
| 53 | the most recently heard from first. **Yours** is the sessions you ran. |
| 54 | |
| 55 | With nothing going on, Sessions says how to start: choose your client in |
| 56 | the [connection instructions](/guides/bring-your-own-agent/), or run |
| 57 | `g1t work claim <number>` from any harness. |
| 58 | |
| 59 | ### Filters |
| 60 | |
| 61 | Narrow it by repository, person, harness, kind and work item. The address |
| 62 | keeps the filters, so a filtered view can be shared: |
| 63 | |
| 64 | | Filter | In the address | |
| 65 | | --- | --- | |
| 66 | | Repository | `?repo=web` | |
| 67 | | Person | `?person=<username>` | |
| 68 | | Harness | `?harness=codex`: `claude_code`, `claude_managed_agents`, `codex`, `cursor`, `copilot` or `other` | |
| 69 | | Kind | `?kind=hosted` | |
| 70 | | Work item | `?item=12`, shown as **On #12** | |
| 71 | | Every session | `?state=recent` | |
| 72 | |
| 73 | A repository's sessions are Sessions filtered to it, |
| 74 | `g1t.sh/<workspace>/-/work/sessions?repo=<name>`: a repository has no |
| 75 | Sessions page of its own. On a phone the filters are in one **Filters** |
| 76 | sheet. |
| 77 | |
| 78 | ### Kinds of session |
| 79 | |
| 80 | Every kind of session is listed in this one place, and each has its own |
| 81 | row in the sidebar: |
| 82 | |
| 83 | | Kind | Sidebar | Is | |
| 84 | | --- | --- | --- | |
| 85 | | `harness` | **People's harnesses** | A run of someone's own harness (Claude Code, Codex, Cursor, Copilot or another), with its [subagents](/guides/sessions/#subagents) under it. | |
| 86 | | `hosted` | **Started on g1t** | 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](/guides/sessions/#start-a-session-on-your-anthropic-account). | |
| 87 | | `agent` | **g1t's agent** | g1t's own agent at work on a pull request. Only the workspace's members see these. | |
| 88 | | `recorded` | **Recorded on pull requests** | 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`. | |
| 89 | |
| 90 | ### As it happens |
| 91 | |
| 92 | Sessions, Cooking now, the [Board](/work/board/) and a work item's page |
| 93 | follow the work without reloading. Signed in, the page listens for changes |
| 94 | in the workspace's repositories and reads itself again a second after the |
| 95 | last one, never while you type or a dialog is open, and catches up when you |
| 96 | come back to the tab. Since a session going idle sends nothing, Sessions |
| 97 | also checks every 15 seconds while anything is going. Signed out, a page |
| 98 | reads itself again when you come back to it and once a minute. |
| 99 | |
| 100 | ## States |
| 101 | |
| 102 | A session's `state` is worked out from when it was last heard from. Every |
| 103 | heartbeat, update and recorded entry counts: |
| 104 | |
| 105 | | State | Means | |
| 106 | | --- | --- | |
| 107 | | `active` | Heard from in the last 15 minutes. | |
| 108 | | `idle` | Not heard from for 15 minutes. It may still come back. | |
| 109 | | `ended` | Ended by its harness, or not heard from for 30 minutes (`end_reason` `timed_out`). A heartbeat brings a timed-out session back; one its harness ended stays ended. | |
| 110 | |
| 111 | A session its harness left behind, killed or never told to end, can be |
| 112 | ended by hand: **End session** in its menu under Live now (on the project's |
| 113 | overview and on Sessions), or on its page. Whoever runs a session can end |
| 114 | it, and so can anyone with write access to the repository; nobody else |
| 115 | sees the action. It ends with `end_reason` `ended by hand by @name`, its |
| 116 | subagents still going end with it, and its claims stay until they are |
| 117 | released or expire. Like a session that timed out, it comes back the |
| 118 | moment its harness is heard from again, so a harness that was in fact |
| 119 | still running picks up where it was. A session g1t runs on the workspace's |
| 120 | Anthropic account is stopped from its page instead, with **Stop**. |
| 121 | |
| 122 | ## A session's page |
| 123 | |
| 124 | A session's page is `g1t.sh/<workspace>/-/work/sessions/<id>` (its |
| 125 | `ses_…` id), opened from Sessions or from anywhere the session is listed. |
| 126 | It shows: |
| 127 | |
| 128 | - who ran it, in which harness and on which model, its state, when it |
| 129 | started and how long it ran, when it was last heard from or why it |
| 130 | ended, its repository, branch and head commit; |
| 131 | - the work items and pull requests it and its subagents worked on, each |
| 132 | saying how it was tied (see [what a session records](#what-a-session-records)); |
| 133 | - **What it reported**, when it ended with a result; |
| 134 | - its **subagents** as a tree you open one at a time, each with its kind, |
| 135 | the task it was given, what it touched and what it reported. A |
| 136 | subagent's own page links back to the session that started it; |
| 137 | - the **skills** it used, **what it touched** (files, commits, branches, |
| 138 | pull requests), and its commits and pull requests; |
| 139 | - the [coordination updates](/work/claims-and-dependencies/#coordination-updates) |
| 140 | it has not acknowledged yet; |
| 141 | - **What it recorded**, as it records it: its prompt folded, its messages |
| 142 | formatted as they were written, and the tool calls between them a line |
| 143 | each (a command as code, a file by its path, a g1t tool by what it did, |
| 144 | such as *work item · claim*), more than three in a row folded into one |
| 145 | line that opens to them. A long command and what a tool gave back open |
| 146 | under its line. |
| 147 | |
| 148 | Whoever runs it, and anyone with write access to the repository, can |
| 149 | **Rename** it there, which pins the title; see |
| 150 | [session titles](/work/session-titles/#pin-a-title). |
| 151 | |
| 152 | ## Sessions elsewhere on the site |
| 153 | |
| 154 | Sessions show where the work is, as it happens: |
| 155 | |
| 156 | - **A work item's Work panel**, at the top of its sidebar: its claims, the |
| 157 | sessions on it (up to five, then a link to Sessions filtered to it), what |
| 158 | it is blocked by and what it blocks. See |
| 159 | [claims and dependencies](/work/claims-and-dependencies/). |
| 160 | - **A work item's and a pull request's sessions**: every session tied to |
| 161 | it in any way, in any of the workspace's repositories, with its |
| 162 | subagents under it. A pull request's **Session** tab, |
| 163 | `g1t.sh/<owner>/<repo>/pull/<number>/session`, is what was recorded on |
| 164 | it. |
| 165 | - **Cooking now**, above the [Work list](/work/#cooking-now): the live |
| 166 | sessions, a strip of cards. |
| 167 | - **A project's overview**: **Live now**, the people and coding agents |
| 168 | working on that repository, grouped by work item, then by pull request |
| 169 | or branch. See [the overview](/guides/projects/#the-overview). |
| 170 | |
| 171 | ## What a session records |
| 172 | |
| 173 | A session records its prompts, its messages, the tool calls it makes, |
| 174 | notes, the skills it uses, and its result when it ends. It never records |
| 175 | what a tool gave back unless its harness sends it. It also says what it |
| 176 | touched, each kept once: |
| 177 | |
| 178 | | `kind` | `value` | |
| 179 | | --- | --- | |
| 180 | | `file` | A file it wrote, from the repository's root. | |
| 181 | | `commit` | A commit it made. | |
| 182 | | `branch` | A branch it made or pushed. | |
| 183 | | `pull` | A pull request it opened, by number. | |
| 184 | | `item` | A work item it named or claimed, by its number in the workspace. | |
| 185 | |
| 186 | From these and the rest of what it records, g1t ties the session to the |
| 187 | work items and pull requests it worked on, each in as many ways as it was |
| 188 | (`via` in the session's `links`): |
| 189 | |
| 190 | | `via` | When | |
| 191 | | --- | --- | |
| 192 | | `attached` | It said it is on it, starting or updating. | |
| 193 | | `claim` | It claimed the work item. | |
| 194 | | `opened` | It opened the pull request. | |
| 195 | | `branch` | It pushed the pull request's branch, also when the pull request is opened later. | |
| 196 | | `commit` | It made the pull request's head commit. | |
| 197 | | `trailer` | A commit pushed to the pull request's branch names it in a `G1t-Session: ses_…` trailer. | |
| 198 | | `ref` | Its prompt, its task, its result or a subagent's names it as `#12`. | |
| 199 | |
| 200 | A session's links cover its subagents too, and the work item and pull |
| 201 | request pages list every session tied to them with its subagents. Put the |
| 202 | trailer on the commits a session makes and they lead back to it: |
| 203 | |
| 204 | ```sh |
| 205 | git commit --trailer "G1t-Session: $G1T_SESSION" |
| 206 | ``` |
| 207 | |
| 208 | A work item a session closes, or a repository it lands on one, says so on |
| 209 | its timeline, **via session** and a link to it (see |
| 210 | [who closed it, and how](/work/closing/#who-closed-it-and-how)). When two |
| 211 | active sessions touch the same file, each is told; see |
| 212 | [overlaps](/work/claims-and-dependencies/#overlaps). |
| 213 | |
| 214 | Entries of a session attached to a pull request show in that pull |
| 215 | request's [session](/guides/why-blame/#sessions) too, so reviewers and |
| 216 | why-blame see them. |
| 217 | |
| 218 | ## Who sees what |
| 219 | |
| 220 | A session records someone's own work as it happens, so g1t shows it by who |
| 221 | is looking, on the site, the API, MCP and the CLI alike. |
| 222 | |
| 223 | | Who | Sees | |
| 224 | | --- | --- | |
| 225 | | Whoever ran it | All of it: its prompts, tool calls, what it touched and reported, its pending updates. | |
| 226 | | 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. | |
| 227 | | 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. | |
| 228 | |
| 229 | g1t's own agent's sessions are listed only for members. |
| 230 | |
| 231 | Before anything is kept, g1t takes out what looks like a credential |
| 232 | (`[redacted]`): every token format [secret protection](/guides/security/secret-protection/) |
| 233 | knows, any key or token by its issuer's prefix, `NAME_TOKEN=value`, |
| 234 | `password: value` and the like, `--token`/`--password` flags, `Bearer` and |
| 235 | `Authorization` headers, a URL's user and password and its signed query |
| 236 | parameters, JWTs, private keys, and long random-looking strings. What was |
| 237 | recorded before this is hidden the same way as it is read. The |
| 238 | [Claude Code plugin](/guides/claude-code-plugin/) does the same before |
| 239 | anything leaves your machine. It is a safety net, not a vault: keep |
| 240 | secrets out of prompts and command lines. |
| 241 | |
| 242 | ## From the API, MCP and the CLI |
| 243 | |
| 244 | The same list is in the API, MCP and the CLI: |
| 245 | [`GET /workspaces/{workspace}/sessions`](/reference/api/sessions/list-workspace-sessions/) |
| 246 | by `state` (`live`, `recent` or `ended`), `kind` (`harness`, `hosted`, |
| 247 | `agent` or `recorded`), `harness`, `person`, `repo`, `item`, `subagents` |
| 248 | and `limit`, which returns the `sessions`, each repository's `queue`, what |
| 249 | `landed` and the `repos` it covers; |
| 250 | [`GET /workspaces/{workspace}/sessions/{id}`](/reference/api/sessions/get-workspace-session/) |
| 251 | for one session, with its `repo`. Over MCP, the `session` tool's `list` |
| 252 | takes `workspace` instead of `repo`, and `get` takes `workspace` and `id`. |
| 253 | From the CLI: |
| 254 | |
| 255 | ```sh |
| 256 | g1t session list --workspace # this repository's workspace |
| 257 | g1t session list --workspace acme --in web # one repository of it |
| 258 | g1t session list --workspace --harness codex --state active |
| 259 | g1t session view ses_01m4b2c3d4e5f6g7h8j9k0m1n2 |
| 260 | ``` |
| 261 | |
| 262 | `--workspace` takes a slug, or none for the current repository's |
| 263 | workspace; `--harness`, `--person`, `--in NAME` (a repository of it), |
| 264 | `--state` (active or idle: what is going now; ended), `--item` and |
| 265 | `--subagents` narrow it. |
| 266 | |
| 267 | One repository's sessions are |
| 268 | [`GET /repos/{owner}/{name}/sessions`](/reference/api/sessions/list-sessions/), |
| 269 | or `session` `list` with `repo`, by `state`, `item` or `pull` (any session |
| 270 | tied to it), or `path` (those that touched a file, or any under a folder |
| 271 | ending in `/`); subagents are listed too with `subagents=true`. A session |
| 272 | in the list with no `title` carries `first_prompt`: the first 300 |
| 273 | characters of the first prompt it recorded. Reading sessions needs |
| 274 | `pull_requests:read` with an access token. |