| 1 | --- |
| 2 | title: Connect a coding agent |
| 3 | description: Connect Claude Code, Codex, Cursor, OpenCode or any MCP client to g1t, and have it work on issues, record its sessions and react to events. |
| 4 | --- |
| 5 | |
| 6 | import AgentSetup from '../../../components/AgentSetup.astro'; |
| 7 | |
| 8 | Claude Code, Codex, Cursor, OpenCode and any other harness connect to g1t |
| 9 | the way a person's tools do, and act as you, with the access you give |
| 10 | them: |
| 11 | |
| 12 | | To | Use | |
| 13 | | --- | --- | |
| 14 | | Read and change anything on g1t from inside the agent | The MCP server at `https://mcp.g1t.sh`: [MCP tools](/reference/mcp/) | |
| 15 | | Work from the agent's shell | The [g1t CLI](/guides/cli/): `g1t pr create`, `g1t pr checks --watch`, `g1t run logs --failed` | |
| 16 | | Push code | git over HTTPS, signed in with `g1t auth setup-git` or an [access token](/guides/authentication/#access-tokens) | |
| 17 | | Start the agent when something happens | [Webhooks](/guides/webhooks/), or a [workflow](/guides/actions/) on `issues` or `issue_comment` | |
| 18 | | Show people how a change was made | The pull request's [session](/guides/why-blame/#sessions) | |
| 19 | | See who is working on what, and not collide | [Sessions, claims and dependencies](/guides/sessions/) | |
| 20 | | Script anything else | The [REST API](/reference/api/), which has the same operations as the tools | |
| 21 | |
| 22 | The agent runs where you run it: on your machine, in your CI, or on a |
| 23 | [runner](/guides/self-hosted-runners/) of your own, on your own model |
| 24 | account. g1t runs no agents of its own; it keeps the code, the issues and |
| 25 | pull requests, the checks and the record of what happened. To start one |
| 26 | from g1t instead, see [hand an issue to g1t](#hand-an-issue-to-g1t). |
| 27 | |
| 28 | ## Connect your coding agent |
| 29 | |
| 30 | Choose your agent. Every block on these pages follows the choice, and it is |
| 31 | remembered for your next visit. For Claude Code, install g1t's |
| 32 | [Claude Code plugin](/guides/claude-code-plugin/): it adds the MCP server |
| 33 | and records your sessions, so `claude mcp add` is only for Claude Code |
| 34 | without it. |
| 35 | |
| 36 | <AgentSetup /> |
| 37 | |
| 38 | Signing in opens g1t in your browser. The page lists what the agent will be |
| 39 | able to do; untick anything you would rather it could not, and approve. |
| 40 | There is no token to copy. An agent that asks for nothing in particular gets |
| 41 | the [Agent preset](/guides/authentication/#presets), which never includes an |
| 42 | admin scope. It shows up in |
| 43 | [Settings → Connected applications](https://g1t.sh/settings/applications), |
| 44 | where you can change what it may do, or sign it out. |
| 45 | |
| 46 | The agent also needs to push with git. Where the [g1t CLI](/guides/cli/) |
| 47 | is signed in, `g1t auth setup-git` makes git use the same sign-in. |
| 48 | Otherwise git asks for a username and a password: use your g1t username |
| 49 | and an [access token](/guides/authentication/#access-tokens) with |
| 50 | `code:write`. |
| 51 | |
| 52 | Ask it to list the open issues on a repository, or to work on one, and it |
| 53 | will use g1t's tools. It sees only the tools and actions its access allows. |
| 54 | |
| 55 | ### With a token instead |
| 56 | |
| 57 | To skip the browser, for a script, a CI job or a machine without one, put an |
| 58 | [access token](/guides/authentication/#access-tokens) in `G1T_TOKEN` and |
| 59 | send it as a bearer token: |
| 60 | |
| 61 | <AgentSetup variant="token" /> |
| 62 | |
| 63 | ### What to give an agent |
| 64 | |
| 65 | Give an agent the least that lets it do its work: |
| 66 | |
| 67 | | Choose | For an agent | |
| 68 | | --- | --- | |
| 69 | | Scopes | The **Agent** [preset](/guides/authentication/#presets), which reads across g1t and writes what an agent's work needs, and never includes an admin scope. Add one only for a task that needs it. | |
| 70 | | Expires | The shortest that fits the work, such as 30 days. | |
| 71 | |
| 72 | A token reaches every workspace and repository you can. To keep an agent |
| 73 | to one workspace, give it that workspace's own |
| 74 | [workspace token](/guides/workspaces/#workspace-access-tokens) instead. |
| 75 | |
| 76 | The same choices are on the sign-in page for an agent that connects with |
| 77 | OAuth, and in [Settings → Access tokens](https://g1t.sh/settings/tokens) |
| 78 | for a token. A call the agent's access does not allow is refused with the |
| 79 | scope it needs; see [scopes](/guides/authentication/#scopes). Everything |
| 80 | the agent does is done as you, and shows as you in the |
| 81 | [audit log](/guides/audit-log/). |
| 82 | |
| 83 | ## How an agent works on an issue |
| 84 | |
| 85 | 1. `issue` with `work`, to load everything about it in one call: what |
| 86 | done means, who has claimed it, the pull requests already made for it, |
| 87 | and what it is blocked by. Then `issue` with `claim`, which also says |
| 88 | who else is on it. |
| 89 | 2. `pull_request` with `create` and the issue's number. This opens a draft |
| 90 | pull request and returns the git remote of its [working copy](/concepts/forks/#working-copies-for-pull-requests). |
| 91 | 3. Clone the working copy, make changes, commit and push. |
| 92 | 4. `pull_request` with `record_session` as it goes, so people can see its |
| 93 | reasoning. |
| 94 | 5. `pull_request` with `get`, to check `overlaps`, `behind` and the checks. |
| 95 | 6. `pull_request` with `ready` and a summary of what changed and why. |
| 96 | |
| 97 | ### Work with no issue yet |
| 98 | |
| 99 | Most of what an agent is asked starts without an issue, and a question, |
| 100 | a look around or a trivial fix never needs one. Record the session |
| 101 | anyway (`session` with `start`), with a `title` saying what it is for: the |
| 102 | team sees it in **Live now** on the project's overview and **Work** page, |
| 103 | under its pull request or branch. When the work becomes a change others |
| 104 | should know about (a branch to push, a pull request), look for its issue |
| 105 | (`issue` with `list` or `list_claims`) and claim it. If there is none, |
| 106 | `issue` with `claim`, a `title` and no `number` opens one and claims it |
| 107 | in one step, and attaches the session (`session_id`) to it: |
| 108 | |
| 109 | ```json |
| 110 | { "name": "issue", "arguments": { "action": "claim", "repo": "flagon-io/hello", "title": "Preview builds time out on large repositories", "session_id": "ses_01m4b2c3d4e5f6g7h8j9k0m1n2" } } |
| 111 | ``` |
| 112 | |
| 113 | See [Work with no issue yet](/guides/sessions/#work-with-no-issue-yet). |
| 114 | |
| 115 | The call that starts the pull request: |
| 116 | |
| 117 | ```json |
| 118 | { "name": "pull_request", "arguments": { "action": "create", "repo": "flagon-io/hello", "issue": 42, "agent": "claude-code" } } |
| 119 | ``` |
| 120 | |
| 121 | `agent` names the harness, so people can see what made the change. Its |
| 122 | commits show with the agent's name and mark too, from the address the |
| 123 | agent writes on them. |
| 124 | |
| 125 | Every push runs the repository's [workflows](/guides/actions/#checks) on |
| 126 | the pull request, as for anyone's. `pull_request` with `get` returns its |
| 127 | `statuses` and `required_checks`, the checks the default branch requires |
| 128 | before it merges. When one fails, `workflow` with `get_run` and `job_logs` |
| 129 | says why; push a fix and the workflows run again. Run the same tests and |
| 130 | linters the workflows run before you push, and you will rarely need to. |
| 131 | |
| 132 | When `main` has moved, `pull_request` with `update_branch` brings the pull |
| 133 | request up to date in a few seconds. When the changes clash, pull `main` |
| 134 | into the working copy, resolve and push. The pull request can then be |
| 135 | merged, or joins the [merge queue](/guides/merge-queue/) when the |
| 136 | repository uses one. |
| 137 | |
| 138 | When the merge queue takes an agent's pull request out because it fails |
| 139 | combined with the pull requests ahead of it, g1t |
| 140 | [says which ones and which check failed](/guides/merge-queue/#who-is-told): |
| 141 | in the pull request's session, as an `integration_failure` decision |
| 142 | (`pull_request` `list_decisions`), and as the `integration.failed` event. |
| 143 | The agent reads the other pull request's changes, fixes its own, and |
| 144 | pushes; once the checks pass, the pull request rejoins the queue by |
| 145 | itself. It can say what it changed with `pull_request` `record_decision` |
| 146 | (`kind` `fix`), and `repository` `why` explains any line it is unsure of. |
| 147 | |
| 148 | ### Repository instructions |
| 149 | |
| 150 | Each agent reads a repository's instructions from a file at its root: |
| 151 | Claude Code from `CLAUDE.md`, and Codex, OpenCode and Cursor from |
| 152 | `AGENTS.md`. To keep one file, write `AGENTS.md` and put `@AGENTS.md` in |
| 153 | `CLAUDE.md`. A few lines there make every agent work the same way on g1t: |
| 154 | |
| 155 | ```md title="AGENTS.md" |
| 156 | ## Working on g1t |
| 157 | |
| 158 | - Work in a draft pull request (`pull_request` `create` with the issue), |
| 159 | and record your session with `record_session` before each push. |
| 160 | - Read `overlaps` and `behind` on `pull_request` `get` before going far. |
| 161 | - Say why you made a choice with `pull_request` `record_decision`. |
| 162 | ``` |
| 163 | |
| 164 | An agent with a shell can use the [g1t CLI](/guides/cli/) instead of the |
| 165 | tools, and claim the issue, record its session and hand off with it: the |
| 166 | lines for that are in |
| 167 | [other coding agents](/guides/claude-code-plugin/#other-coding-agents). |
| 168 | With Claude Code, the [plugin](/guides/claude-code-plugin/) does this for |
| 169 | you. |
| 170 | |
| 171 | ## Record the session |
| 172 | |
| 173 | A pull request's session is the record of how it was made: the prompts, |
| 174 | the agent's reasoning, the tools it ran and what they returned. People read |
| 175 | it on the pull request's **Session** tab, and |
| 176 | [why-blame](/guides/why-blame/) uses it to explain each line. |
| 177 | |
| 178 | An agent can record its own session with the `pull_request` tool's |
| 179 | `record_session` action. It takes a list of `entries`, each with a `kind` |
| 180 | (`prompt`, `message`, `tool_call`, `tool_result` or `note`) and `text`, |
| 181 | and tool entries also carry the `tool` name. Record before each push: an |
| 182 | entry is tied to the commit that was the head when it was recorded. Do not |
| 183 | put secrets in a session; sessions are as visible as the repository. |
| 184 | |
| 185 | ### Recording sessions automatically |
| 186 | |
| 187 | With Claude Code, install g1t's plugin and every session in a g1t |
| 188 | repository is recorded without the agent having to remember: |
| 189 | |
| 190 | ```sh |
| 191 | claude plugin marketplace add https://g1t.sh/flagon-io/g1t-plugins.git |
| 192 | claude plugin install g1t@g1t |
| 193 | ``` |
| 194 | |
| 195 | Its hooks record your prompts, the tools Claude uses and what it called |
| 196 | them with, and its pushes, through the [g1t CLI](/guides/cli/), which |
| 197 | must be installed and signed in (`g1t auth login`), and title each |
| 198 | session with what its first prompt asked for. They never send what a |
| 199 | tool returned. The plugin also gives Claude the issue's work context when |
| 200 | a session starts (or, with no issue, when to claim or open one), g1t's MCP |
| 201 | server, and commands to claim and hand off issues. See [Claude Code plugin](/guides/claude-code-plugin/) for |
| 202 | everything it records, and how to opt out. |
| 203 | |
| 204 | Other agents record a session with the same CLI commands, from their |
| 205 | instructions file: see |
| 206 | [other coding agents](/guides/claude-code-plugin/#other-coding-agents). |
| 207 | |
| 208 | ## Staying out of each other's way |
| 209 | |
| 210 | Several agents, and people, can work on one repository at once. |
| 211 | `pull_request` with `get` returns: |
| 212 | |
| 213 | - `overlaps`: other pull requests in progress that change files this one |
| 214 | changes, with the paths. An overlap with a pull request for a different |
| 215 | issue will become a conflict for whichever merges second, so narrow the |
| 216 | change, or say so in the pull request. |
| 217 | - `behind`: whether `main` has moved since the pull request was made. If |
| 218 | it has, `update_branch` before asking for a merge. |
| 219 | |
| 220 | Required checks, [rules](/guides/rules/) and the |
| 221 | [merge queue](/guides/merge-queue/) hold for an agent's pull request |
| 222 | exactly as for a person's. |
| 223 | |
| 224 | ## Hand an issue to g1t |
| 225 | |
| 226 | g1t runs no model of its own, but it can start a session for you on the |
| 227 | workspace's own Anthropic account. Once an owner adds an Anthropic key |
| 228 | under [**AI**](/guides/ai/): |
| 229 | |
| 230 | - **Assign to g1t** in an issue's sidebar (or `g1t issue edit 12 |
| 231 | --add-assignee g1t`), or mention `@g1t` in a comment on an issue or pull |
| 232 | request, with what you want done. |
| 233 | - **Start a session** on an issue's page, `g1t work dispatch 12`, or the |
| 234 | `session` tool's `dispatch` action, to choose the mode (`plan`, |
| 235 | `implement` or `review`). |
| 236 | |
| 237 | g1t reacts 👀, then starts the session as you, with a token for that |
| 238 | repository only that is revoked when the session ends. It installs the |
| 239 | g1t CLI, clones the repository and works the way this page describes; its |
| 240 | card shows in the issue's conversation, and Anthropic bills the account |
| 241 | for it. Without an Anthropic key, `g1t work dispatch` prints a Claude Code |
| 242 | command to run yourself instead. See |
| 243 | [Assign g1t](/guides/sessions/#assign-g1t-or-ask-it-in-the-thread) and |
| 244 | [Start a session on your Anthropic account](/guides/sessions/#start-a-session-on-your-anthropic-account). |
| 245 | |
| 246 | ## Start an agent when something happens |
| 247 | |
| 248 | To run your agent without anyone starting it by hand, react to g1t's |
| 249 | events: |
| 250 | |
| 251 | - **Webhooks.** Register an address for a repository or a whole workspace |
| 252 | with the `webhook` tool or in its settings, and choose the events, such |
| 253 | as `issue.labeled`, `issue.assigned`, `comment.created`, |
| 254 | `checks.completed` or `workflow.completed`. Each delivery is signed. See |
| 255 | [webhooks](/guides/webhooks/). |
| 256 | - **Workflows.** A workflow in `.g1t/workflows/` can start on `issues` or |
| 257 | `issue_comment` and run your agent's command line on a g1t runner, with |
| 258 | its key in a [secret](/guides/secrets-and-variables/). See |
| 259 | [GitHub Actions](/guides/actions/). |
| 260 | - **Notifications.** An agent that works as you can read your inbox with |
| 261 | the `notifications` tool: review requests, mentions, assignments and |
| 262 | your work's checks, each with why you were told. |
| 263 | |
| 264 | ## Reviewing as an agent |
| 265 | |
| 266 | An agent can review as well as write. Given an issue with several pull |
| 267 | requests, it can call `pull_request` with `changes` and `read_session` on |
| 268 | each, compare them, and read each one's check results from `get`. It can |
| 269 | leave findings on specific lines with `issue` and `comment`, give a verdict |
| 270 | with `pull_request` and `review`, and, with the Write role, `merge` the |
| 271 | best one. It cannot approve or request changes on a pull request it opened. |
| 272 | |
| 273 | ## Artifacts |
| 274 | |
| 275 | Your agent can read and write a workspace's artifacts: its docs, and later |
| 276 | its slides, designs and dashboards. The `artifact` tool does it as you, |
| 277 | so it opens only what you can open, and changes only what you can change. |
| 278 | Its token needs `artifacts:read` to read them (the Read only and Agent |
| 279 | [presets](/guides/authentication/#presets) have it), `artifacts:write` to |
| 280 | make and change them, and `artifacts:admin` to share them or delete them |
| 281 | for good. A token without one of these sees no `artifact` tool, and a |
| 282 | token sees only the actions its scope allows. |
| 283 | |
| 284 | 1. Find what is there with `list` (narrow with `kind`, `space` or `q`) or |
| 285 | `search`, which matches words and meaning and returns the passage that |
| 286 | matched. |
| 287 | 2. Read one with `read`. A doc comes back as Markdown in `content`, with |
| 288 | its top-level `blocks` and their ids, and `can` says whether you may |
| 289 | edit it or only suggest. |
| 290 | 3. Change it with `edit`: `markdown` and a `target`, which is `append`, |
| 291 | `document` (replace it all), a `section` by its `heading`, or `blocks` |
| 292 | from one block id to another. With the edit role the change is made, as |
| 293 | a new version; with the comment role, or with `suggest_only`, it is |
| 294 | filed as a suggestion that the doc's editors accept or reject. |
| 295 | 4. Make one with `create`. Left out `space` and `parent_id`, it lands in |
| 296 | your Private, where only you can open it until you share it. |
| 297 | |
| 298 | ```json |
| 299 | { "action": "edit", "workspace": "acme", "artifact_id": "fol_01kq7c4e6g8j0m2p4r6t8v0x2z", |
| 300 | "target": { "kind": "section", "heading": "Risks" }, |
| 301 | "markdown": "## Risks\n\nThe migration needs a maintenance window.\n", |
| 302 | "note": "Adds the migration risk" } |
| 303 | ``` |
| 304 | |
| 305 | Name an artifact by its id (`fol_…`) or by its link. Each action is also |
| 306 | a REST route under `/workspaces/{workspace}/artifacts`; see the |
| 307 | [API reference](/reference/api/). These are not workflow runs' artifacts, |
| 308 | which are the `workflow` tool's. Slides, designs and dashboards answer |
| 309 | that they are not here yet. A workspace's own token cannot use artifacts: |
| 310 | they always belong to a person. |
| 311 | |
| 312 | ## Filing issues from another system |
| 313 | |
| 314 | Anything that holds an access token can open issues: an error tracker, a |
| 315 | monitor, a script. Call the `issue` tool with `create`, or `POST |
| 316 | /repos/{owner}/{name}/issues`, with a title, a description and labels |
| 317 | such as `bug`. Its token needs `issues:write`. The issue is attributed to |
| 318 | the account the token belongs to. |
| 319 | |
| 320 | ## Tools |
| 321 | |
| 322 | Each tool is a kind of thing on g1t and takes an `action`, such as `get` |
| 323 | or `create`. Repositories are given as `owner/name`, and issues and pull |
| 324 | requests as the repository and a `number`. |
| 325 | |
| 326 | | Tool | What it covers | |
| 327 | | --- | --- | |
| 328 | | `search` | Code, repositories, issues, pull requests and people across g1t; a tracker's ticket | |
| 329 | | `repository` | Repositories, their settings, rulesets, branches, labels, milestones and releases | |
| 330 | | `issue` | Issues, labels and comments; an issue's whole context, and claims | |
| 331 | | `pull_request` | Pull requests: create, record and read sessions, review, merge, the merge queue | |
| 332 | | `session` | Your harness's session: start, update, record, end, get, list; dispatch work on an issue; who else is working | |
| 333 | | `workflow` | Workflow runs and logs, checks, deployments, environments and runners | |
| 334 | | `observability` | A project's requests, logs, traces, errors and metrics in production | |
| 335 | | `package` | Packages in every registry | |
| 336 | | `secret` | Secrets and variables | |
| 337 | | `security` | Secret scanning, code scanning, vulnerable dependencies and advisories | |
| 338 | | `webhook` | Webhooks and their deliveries | |
| 339 | | `access` | Who has which role on a repository, and deploy keys | |
| 340 | | `team` | Teams and their members and repositories | |
| 341 | | `workspace` | Workspaces, members, integrations, projects, rulesets and token rules | |
| 342 | | `ai` | The workspace's AI providers, and what Ask answers with | |
| 343 | | `billing` | Usage, budget and invoices | |
| 344 | | `notifications` | Your inbox | |
| 345 | | `account` | Who the token acts as, and your invitations | |
| 346 | | `artifact` | A workspace's docs | |
| 347 | |
| 348 | [MCP tools](/reference/mcp/) lists every action with its required inputs, |
| 349 | its scope and its REST route. |
| 350 | |
| 351 | ## Other clients |
| 352 | |
| 353 | The server speaks MCP over streamable HTTP and answers each request with |
| 354 | JSON. Every call needs to be signed in. Opening |
| 355 | [mcp.g1t.sh](https://mcp.g1t.sh) in a browser shows what the server is, how |
| 356 | to connect, and the tools it offers. |
| 357 | |
| 358 | A client that supports MCP authorization needs only the URL. An |
| 359 | unauthenticated request is answered with `401` and a pointer to |
| 360 | `https://mcp.g1t.sh/.well-known/oauth-protected-resource`, from which the |
| 361 | client finds g1t's authorization server, registers itself, and sends you to |
| 362 | your browser. A client that asks for scopes sends them in `scope` on the |
| 363 | authorization request. See |
| 364 | [signing in with OAuth](/guides/authentication/#signing-in-with-oauth). |
| 365 | |
| 366 | A client that does not can send `Authorization: Bearer <token>` with an |
| 367 | access token. |