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