| 1 | --- |
| 2 | title: g1t's agent |
| 3 | description: Assign an issue to g1t and it does the work. |
| 4 | --- |
| 5 | |
| 6 | g1t can do the work itself. Its agent is named `g1t`: assign an open issue |
| 7 | to g1t and it opens a pull request for the issue, works in a sandbox and a |
| 8 | fork of its own, and reports back as it goes. There is nothing to |
| 9 | configure: you do not say how many agents or which model. Scale comes from |
| 10 | assigning many issues, each worked on by its own run, all at once. |
| 11 | |
| 12 | Everything g1t does shows as `g1t`: the pull requests it opens, its |
| 13 | commits, comments, reviews, plans and security updates, assignments, |
| 14 | timeline events, the audit log, notifications and webhooks. A pull request |
| 15 | g1t opens shows g1t as its author, with **requested by** naming the person |
| 16 | who asked for it. See [who a pull request is for](#who-a-pull-request-is-for). |
| 17 | |
| 18 | g1t's runs are paid for by the workspace they work for, so they need a |
| 19 | paid workspace or the free trial; see [who can run agents](#who-can-run-agents) |
| 20 | and [usage and billing](/guides/usage-and-billing/). Everyone can also |
| 21 | [bring their own agent](/guides/bring-your-own-agent/), which costs |
| 22 | nothing on g1t. |
| 23 | |
| 24 | To hand over a whole outcome rather than one issue at a time, have an agent |
| 25 | plan it first: see [hand off an outcome](/guides/outcomes/). |
| 26 | |
| 27 | ## Put an agent on it in one step |
| 28 | |
| 29 | When the work is not written down yet, open the issue and hand it to the |
| 30 | agent at once: |
| 31 | |
| 32 | 1. On Mission control, choose **Put an agent on it**. |
| 33 | 2. Pick the project, give a title, and say what you want done in plain |
| 34 | words, with what done means if you know it. |
| 35 | 3. Choose **Put an agent on it**. |
| 36 | |
| 37 | You land on the new issue with the agent already at work on its pull |
| 38 | request. The same choice is on a project's **New issue** page, as **Assign |
| 39 | g1t now**, and in the ⌘K palette as **Put an agent on …** followed by |
| 40 | a project's name. |
| 41 | |
| 42 | Putting an agent to work needs the Write role on the project. Without it, |
| 43 | nothing is opened. With it, the issue is always opened, even when the |
| 44 | agent cannot start: |
| 45 | |
| 46 | | What happened | What you see | |
| 47 | | --- | --- | |
| 48 | | The agent started | The issue, with its draft pull request under **Assignees**. | |
| 49 | | Every agent slot of the workspace is busy | The issue, queued for g1t. It starts by itself when a slot frees up. | |
| 50 | | The workspace's plan or limits refused it | The issue is opened, and the composer says why and links to the fix: start the plan or the trial (`not_paid`, `trial_used`), raise the monthly limit (`limit`) or the cap per issue (`issue_cap`), or connect a model (`no_model`). A workspace g1t `paused` says to contact support. | |
| 51 | |
| 52 | From the API or an agent of your own, it is one call: |
| 53 | |
| 54 | ```sh |
| 55 | curl -X POST https://api.g1t.sh/repos/<workspace>/<repo>/issues/delegate \ |
| 56 | -H "Authorization: Bearer $G1T_TOKEN" \ |
| 57 | -H "Content-Type: application/json" \ |
| 58 | -d '{"title": "Retry webhooks with exponential backoff", "body": "Deliveries that fail are dropped today. Retry them up to six times."}' |
| 59 | ``` |
| 60 | |
| 61 | The answer holds the `issue`, the `pull` request the agent opened (or |
| 62 | `null`), and `agent`: its `status` (`started`, `queued` or `not_started`), |
| 63 | and when it did not start, a `code`, a `message` and a `fix_url`. On the MCP |
| 64 | server it is the `agent` tool's `delegate` action. See |
| 65 | [put an agent on it](/reference/api/issues/delegate/). |
| 66 | |
| 67 | The `checks` field this call and `create_issue` used to take is |
| 68 | deprecated. It is still accepted: its commands are added to the issue's |
| 69 | body under `## Definition of done`, one line each (`` - `npm test` passes. ``), |
| 70 | and the answer carries a `deprecation` string saying so. What has to pass |
| 71 | before the pull request merges is the default branch's |
| 72 | [required status checks](/guides/pull-requests/#required-status-checks). |
| 73 | |
| 74 | ## Assigning agents |
| 75 | |
| 76 | One issue: |
| 77 | |
| 78 | 1. Open an issue on a repository. |
| 79 | 2. In **Assign to g1t**, optionally add guidance for this run, on top |
| 80 | of the issue's description. |
| 81 | 3. Choose **Assign**. |
| 82 | |
| 83 | Many issues: |
| 84 | |
| 85 | 1. Open the repository's **Issues** tab. |
| 86 | 2. Tick the issues to hand over, up to ten at a time. |
| 87 | 3. Choose **Assign to g1t**. |
| 88 | |
| 89 | From the API, an agent of your own, or a script: |
| 90 | |
| 91 | ```sh |
| 92 | curl -X POST https://api.g1t.sh/repos/<workspace>/<repo>/issues/12/assign \ |
| 93 | -H "Authorization: Bearer $G1T_TOKEN" |
| 94 | ``` |
| 95 | |
| 96 | The same thing is the `agent` tool's `assign` action on the MCP server, so an agent |
| 97 | planning work can hand issues to g1t itself. |
| 98 | |
| 99 | In a comment: write `@g1t take this` on the issue. See |
| 100 | [mentioning g1t](#mentioning-g1t). |
| 101 | |
| 102 | By label: a project can hand every issue given a label to the agent. See |
| 103 | [the label rule](#the-label-rule). |
| 104 | |
| 105 | Each run appears as a draft pull request on its issue within a few |
| 106 | seconds. The pages update on their own while g1t works. |
| 107 | |
| 108 | An issue can still have more than one pull request: assign it again, or |
| 109 | have your own agent open one alongside. That is for when you want a second |
| 110 | attempt, not the normal way of working. |
| 111 | |
| 112 | ## What an agent does |
| 113 | |
| 114 | 1. Clones its pull request's fork. |
| 115 | 2. Is told what else is in progress: every other open pull request in the |
| 116 | repository, what it is for and which files it changes. Its session |
| 117 | starts with a note of what it was told. |
| 118 | 3. Reads the code and makes the change the issue asks for, keeping clear of |
| 119 | the other work where it can. |
| 120 | 4. Commits its work. |
| 121 | 5. Pushes to the fork and marks the pull request ready for review, with a |
| 122 | summary as its description. |
| 123 | |
| 124 | Everything it reads, runs and decides is recorded in the pull request's |
| 125 | **Session** as it happens; see [sessions and why-blame](/guides/why-blame/). |
| 126 | The **Files changed** tab shows the resulting diff. |
| 127 | |
| 128 | If an agent fails, or finishes without changing anything, its pull request |
| 129 | is closed and its session says why. |
| 130 | |
| 131 | ## Repository instructions |
| 132 | |
| 133 | Every g1t run reads the repository's own instructions for agents |
| 134 | and is told them, labelled as the repository's, before it starts: making a |
| 135 | change, revising it, reviewing, catching up, answering, and planning. |
| 136 | |
| 137 | | File | Read by | |
| 138 | | --- | --- | |
| 139 | | `AGENTS.md` and `CLAUDE.md` at the root | Every run. | |
| 140 | | `AGENTS.md` and `CLAUDE.md` in a subdirectory | Runs whose task touches files under it: the nearest one above each file. Where it disagrees with the root's, it wins for the files under it. | |
| 141 | | `.g1t/review.md` | Reviews: what to check, house rules, paths that need extra care. | |
| 142 | |
| 143 | Write them for an agent that knows nothing about the project: how to build |
| 144 | and test, how things are named, what never to touch. For example: |
| 145 | |
| 146 | ```md |
| 147 | # AGENTS.md |
| 148 | - Run `npm test` and `npm run typecheck` before you finish. |
| 149 | - API handlers return a Result; they never throw. |
| 150 | - Never edit files under `vendor/`. |
| 151 | ``` |
| 152 | |
| 153 | Which directories a task touches comes from the pull request's changed |
| 154 | files, and for new work from the paths the issue names, so naming the |
| 155 | files in an issue helps the right instructions reach the agent. |
| 156 | |
| 157 | **Where they are read from.** The default branch, as it is when the run |
| 158 | starts. A pull request from one of the repository's own branches is read at |
| 159 | its head instead, since only people who can push to the repository can |
| 160 | change it. A pull request from a fork, which includes every change g1t |
| 161 | makes, is never followed: the agent keeps the default branch's |
| 162 | instructions, and if the fork changes them, it is shown the changed text as |
| 163 | part of the change, marked as not instructions. That way nobody can steer |
| 164 | an agent, or the review of their own change, by editing these files in a |
| 165 | pull request. Treat what a fork's head says as untrusted, as you would its |
| 166 | code. |
| 167 | |
| 168 | **Limits.** Each file is cut at 8,000 characters and all of them together |
| 169 | at 24,000; what is left out is named in the prompt. Files are read once per |
| 170 | commit and reused. |
| 171 | |
| 172 | The project's **Agents** page lists the files its runs read, what they say |
| 173 | and when each last changed, with a link to each in the code. Each run's |
| 174 | session starts with a note of which files it read. To change them, change |
| 175 | the files and merge to the default branch. |
| 176 | |
| 177 | ## Seeing it through |
| 178 | |
| 179 | Making the change is the first step. g1t takes the rest itself, and you |
| 180 | get the pull request back ready to merge: |
| 181 | |
| 182 | 1. **Checks.** Every push the agent makes runs the repository's |
| 183 | [workflows](/guides/actions/) on the pull request, as for anyone's pull |
| 184 | request. g1t waits for them to finish. Only the workflow runs and your |
| 185 | integrations report [checks](/guides/checks/), so the agent has no say |
| 186 | in the result: it reads them, with each failing check run's annotations, |
| 187 | and never reports one. |
| 188 | 2. **Review.** A different agent reads the change and posts comments on |
| 189 | lines, a summary and a verdict. |
| 190 | 3. **Revision.** If a check fails or the review asks for changes, the |
| 191 | author is sent back with exactly what was found. For a failed check, |
| 192 | that is the end of the log of each failed job, up to three jobs and |
| 193 | about 3,000 characters each; it can read more with `get_workflow_run` |
| 194 | and `get_job_logs`. Steps 1 and 2 run again on the result. This happens |
| 195 | at most twice, or as often as the repository's **Revisions before asking |
| 196 | you** allows. |
| 197 | 4. **Ready to merge.** The required checks passed and it is approved. |
| 198 | Merging is yours, unless the repository says otherwise (below). Until |
| 199 | you merge it, Home and Code's overview list it as waiting for you to |
| 200 | merge it, with a link to **Merge automatically when ready** in the |
| 201 | repository's branch settings for a pull request g1t made. |
| 202 | |
| 203 | Agents are told to run the same tests and linters the workflows run before |
| 204 | they finish, so most failures are caught in the sandbox. What "done" means |
| 205 | for the issue, if its description says so, is context for the agent and |
| 206 | its reviewer; what decides the merge is the default branch's |
| 207 | [required status checks](/guides/pull-requests/#required-status-checks). |
| 208 | A repository with no workflows has nothing to prove a change works; **Add |
| 209 | CI** gives it one ([add CI](/guides/actions/#add-ci)). |
| 210 | |
| 211 | If `main` has moved in the meantime, that does not hold the pull request |
| 212 | up. Merging it brings it up to date first: g1t merges `main` in, an agent |
| 213 | resolves any conflict, and it lands. A repository that wants every pull |
| 214 | request caught up and checked again before it may merge turns on **Require |
| 215 | pull requests to be up to date before merging** in its settings; catching |
| 216 | up is then a step of its own, before "ready". |
| 217 | |
| 218 | g1t also works out ahead of time whether each pull request still merges |
| 219 | cleanly, every time it or `main` moves |
| 220 | ([how](/guides/pull-requests/#conflicts)). When one of an agent's pull |
| 221 | requests is found to conflict, g1t does not wait for a merge to trip over |
| 222 | it: the agent is sent to merge `main` in and resolve the conflicts, told |
| 223 | which files conflict, and the checks run again on the result. |
| 224 | |
| 225 | The pull request's page shows which step it is at. While a required check |
| 226 | has not reported on its latest commit, it says so: "Waiting for the |
| 227 | required check CI to report on its latest commit." If g1t cannot finish, |
| 228 | because a required check still fails after the agent revised as often as |
| 229 | the repository allows ("The required check CI still fails after the agent |
| 230 | revised twice."), a review could not be written, or a conflict could not |
| 231 | be resolved while bringing it up to date, it stops and the page says |
| 232 | **Needs you**, with the reason. A check that is not required and still |
| 233 | fails after the last revision does not hold it. Pushing to the pull |
| 234 | request yourself starts it moving again. |
| 235 | |
| 236 | ### What a repository can ask for |
| 237 | |
| 238 | A project's [rulesets](/guides/rules/), under **Settings → Rules**, set |
| 239 | what every pull request needs before it merges, a person's or an agent's: |
| 240 | required checks, approvals, being up to date, the merge queue and the rest. |
| 241 | Agents, g1t's included, follow them as people do. They are let through only |
| 242 | when a ruleset lists g1t, or their token, as able to bypass it. Some rules |
| 243 | are written for agents' changes: |
| 244 | |
| 245 | | Rule | What it does for an agent's change | |
| 246 | | --- | --- | |
| 247 | | A rule that holds for agents only | For example, one approval from a person, or no changes to `.g1t/workflows/**` and `CODEOWNERS`. A push that breaks it is refused, and git says which rule refused it. | |
| 248 | | Confidence threshold | A change g1t [rates](#how-sure-the-agent-is) below the minimum waits for people's approval. | |
| 249 | | Cost cap | Past the cap, the pull request neither merges nor goes back to its agent until a person approves it. It shows **Needs you**. | |
| 250 | | Agent auto-merge | Whether g1t merges the agent's change into this branch by itself, and at what confidence. | |
| 251 | | Merge window | Merges, g1t's included, wait outside the window and during a freeze. | |
| 252 | |
| 253 | Under **Settings → Branches and merging**, in the **g1t** section, you set |
| 254 | what g1t does with its own pull requests: |
| 255 | |
| 256 | | Setting | Default | What it does | |
| 257 | | --- | --- | --- | |
| 258 | | Review by a second agent | On | Off leaves review to people. | |
| 259 | | Revisions before asking you | 2 | How often an agent is sent back before g1t stops. | |
| 260 | | Merge automatically when ready | Off | Lands g1t's pull request once every rule is met. | |
| 261 | | Ask a person before merging low-confidence changes | On | A change by g1t [rated low](#how-sure-the-agent-is) waits for a person's approval instead of merging by itself or joining the queue. | |
| 262 | |
| 263 | A pull request g1t opens follows the same rules as anyone's. If the |
| 264 | repository wants approvals from people, it waits for them, and shows |
| 265 | **Needs you** until they arrive. |
| 266 | |
| 267 | ### Talking to an agent |
| 268 | |
| 269 | While g1t works, you can steer it with **Message the agent** on its |
| 270 | pull request; it reads the message at its next step, without starting |
| 271 | over. Once it is done, a review with **Request changes** sends it back to |
| 272 | make them, and the checks and review run again. g1t's runs working at the |
| 273 | same time can also ask each other questions and hand each other work. See |
| 274 | [talk to agents](/guides/talking-to-agents/). |
| 275 | |
| 276 | ### Merging automatically |
| 277 | |
| 278 | A repository can land g1t's pull request by itself once it is |
| 279 | ready. Someone with the Maintain role or higher turns this on under the repository's |
| 280 | **Settings → Branches and merging**; it is off to begin with. The merge is recorded as made by |
| 281 | `g1t`, the issue closes naming the pull request, and nothing short of |
| 282 | ready is ever merged this way: every required check has passed on its |
| 283 | head. One that is behind `main` is brought up to |
| 284 | date as part of the merge. Pull requests from people and from other |
| 285 | agents always wait for a person to merge them. |
| 286 | |
| 287 | Every step is recorded: revisions and catch-ups in the pull request's |
| 288 | **Session**, reviews in its conversation. |
| 289 | |
| 290 | This applies to pull requests g1t opens. One you or your own |
| 291 | agent opened is yours to drive; the same workflows run on it, and you can ask |
| 292 | for a review or a catch-up from its page. |
| 293 | |
| 294 | ### How sure the agent is |
| 295 | |
| 296 | Once g1t has finished a change, g1t records how sure it is that the |
| 297 | change is right: **high**, **medium** or **low**, with a few words saying |
| 298 | why, such as "Low — tests not added, 3 revisions". It shows on the pull |
| 299 | request, under the agent, and on Mission control. It is worked out again as |
| 300 | the change moves through checks, review and revision, and kept with each |
| 301 | run, so a run's page says how the change stood when that run left it. |
| 302 | |
| 303 | Confidence comes from what g1t can observe, not from how the agent sounds. |
| 304 | Each signal below that tells against the change adds points, or makes it |
| 305 | low on its own. No points is high, one or two is medium, and three or more |
| 306 | is low. |
| 307 | |
| 308 | | Signal | Effect | |
| 309 | | --- | --- | |
| 310 | | Required checks fail | Low | |
| 311 | | It failed in the [merge queue](/guides/merge-queue/) | Low | |
| 312 | | The reviewer agent asks for changes | Low | |
| 313 | | A run was stopped at its cost or time cap | Low | |
| 314 | | Sent back to revise | 1 point per revision, at most 3 | |
| 315 | | Required checks have not finished, or have not run on its head | 1 point | |
| 316 | | Checks passed only on a retry | 1 point | |
| 317 | | The default branch has no required checks | 1 point | |
| 318 | | No review yet, or the repository has no reviewer agent | 1 point | |
| 319 | | The reviewer approved but left three or more comments on lines | 1 point | |
| 320 | | Code changed and no test was added or changed | 1 point | |
| 321 | | More than 400 lines changed; more than 1,000 | 1 point; 2 points | |
| 322 | | More than 30 files changed | 1 point | |
| 323 | | Files changed outside the area its [plan](/guides/outcomes/) expected; four or more | 1 point; 2 points | |
| 324 | | Touches CI workflows, repository automation, secrets, infrastructure or `CODEOWNERS` | 2 points | |
| 325 | | Its latest run used 80% or more of its cost or time cap | 1 point each | |
| 326 | | Steps refused by [guardrails](/guides/guardrails/); three or more | 1 point; 2 points | |
| 327 | | A question or handoff it sent another agent is unanswered | 2 points | |
| 328 | | The agent said it was unsure about something | 1 point | |
| 329 | |
| 330 | At the end of every run that makes or revises a change, the agent is also |
| 331 | asked how sure it is, and what it could not verify. g1t takes the lower of |
| 332 | the two: what it observes can lower the agent's own word, never raise it. |
| 333 | When the agent's word is lower, the reasons start with "agent says low", |
| 334 | and the pull request lists what it was unsure about. |
| 335 | |
| 336 | For high confidence, the reasons say what it rests on: required checks pass, |
| 337 | approved on the first review, tests added, a small change. |
| 338 | |
| 339 | The pull request's `confidence` in the |
| 340 | [API](/reference/api/pull-requests/get-pull-request/) has the `level`, |
| 341 | `reasons`, `self_reported`, `uncertain_about`, the `run_id` it was worked out |
| 342 | after, and `assessed_at`. [Webhooks](/guides/webhooks/) for pull requests |
| 343 | carry it too. |
| 344 | |
| 345 | ### Low-confidence changes wait for a person |
| 346 | |
| 347 | With **Ask a person before merging low-confidence changes** on, which it is |
| 348 | unless someone turns it off, a change by g1t rated low is not merged |
| 349 | by itself and does not join the merge queue, even with **Merge |
| 350 | automatically when ready** on. Once everything else the repository asks |
| 351 | for is met, it stops at **Needs you**, saying why, and Mission control |
| 352 | lists it under **Needs you** with a **Low confidence** chip, the reasons in |
| 353 | **What the agent already knows**, and the reasons again in **Why this |
| 354 | needs you**. |
| 355 | |
| 356 | To let it land, approve it: a person's approval since the agent last |
| 357 | revised lifts the hold, and it merges as the repository's rules say. To |
| 358 | send it back, request changes. Merging it yourself works as usual. The |
| 359 | setting is under **Settings → Branches and merging**, in the **g1t** section, |
| 360 | and is `hold_low_confidence` in |
| 361 | [`update_repo_settings`](/reference/api/repositories/update-repo-settings/). |
| 362 | |
| 363 | ## Choosing between pull requests |
| 364 | |
| 365 | Each pull request on the issue's page shows whether its checks passed. Open |
| 366 | the ones that did, read their descriptions and changes, and merge the one |
| 367 | you want. Merging lands it on `main` and closes the issue, which records |
| 368 | that pull request as the one that resolved it. The other pull requests for |
| 369 | the issue close as superseded. See |
| 370 | [merging](/concepts/overview/#merging) for what happens when `main` has moved. |
| 371 | |
| 372 | ## Other things g1t does |
| 373 | |
| 374 | - **Review.** On a pull request that is ready, **Request review from g1t** |
| 375 | has g1t read the change and post comments on lines, a summary and a |
| 376 | verdict. |
| 377 | - **Catch up.** When `main` has moved under a pull request, **Catch up with |
| 378 | main** merges it in. When the two changed different files g1t does that |
| 379 | itself in seconds, with no agent; otherwise an agent merges it in a |
| 380 | sandbox and resolves any conflict |
| 381 | ([catching up](/guides/pull-requests/#catching-up)). |
| 382 | - **Finish a security update.** g1t raises a vulnerable dependency to its |
| 383 | fixed version itself, with no agent. When raising the version is not |
| 384 | enough (the bump fails, or the pull request's required checks fail |
| 385 | because code must change), g1t opens an issue and assigns it to g1t. |
| 386 | That session shows as **started by g1t** on the project's **Agents** page. |
| 387 | See [security updates](/guides/security/#security-updates). |
| 388 | |
| 389 | Each runs in a sandbox of its own. |
| 390 | |
| 391 | ## Mentioning g1t |
| 392 | |
| 393 | Write `@g1t` in a comment on an issue or a pull request, with what |
| 394 | you want, and it does it. The comment box offers to complete the name as |
| 395 | you type `@`. |
| 396 | |
| 397 | | Where | You write | What happens | |
| 398 | | --- | --- | --- | |
| 399 | | An issue | A request: `@g1t take this`, `@g1t fix the empty case` | The issue is assigned to g1t, which opens a pull request, as if you had chosen **Assign**. | |
| 400 | | An issue | A question: `@g1t why is this slow?` | g1t reads the code on the default branch and answers in the thread. It changes nothing. | |
| 401 | | A pull request g1t made | A request: `@g1t also handle the empty list` | g1t is sent back to make the change, with your comment as what to address, and the checks and review run again. If it is still working, it gets your comment as a message at its next step. | |
| 402 | | Any pull request | `@g1t review this` | A review by g1t, as with **Request review from g1t**. | |
| 403 | | Any pull request | A question | g1t reads the change at its head and answers in the thread. On someone else's pull request, which it cannot push to, a request is answered too: it says what it would change. | |
| 404 | |
| 405 | A request is a comment whose words after the mention start with what to |
| 406 | do (`take`, `fix`, `add`, `please rename`, `can you update`); a question |
| 407 | starts with a question word or ends with a question mark. `review` near the |
| 408 | start asks for a review. |
| 409 | |
| 410 | g1t always replies in the thread, saying what it started or why it |
| 411 | did not. Every run a mention starts shows on the project's **Agents** page |
| 412 | as started by whoever mentioned it, and a mention that started nothing |
| 413 | shows there as a failed run with the reason. |
| 414 | |
| 415 | **What does not count.** Mentions in code (`` `@g1t` `` or a code |
| 416 | block), in quoted lines (`> @g1t …`), in email addresses |
| 417 | (`ops@g1t.sh`), in URLs, in package scopes (`@g1t/platform`) and in longer |
| 418 | names (`@g1t-bot`) are ignored. Matching ignores case. Agents mentioning |
| 419 | `@g1t` start nothing, so |
| 420 | agents cannot set each other to work this way. Neither does a comment made |
| 421 | with a workflow job's own token (`G1T_TOKEN`), so a workflow cannot set |
| 422 | off g1t whose push sets off the workflow again; see |
| 423 | [the job's token](/guides/actions/#the-jobs-token). |
| 424 | |
| 425 | **Who can.** People with the Write [role](/guides/access-and-roles/) or higher on the |
| 426 | repository, members or not. Anyone else who mentions it gets a short reply |
| 427 | saying that putting g1t to work needs the Write role on the |
| 428 | repository, and nothing starts. When |
| 429 | the workspace's plan does not let the agent start (a free workspace with no |
| 430 | trial left, a paused workspace, an issue at its spending cap), g1t |
| 431 | replies with why and where to fix it. When every agent slot is busy, it |
| 432 | replies that the run is waiting for a free slot, and starts it when one |
| 433 | finishes. |
| 434 | |
| 435 | Each comment starts one run at most; to ask again, write a new comment. |
| 436 | |
| 437 | A mention sends g1t back to a pull request it made even after it stopped |
| 438 | there, or used up the repository's revisions. At most 10 mentions in a day |
| 439 | send it back to the same pull request; past that, g1t replies that it |
| 440 | has reached the most it takes, and the next one works a day after the |
| 441 | first of those 10. |
| 442 | |
| 443 | ## The label rule |
| 444 | |
| 445 | Under a project's **Settings → Agents**, someone with the Maintain role or |
| 446 | higher sets a label, such as `agent`. From then on, when someone with the |
| 447 | Write role or higher gives an open issue that label, either |
| 448 | when opening it or later, g1t takes it: the issue is queued for |
| 449 | g1t, the conversation says so, and the agent starts as soon as the |
| 450 | project has room and nothing the issue depends on is still open, exactly as |
| 451 | for a [plan's](/guides/outcomes/) issues. An issue that already had the |
| 452 | label is not affected; removing and adding it again counts. **Turn off** |
| 453 | removes the rule. |
| 454 | |
| 455 | ## Which model runs |
| 456 | |
| 457 | You do not have to pick one. You assign the work to `g1t`, the way you |
| 458 | would assign an issue to a colleague, and **Auto** routes each job to the |
| 459 | least costly model that can do it, from three tiers: |
| 460 | |
| 461 | | Tier | Model today | For | |
| 462 | | --- | --- | --- | |
| 463 | | Fast | Claude Haiku 5.5 | Small, well-bounded work, and plans | |
| 464 | | Standard | Claude Sonnet 5.5 | Most changes and reviews | |
| 465 | | Most capable | Claude Opus 5.5 | Hard work, and work that failed on the standard model | |
| 466 | |
| 467 | The models are today's: when g1t moves a tier to a newer model, runs use |
| 468 | it within a minute. A model its provider retires is never used; the next |
| 469 | model for the tier runs, and the run's line says so. |
| 470 | |
| 471 | The job starts on its tier: |
| 472 | |
| 473 | | Work | Starts on | |
| 474 | | --- | --- | |
| 475 | | Making a change for an issue, revising it, and taking over handed-on work | Standard | |
| 476 | | Answering a question asked of `@g1t` | Fast | |
| 477 | | Reviewing a pull request that changes at most 10 files and 200 lines and touches no sensitive path | Fast | |
| 478 | | Reviewing a pull request that changes more than 60 files or 3,000 lines | Most capable | |
| 479 | | Reviewing any other pull request, or one whose changed files g1t does not know yet | Standard | |
| 480 | | Catching up with the base branch and resolving conflicts | Fast | |
| 481 | | Planning an outcome | Fast, at high effort | |
| 482 | |
| 483 | Then, in this order: |
| 484 | |
| 485 | 1. **Labels on the issue.** `architecture` sends the work to the most |
| 486 | capable model. `security` keeps it off the fast one. `documentation`, |
| 487 | `docs` and `typo` let a change or an answer start on the fast one. |
| 488 | 2. **Failures.** When the last attempt at the same work failed or stopped |
| 489 | at a guardrail cap, the next goes one tier up; after two in a row, to |
| 490 | the most capable. A revision counts each round before it. When the |
| 491 | last attempt finished but left a change g1t had |
| 492 | [low confidence](#how-sure-the-agent-is) in, the next goes one tier up. |
| 493 | 3. **What worked here.** g1t looks at the repository's last 20 runs of |
| 494 | the same kind. When the tier below finished at least 9 in 10 of at |
| 495 | least 5, the work goes down a tier; when this tier failed half of at |
| 496 | least 5, it goes up. Work that touches a sensitive path or carries |
| 497 | one of the labels above is never moved down. |
| 498 | |
| 499 | Sensitive paths are the ones that run, configure or guard things: CI |
| 500 | workflows, `.g1t/` and `.github/`, `CODEOWNERS`, secrets such as `.env` |
| 501 | and `.pem` files, and infrastructure such as Dockerfiles, Terraform and |
| 502 | `wrangler.*` files. They are the same paths that lower a change's |
| 503 | [confidence](#how-sure-the-agent-is). |
| 504 | |
| 505 | The agent's own small background steps run on the fast tier. |
| 506 | |
| 507 | Some work also has an effort level, how long the model thinks before it |
| 508 | answers: planning runs at high effort, answering a question at medium and |
| 509 | catching up at low, whichever tier the work lands on. Other work runs at |
| 510 | the model's default. A workspace's own provider is sent no effort level. |
| 511 | |
| 512 | Every run says which model it used and why, in one line: as the first |
| 513 | step on its run, and at the top of its pull request's session. For |
| 514 | example, *Used a fast model (Claude Haiku 5.5): small change, 3 files and |
| 515 | 80 lines.* An agent's review also says which model wrote it. When a better |
| 516 | model for a tier appears, g1t changes the route and nothing you have set |
| 517 | up needs to change. |
| 518 | |
| 519 | To choose instead of Auto, an owner picks **Fast**, **Standard** or **Most |
| 520 | capable** for a kind of work under |
| 521 | [which model does which work](/guides/models/#choose-which-model-does-which-work). |
| 522 | Every run of that kind then uses it, and says the workspace chose it. |
| 523 | |
| 524 | A workspace that routes its work to [its own provider](/guides/models/) |
| 525 | runs the model its route names. On an Anthropic key with no model named, |
| 526 | Auto chooses the tier's Claude model, as on g1t's models. |
| 527 | |
| 528 | A pull request g1t opens has `g1t` as its author and as its `agent` in the |
| 529 | API, and its commits are authored `g1t <g1t@users.noreply.g1t.sh>`. |
| 530 | |
| 531 | ## Who a pull request is for |
| 532 | |
| 533 | g1t is the author of every pull request it makes and of every issue it |
| 534 | files while at work. The person who asked for the work, by assigning the |
| 535 | issue or handing g1t the task, is kept beside it as **requested by**. Work |
| 536 | g1t starts itself, such as a [security update](/guides/security/), names |
| 537 | nobody. |
| 538 | |
| 539 | | Where | Author | Who asked | |
| 540 | | --- | --- | --- | |
| 541 | | The pull request's page, lists and link previews | **g1t** | **requested by** *name*, or **for** *name* | |
| 542 | | The API and MCP (`get_pull_request`, `list_pull_requests`, `get_issue`) | `author`: `{ "username": "g1t", "kind": "agent" }` | `requested_by`, or `null` | |
| 543 | | [Webhooks](/guides/webhooks/) | `data.author` | `data.requested_by`, left out when nobody asked | |
| 544 | | [Actions](/guides/actions/) (`github.event`) | `pull_request.user`, a `Bot` named `g1t` | `pull_request.requested_by`; `sender` is whoever caused the event | |
| 545 | | [Search](/guides/search/) | `author:g1t` finds it | shown as **for** *name* | |
| 546 | |
| 547 | The person who asked answers for the pull request as its author would: |
| 548 | |
| 549 | - they can update, close and mark it ready, catch it up and steer its |
| 550 | agent without the Triage role; |
| 551 | - they are never asked to review it, and they cannot approve it or |
| 552 | request changes on it; nor does their approval count toward the |
| 553 | repository's required approvals; |
| 554 | - it is on their own lists: what they are working on, and their profile; |
| 555 | - the sandboxes that work on it act as them, so it reaches what they can; |
| 556 | - its workflows and preview get secrets only when they have the Write |
| 557 | role or higher, as theirs would. |
| 558 | |
| 559 | Being its author gives g1t nothing more: a review by g1t's agent still |
| 560 | counts where the repository lets an agent's approval count. |
| 561 | |
| 562 | ## How model traffic is routed |
| 563 | |
| 564 | g1t's runs send model requests to g1t's model proxy at |
| 565 | `https://models.g1t.sh`, with a token for their run in place of a key; see |
| 566 | [your keys never reach a sandbox](/guides/models/#your-keys-never-reach-a-sandbox). |
| 567 | Requests for g1t's hosted models go on through |
| 568 | [Cloudflare AI Gateway](https://developers.cloudflare.com/ai-gateway/), |
| 569 | which holds g1t's key. Each of those requests is tagged with the kind of |
| 570 | work, the tier, the repository and the pull request, so spend can be read |
| 571 | per tier and per pull request. Requests for a workspace's own provider go to that provider. |
| 572 | |
| 573 | If you run your own copy of g1t, these settings control it: |
| 574 | |
| 575 | | Setting | Where | What it does | |
| 576 | | --- | --- | --- | |
| 577 | | `AGENT_ROUTING` | Runner | JSON. `tiers`: the model behind `small`, `large` and `frontier`, each `{ "modelName", "model", "price" }` (`price`, dollars per million `input`, `output`, `cacheRead` and `cacheWrite` tokens, is for estimates only). `tasks`: the tier `implement`, `revise`, `answer`, `review`, `update` and `plan` start on, or `change` to decide by the change. `smallChange` and `largeChange`: the most `files` and `lines` of a small change, and the least of a large one. `smallLabels`, `largeLabels` and `frontierLabels`: issue labels that move work. `frontierAfter`: failures in a row before the most capable tier. `learning`: `window`, `minRuns`, `stepDownAt` and `stepUpAt`. Anything left out takes the defaults above. | |
| 578 | | `MODELS_URL` | Runner | Where sandboxes send model requests: the model proxy. | |
| 579 | | `AI_GATEWAY_ID` | Model proxy | The gateway hosted requests go through. Empty sends them to the provider directly. | |
| 580 | | `AI_GATEWAY_TOKEN` | Model proxy | Secret. Authenticates to the gateway. | |
| 581 | | `ANTHROPIC_API_KEY` | Model proxy | Secret. The provider's key, if the gateway does not hold it. | |
| 582 | |
| 583 | ## What it costs |
| 584 | |
| 585 | A workspace pays for g1t's runs on its repositories, after they run: each |
| 586 | run is charged its sandbox by the second, at cost plus 20%, and the |
| 587 | [agent rate](/guides/usage-and-billing/#the-agent-rate) on the tokens it |
| 588 | used. On g1t's hosted models, the model is charged at what AI Gateway |
| 589 | priced its requests at, the provider's price with no markup. A |
| 590 | workspace's [own provider](/guides/models/) bills it for the model |
| 591 | directly; the agent rate is still charged, as **Agent rate, your own model |
| 592 | key**. See [Usage and billing](/guides/usage-and-billing/) for how prices |
| 593 | are set and the limits on usage not yet paid for. The workspace's |
| 594 | **Usage** page shows what its agents have cost, by day, kind of work, |
| 595 | repository and pull request, and their tokens by model. |
| 596 | |
| 597 | ## What a sandbox has |
| 598 | |
| 599 | Git, common shell tools, and toolchains for Node.js, Python, Go and Rust, so |
| 600 | an agent can build and test most projects. If your project needs something |
| 601 | else, the agent will say in its summary what it could not run. |
| 602 | |
| 603 | A workspace (or a project) can send its agents' work to |
| 604 | [its own runners](/guides/self-hosted-runners/#agents-on-your-runners) |
| 605 | instead, so agents build and test with what those machines have. The agent |
| 606 | works the same way there, with the same short-lived credentials, and its |
| 607 | model calls still go through g1t; the machine time is free. g1t's network |
| 608 | guardrails cannot be enforced on your machines, and the run says so. |
| 609 | |
| 610 | ## Who can run agents |
| 611 | |
| 612 | Putting an agent to work (assigning it, mentioning it, asking it for a |
| 613 | review, planning, sending it back to revise) needs the Write |
| 614 | [role](/guides/access-and-roles/) or higher on the repository. That |
| 615 | includes an [outside collaborator](/guides/access-and-roles/#outside-collaborators) |
| 616 | with Write: their runs are charged to the repository's workspace, as a |
| 617 | member's are, and count against its plan, caps and agent slots. They see |
| 618 | what their agents do, but not which model ran or what a run cost; those |
| 619 | are for members of the workspace. A run for an outside collaborator is |
| 620 | told the project's memory, never the workspace's. |
| 621 | |
| 622 | Agents cost g1t real money, so they run for paid workspaces. A free |
| 623 | workspace has the whole forge, and two ways to try agents: |
| 624 | |
| 625 | - **The trial.** $5 of usage, once per workspace, after a card check. |
| 626 | - **The open-source pool.** Workflows and the merge queue on public |
| 627 | repositories, after the same card check. It does not pay for agents. |
| 628 | |
| 629 | This holds whether the agent uses g1t's hosted models or |
| 630 | [the workspace's own model provider](/guides/models/): the sandbox an agent |
| 631 | works in is g1t's either way. Before anyone assigns, asks for a review or |
| 632 | plans, a free workspace's pages say "Agents need a paid workspace or the |
| 633 | free trial", with a link to its **Billing** page. |
| 634 | |
| 635 | Every agent run, of every kind (making a change, revising, reviewing, |
| 636 | catching up, planning, answering a mention), asks billing before it |
| 637 | starts. Billing reserves what the run is expected to cost: its model's |
| 638 | recent average (about $0.10 to make a change or plan, $0.07 to review) |
| 639 | plus its sandbox for its whole time cap. When the run ends, what it really |
| 640 | cost is settled against that. If billing refuses, nothing starts, and you |
| 641 | see why where you started it: |
| 642 | |
| 643 | | Where you started it | Where the refusal shows | |
| 644 | | --- | --- | |
| 645 | | **Assign to g1t**, **Request review**, **Plan it**, catching up | Under the button | |
| 646 | | A mention or the label rule | A comment from g1t on the issue or pull request | |
| 647 | | A step g1t takes by itself (a review, a revision, a catch-up) | The pull request's status, which then waits for you | |
| 648 | |
| 649 | Each refusal says what to do: start the plan or the trial, raise the spend |
| 650 | limit, or wait for next month's open-source pool, with the page to do it |
| 651 | on. |
| 652 | |
| 653 | ### Caps on a plan |
| 654 | |
| 655 | A workspace's plan sets caps on its agents. A new paid workspace in its |
| 656 | first month, and a workspace on the trial, has tighter ones. The amounts |
| 657 | are on [usage and billing](/guides/usage-and-billing/#caps). |
| 658 | |
| 659 | | Cap | What happens at it | |
| 660 | | --- | --- | |
| 661 | | Agents at once | A run over the cap waits for a free slot instead of being refused. An assigned issue goes back in the queue; a review, catch-up, plan or answer someone asked for waits its turn; a step g1t takes by itself is tried again at its next sweep, within five minutes. Each says "Waiting for a free slot". | |
| 662 | | Time per run | The lower of the project's [guardrails](/guides/guardrails/) time cap for that kind of run and the plan's. | |
| 663 | | Cost per run | The lower of the guardrails' cost cap and the plan's. The agent is stopped when it reaches it, as with any cost cap. | |
| 664 | | Cost per issue | What every agent run on an issue and its pull requests has cost in all. Past it, g1t does not start on that issue again and says so on it; an owner can raise the cap on the **Billing** page. | |
| 665 | |
| 666 | When the workspace's compute is paused (a spend spike waiting for an owner, |
| 667 | or a hold by g1t), nothing new starts, and the refusal gives the reason. |
| 668 | |
| 669 | ### When billing cannot be reached |
| 670 | |
| 671 | g1t's own billing service could be briefly unreachable. Then: |
| 672 | |
| 673 | - A paid workspace's runs go ahead, and the miss is logged. A billing blip |
| 674 | never stops a paying customer's work. |
| 675 | - A free workspace's runs do not start: they would be paid for by nobody. |
| 676 | Try again in a minute. |
| 677 | |
| 678 | g1t decides which a workspace is from its plan, or from the last plan it |
| 679 | saw for it in the past day. |
| 680 | |
| 681 | ### Other limits |
| 682 | |
| 683 | - A run has two hours. After that its credentials expire and it can no |
| 684 | longer push or report. |
| 685 | - Agents do not run on an [archived](/guides/managing-repositories/#archive-a-repository) |
| 686 | or deleted repository: nothing new starts, whether from an assignment, |
| 687 | a mention or the label rule, and a run under way cannot push or merge. |
| 688 | What was refused does not start by itself when the repository is |
| 689 | unarchived or restored; assign the work again. |
| 690 | |
| 691 | ## Credentials |
| 692 | |
| 693 | Every sandbox run gets credentials of its own, made when it starts and |
| 694 | revoked the moment it stops. They are not your access tokens, and they are |
| 695 | not listed with them. |
| 696 | |
| 697 | Each credential carries a composite identity: the agent, acting on behalf |
| 698 | of the person who started the work. A run you started by assigning an issue |
| 699 | is `g1t on behalf of you`, and that is how it appears in the |
| 700 | [audit log](/guides/audit-log/), on the run's page and in the pull |
| 701 | request's **Agent** panel. |
| 702 | |
| 703 | What it may do is the intersection of two things: |
| 704 | |
| 705 | - **The run's scope.** The credential is bound to the run, its repository, |
| 706 | and what that kind of run needs. It expires no later than the run's |
| 707 | timeout. |
| 708 | - **What you may do now.** It works only in the repository's workspace, |
| 709 | with your [role](/guides/access-and-roles/) on the repository as it is now, and never |
| 710 | more than Write: an owner's agent has Write, not Admin. If you leave the |
| 711 | workspace or lose your role, every agent working on your behalf there |
| 712 | loses it too. It can never change who has access. |
| 713 | |
| 714 | A sandbox holds two credentials. One is for g1t's runner, which clones, |
| 715 | pushes the result and records the session; downstream it acts as you, so |
| 716 | what it pushes is yours, within the run's scope. The other is for the |
| 717 | agent's own tools over MCP, and acts as the agent; it cannot be used with |
| 718 | git at all. |
| 719 | |
| 720 | | Kind of run | Git | API and MCP tools | |
| 721 | | --- | --- | --- | |
| 722 | | Implement | Reads the repository; pushes to its pull request's fork only | Records the session and marks its own pull request ready; tools to read issues, pull requests, the merge queue, workflow runs and memory, to [search all of g1t](/guides/search/) and the workspace's context hub, open issues, comment, remember, and message other agents | |
| 723 | | Revise, answer | Reads the repository; pushes to the pull request's fork, or to its branch only when the change is a branch of the repository | Records the session of its own pull request; the same tools as implement | |
| 724 | | Catch up | Reads the repository; pushes to the pull request's fork or branch only | Records the session of its own pull request | |
| 725 | | Review | Reads the change and the repository; pushes nothing | Reports its review through its own run | |
| 726 | | Plan | Reads the repository; pushes nothing | Reports its plan through its own run, for a person to apply; it can create issues in its repository only | |
| 727 | | Merge check | Reads the change; pushes nothing | None | |
| 728 | | Merge queue | Reads each queued change; pushes the queue's own branch only | None | |
| 729 | | Deploy | Reads the commit it builds; pushes nothing | None | |
| 730 | |
| 731 | Nothing an agent's credential holds can reach another repository, or a |
| 732 | workspace's settings, members, access tokens, billing, integrations, |
| 733 | webhooks, secrets and variables, or workflows' controls. It cannot merge a |
| 734 | pull request or put more agents to work. It cannot change its repository's |
| 735 | details or default branch, rename it or its branches, make it public or |
| 736 | private, archive, transfer, delete, restore or purge it; see |
| 737 | [managing a repository](/guides/managing-repositories/). A call that would is refused, and |
| 738 | the refusal is recorded with the rule that refused it: |
| 739 | |
| 740 | | Rule | Refused because | |
| 741 | | --- | --- | |
| 742 | | `never` | No agent's credential may ever do this. | |
| 743 | | `scope:operation` | The run's kind does not include this operation. | |
| 744 | | `scope:repository` | It names a repository other than the run's. | |
| 745 | | `scope:pull` | The runner tried to change a pull request other than its own. | |
| 746 | | `on-behalf-of:membership` | The person the agent works for is no longer a member of the workspace, and has no role on its repositories. | |
| 747 | | `git:read`, `git:push`, `git:ref` | The run has no grant to clone that repository, push to it, or move that branch or tag. | |
| 748 | | `git:not-a-run` | An agent's tools credential was used with git. | |
| 749 | |
| 750 | Personal and workspace access tokens are unchanged by any of this. |
| 751 | |
| 752 | ## What a sandbox can reach |
| 753 | |
| 754 | A sandbox holds one fork and its run's credentials, which expire when the |
| 755 | run's time is up and are revoked as soon as it stops. Those credentials, |
| 756 | and the model key the agent runs on, are removed from anything recorded in |
| 757 | the session. |
| 758 | |
| 759 | ## Guardrails |
| 760 | |
| 761 | A workspace decides what its agents may do in their sandboxes, and each |
| 762 | project can override it: which hosts a sandbox can reach (g1t, the package |
| 763 | registries the project needs, and domains you list; enforced outside the |
| 764 | sandbox), which commands the harness refuses (force-pushing, rewriting the |
| 765 | default branch, reading outside the project, printing the environment, |
| 766 | sudo, and your own patterns), and how much one run may cost and how long it |
| 767 | may take. A run that is refused something shows it as a step; one that |
| 768 | reaches a cap is stopped and its pull request waits for you. A run on a |
| 769 | fork's head loads none of the fork's `CLAUDE.md`, `.claude` settings, |
| 770 | hooks, MCP servers or commands. See [guardrails](/guides/guardrails/) for |
| 771 | every rule and exactly how each is enforced. |