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