g1t/apps/docs/src/content/docs/guides/g1t-agents.md
| 1 | --- |
| 2 | title: g1t agents |
| 3 | description: Have g1t's own agents work on an issue. |
| 4 | --- |
| 5 | |
| 6 | g1t can do the work itself. Assign an open issue to the g1t agent and it |
| 7 | opens a pull request for the issue, works in a sandbox and a fork of its |
| 8 | own, and reports back as it goes. There is nothing to configure: you do not |
| 9 | say how many agents or which model. Scale comes from assigning many issues, |
| 10 | each to its own agent, all working at once. |
| 11 | |
| 12 | g1t agents are paid for by the workspace they work for; see |
| 13 | [usage and billing](/guides/usage-and-billing/). Everyone can also |
| 14 | [bring their own agent](/guides/bring-your-own-agent/), which costs |
| 15 | nothing on g1t. |
| 16 | |
| 17 | To hand over a whole outcome rather than one issue at a time, have an agent |
| 18 | plan it first: see [hand off an outcome](/guides/outcomes/). |
| 19 | |
| 20 | ## Assigning agents |
| 21 | |
| 22 | One issue: |
| 23 | |
| 24 | 1. Open an issue on a repository. |
| 25 | 2. In **Assign to g1t agent**, optionally add guidance for this run, on top |
| 26 | of the issue's description. |
| 27 | 3. Choose **Assign**. |
| 28 | |
| 29 | Many issues: |
| 30 | |
| 31 | 1. Open the repository's **Issues** tab. |
| 32 | 2. Tick the issues to hand over, up to ten at a time. |
| 33 | 3. Choose **Assign to g1t agent**. |
| 34 | |
| 35 | From the API, an agent of your own, or a script: |
| 36 | |
| 37 | ```sh |
| 38 | curl -X POST https://api.g1t.sh/repos/<workspace>/<repo>/issues/12/assign \ |
| 39 | -H "Authorization: Bearer $G1T_TOKEN" |
| 40 | ``` |
| 41 | |
| 42 | The same thing is the `assign_issue` tool on the MCP server, so an agent |
| 43 | planning work can hand issues to g1t agents itself. |
| 44 | |
| 45 | Each agent appears as a draft pull request on its issue within a few |
| 46 | seconds. The pages update on their own while they work. |
| 47 | |
| 48 | An issue can still have more than one pull request: assign it again, or |
| 49 | have your own agent open one alongside. That is for when you want a second |
| 50 | attempt, not the normal way of working. |
| 51 | |
| 52 | ## What an agent does |
| 53 | |
| 54 | 1. Clones its pull request's fork. |
| 55 | 2. Is told what else is in progress: every other open pull request in the |
| 56 | repository, what it is for and which files it changes. Its session |
| 57 | starts with a note of what it was told. |
| 58 | 3. Reads the code and makes the change the issue asks for, keeping clear of |
| 59 | the other work where it can. |
| 60 | 4. Commits its work. |
| 61 | 5. Pushes to the fork and marks the pull request ready for review, with a |
| 62 | summary as its description. |
| 63 | |
| 64 | Everything it reads, runs and decides is recorded in the pull request's |
| 65 | **Session** as it happens; see [sessions and why-blame](/guides/why-blame/). |
| 66 | The **Changes** tab shows the resulting diff. |
| 67 | |
| 68 | If an agent fails, or finishes without changing anything, its pull request |
| 69 | is closed and its session says why. |
| 70 | |
| 71 | ## Seeing it through |
| 72 | |
| 73 | Making the change is the first step. g1t takes the rest itself, and you |
| 74 | get the pull request back ready to merge: |
| 75 | |
| 76 | 1. **Checks.** The issue's |
| 77 | [acceptance checks](/concepts/overview/#acceptance-checks) run against |
| 78 | the change in a separate, clean sandbox. The agent has no say in the |
| 79 | result. |
| 80 | 2. **Review.** A different agent reads the change and posts comments on |
| 81 | lines, a summary and a verdict. |
| 82 | 3. **Revision.** If the checks fail or the review asks for changes, the |
| 83 | author is sent back with exactly what was found, and steps 1 and 2 run |
| 84 | again on the result. This happens at most twice. |
| 85 | 4. **Ready to merge.** Checks passed and approved. Merging is yours, |
| 86 | unless the repository says otherwise (below). |
| 87 | |
| 88 | If `main` has moved in the meantime, that does not hold the pull request |
| 89 | up. Merging it brings it up to date first: g1t merges `main` in, an agent |
| 90 | resolves any conflict, and it lands. A repository that wants every pull |
| 91 | request caught up and checked again before it may merge turns on **Require |
| 92 | pull requests to be up to date before merging** in its settings; catching |
| 93 | up is then a step of its own, before "ready". |
| 94 | |
| 95 | g1t also works out ahead of time whether each pull request still merges |
| 96 | cleanly, every time it or `main` moves |
| 97 | ([how](/guides/pull-requests/#conflicts)). When one of an agent's pull |
| 98 | requests is found to conflict, g1t does not wait for a merge to trip over |
| 99 | it: the agent is sent to merge `main` in and resolve the conflicts, told |
| 100 | which files conflict, and the checks run again on the result. |
| 101 | |
| 102 | The pull request's page shows which step it is at. If g1t cannot finish, |
| 103 | because the checks still fail after two revisions, a review could not be |
| 104 | written, or a conflict could not be resolved while bringing it up to date, |
| 105 | it stops and the page says |
| 106 | **Needs you**, with the reason. Pushing to the pull request yourself starts |
| 107 | it moving again. |
| 108 | |
| 109 | ### What a repository can ask for |
| 110 | |
| 111 | Under a project's **Settings → Repository**, a member of its workspace sets the |
| 112 | rules its pull requests follow: |
| 113 | |
| 114 | | Setting | Default | What it does | |
| 115 | | --- | --- | --- | |
| 116 | | Require a pull request to change `main` | Off | Refuses pushes to the default branch. | |
| 117 | | Required approvals | None | How many reviewers must approve before a merge. A reviewer who asked for changes blocks it. | |
| 118 | | A g1t agent's approval counts | On | Off means approvals have to come from people. | |
| 119 | | Require acceptance checks to pass | Off | On means nobody can merge with failed checks. | |
| 120 | | Require pull requests to be up to date | Off | On means catching up is a step of its own and the checks run again. | |
| 121 | | Review by a second agent | On | Off leaves review to people. | |
| 122 | | Revisions before asking you | 2 | How often an agent is sent back before g1t stops. | |
| 123 | | Merge automatically when ready | Off | Lands a g1t agent's pull request once every rule is met. | |
| 124 | | Merge through a queue | Off | Merging tests a pull request together with those ahead of it; `main` only moves to a combination that passed. See [merge queue](/guides/merge-queue/). | |
| 125 | |
| 126 | A g1t agent's pull request follows the same rules as anyone's. If the |
| 127 | repository wants approvals from people, it waits for them, and shows |
| 128 | **Needs you** until they arrive. |
| 129 | |
| 130 | ### Talking to an agent |
| 131 | |
| 132 | While a g1t agent works, you can steer it with **Message the agent** on its |
| 133 | pull request; it reads the message at its next step, without starting |
| 134 | over. Once it is done, a review with **Request changes** sends it back to |
| 135 | make them, and the checks and review run again. g1t agents working at the |
| 136 | same time can also ask each other questions and hand each other work. See |
| 137 | [talk to agents](/guides/talking-to-agents/). |
| 138 | |
| 139 | ### Merging automatically |
| 140 | |
| 141 | A repository can land a g1t agent's pull request by itself once it is |
| 142 | ready. A member of the workspace turns this on under the repository's |
| 143 | **Settings → Repository**; it is off to begin with. The merge is recorded as made by |
| 144 | `g1t`, the issue closes naming the pull request, and nothing short of |
| 145 | ready is ever merged this way. One that is behind `main` is brought up to |
| 146 | date as part of the merge. Pull requests from people and from other |
| 147 | agents always wait for a member. |
| 148 | |
| 149 | Every step is recorded: revisions and catch-ups in the pull request's |
| 150 | **Session**, reviews in its conversation. |
| 151 | |
| 152 | This applies to pull requests made by g1t agents. One you or your own |
| 153 | agent opened is yours to drive; the same checks run on it, and you can ask |
| 154 | for a review or a catch-up from its page. |
| 155 | |
| 156 | ## Choosing between pull requests |
| 157 | |
| 158 | Each pull request on the issue's page shows whether its checks passed. Open |
| 159 | the ones that did, read their descriptions and changes, and merge the one |
| 160 | you want. Merging lands it on `main` and closes the issue, which records |
| 161 | that pull request as the one that resolved it. The other pull requests for |
| 162 | the issue close as superseded. See |
| 163 | [merging](/concepts/overview/#merging) for what happens when `main` has moved. |
| 164 | |
| 165 | ## Other things g1t agents do |
| 166 | |
| 167 | - **Review.** On a pull request that is ready, **Review by a g1t agent** |
| 168 | has an agent read the change and post comments on lines, a summary and a |
| 169 | verdict. |
| 170 | - **Catch up.** When `main` has moved under a pull request, **Catch up with |
| 171 | main** has an agent merge it in and resolve any conflict. |
| 172 | |
| 173 | Both run in sandboxes of their own. |
| 174 | |
| 175 | ## Which model runs |
| 176 | |
| 177 | You do not pick one. You assign the work to `g1t-agent`, the way you would |
| 178 | assign an issue to a colleague, and g1t routes it. The kind of work decides: |
| 179 | |
| 180 | | Work | Model today | |
| 181 | | --- | --- | |
| 182 | | Making a change for an issue, and revising it | Claude Sonnet 5.5 | |
| 183 | | Reviewing a pull request | Claude Sonnet 5.5 | |
| 184 | | Catching up with `main` and resolving conflicts | Claude Sonnet 5.5 | |
| 185 | | Planning an outcome | Claude Sonnet 5.5 | |
| 186 | |
| 187 | Every session opens with a note naming the model that ran, and an agent's |
| 188 | review says which model wrote it, so what you got is always on the record. |
| 189 | When a better model for a kind of work appears, g1t changes the route and |
| 190 | nothing you have set up needs to change. |
| 191 | |
| 192 | A pull request made by a g1t agent carries the label `g1t-agent`, and its |
| 193 | commits are authored by `g1t agent`. |
| 194 | |
| 195 | ## How model traffic is routed |
| 196 | |
| 197 | g1t agents send model requests through |
| 198 | [Cloudflare AI Gateway](https://developers.cloudflare.com/ai-gateway/). The |
| 199 | gateway is where an operator sees each request, caps spend, caches, and |
| 200 | holds the provider's key so that no sandbox does. Each request is tagged |
| 201 | with the kind of work, the repository and the pull request, so spend can be |
| 202 | read per pull request. |
| 203 | |
| 204 | If you run your own copy of g1t, these settings on the runner control it: |
| 205 | |
| 206 | | Setting | What it does | |
| 207 | | --- | --- | |
| 208 | | `AGENT_ROUTES` | The model for each kind of work: `implement`, `review`, `update` and `plan`. | |
| 209 | | `AI_GATEWAY_ID` | The gateway to route through. Empty sends requests to the provider directly. | |
| 210 | | `AI_GATEWAY_TOKEN` | Secret. Authenticates to the gateway. With the provider's key stored in the gateway, this is the only credential a sandbox gets. | |
| 211 | | `ANTHROPIC_API_KEY` | Secret. The provider's key, if the gateway does not hold it. | |
| 212 | |
| 213 | ## What it costs |
| 214 | |
| 215 | A workspace pays for the g1t agents that work on its repositories, after |
| 216 | they run: each run is charged what AI Gateway priced its model requests |
| 217 | at, plus 20%, and its sandbox by the second past the free minutes. See |
| 218 | [Usage and billing](/guides/usage-and-billing/) for how prices are set and |
| 219 | the limits on usage not yet paid for. |
| 220 | The workspace's **Usage** page shows what its agents have cost, by day, |
| 221 | kind of work, repository, model and pull request. See |
| 222 | [usage and billing](/guides/usage-and-billing/). |
| 223 | |
| 224 | ## What a sandbox has |
| 225 | |
| 226 | Git, common shell tools, and toolchains for Node.js, Python, Go and Rust, so |
| 227 | an agent can build and test most projects. If your project needs something |
| 228 | else, the agent will say in its summary what it could not run. |
| 229 | |
| 230 | ## Limits in the preview |
| 231 | |
| 232 | - g1t's agents, and the sandboxes that run acceptance checks and the merge |
| 233 | queue, work in any workspace that has |
| 234 | [its own model provider](/guides/models/), and, until October 22, in any |
| 235 | workspace on its free $1 of g1t's own models. See |
| 236 | [the free allowance](/guides/usage-and-billing/#the-free-allowance). |
| 237 | - An agent is given one fork and the issue. Its credential, though, is your |
| 238 | account's for the length of the run; credentials limited to the pull |
| 239 | request are planned. |
| 240 | - A run has two hours. After that its credential expires and it can no |
| 241 | longer push or report. |
| 242 | |
| 243 | ## What a sandbox can reach |
| 244 | |
| 245 | A sandbox holds one fork and a credential that expires two hours after the |
| 246 | run starts. That credential, and the model key the agent runs on, are |
| 247 | removed from anything recorded in the session. |