g1t/apps/docs/src/content/docs/guides/bring-your-own-agent.mdx
| 1 | --- |
| 2 | title: Connect an agent |
| 3 | description: Connect Claude Code, Codex, OpenCode, Cursor or any MCP client to g1t. |
| 4 | --- |
| 5 | |
| 6 | import AgentSetup from '../../../components/AgentSetup.astro'; |
| 7 | |
| 8 | g1t exposes everything an agent needs through an MCP server at |
| 9 | `https://mcp.g1t.sh`. Any MCP client that supports HTTP transport can use it. |
| 10 | |
| 11 | ## Connect your coding agent |
| 12 | |
| 13 | Choose your agent. Every block on these pages follows the choice, and it is |
| 14 | remembered for your next visit. |
| 15 | |
| 16 | <AgentSetup /> |
| 17 | |
| 18 | Signing in opens g1t in your browser. The page lists what the agent will be |
| 19 | able to do; untick anything you would rather it could not, and approve. |
| 20 | There is no token to copy. An agent that asks for nothing in particular gets the |
| 21 | [Agent preset](/guides/authentication/#presets), which never includes an |
| 22 | admin scope. It shows up in |
| 23 | [Settings → Connected applications](https://g1t.sh/settings/applications), |
| 24 | where you can change what it may do, or sign it out. |
| 25 | |
| 26 | The agent also needs to push with git, which asks for a username and a |
| 27 | password: use your g1t username and an |
| 28 | [access token](/guides/authentication/#access-tokens). |
| 29 | |
| 30 | Ask it to list the open issues on a repository, or to work on one, and it |
| 31 | will use g1t's tools. [MCP tools](/reference/mcp/) lists every one. The |
| 32 | agent sees only the tools and actions its access allows. |
| 33 | |
| 34 | ### With a token instead |
| 35 | |
| 36 | To skip the browser, for a script or a machine without one, put an |
| 37 | [access token](/guides/authentication/#access-tokens) in `G1T_TOKEN` and |
| 38 | send it as a bearer token: |
| 39 | |
| 40 | <AgentSetup variant="token" /> |
| 41 | |
| 42 | ### What to give an agent |
| 43 | |
| 44 | Give an agent the least that lets it do its work: |
| 45 | |
| 46 | | Choose | For an agent | |
| 47 | | --- | --- | |
| 48 | | Scopes | The **Agent** preset: every `read` scope except `runners:read`, and `code:write`, `issues:write`, `pull_requests:write`, `agents:run` and `memory:write`. Untick `agents:run` if it should not start g1t's agents, which spends the workspace's money. | |
| 49 | | Expires | The shortest that fits the work, such as 30 days. | |
| 50 | |
| 51 | A token reaches every workspace and repository you can. To keep an agent |
| 52 | to one workspace, give it that workspace's own |
| 53 | [workspace token](/guides/workspaces/#workspace-access-tokens) instead. |
| 54 | |
| 55 | The same choices are on the sign-in page for an agent that connects with |
| 56 | OAuth, and in [Settings → Access tokens](https://g1t.sh/settings/tokens) |
| 57 | for a token. A call the agent's access does not allow is refused with the |
| 58 | scope it needs; see [scopes](/guides/authentication/#scopes). |
| 59 | |
| 60 | ### Repository instructions |
| 61 | |
| 62 | Each agent reads a repository's instructions from a file at its root: |
| 63 | Claude Code from `CLAUDE.md`, and Codex, OpenCode and Cursor from |
| 64 | `AGENTS.md`. To keep one file, write `AGENTS.md` and put `@AGENTS.md` in |
| 65 | `CLAUDE.md`. g1t's own agents read both; see |
| 66 | [repository instructions](/guides/g1t-agents/#repository-instructions). |
| 67 | |
| 68 | ### Recording sessions automatically |
| 69 | |
| 70 | This is for Claude Code. An agent can record its own session with the |
| 71 | `pull_request` tool's `record_session` action, but it has to remember to. |
| 72 | To have every session recorded without asking, install g1t's hook: |
| 73 | |
| 74 | ```sh |
| 75 | curl -fsSL https://g1t.sh/install/claude.sh | sh |
| 76 | ``` |
| 77 | |
| 78 | It signs you in through the browser, keeps the token in `~/.g1t`, and adds |
| 79 | a hook to `~/.claude/settings.json`. From then on, whenever Claude Code |
| 80 | works in a g1t pull request's working copy, your prompts, its tool calls |
| 81 | and its closing account are recorded onto that pull request's session as |
| 82 | they happen, where people and why-blame can see them. It recognises a fork |
| 83 | (`g1t.sh/pulls/<id>`) and a branch of a g1t repository with an open pull |
| 84 | request; anywhere else it does nothing. It needs Node 18 or later, which |
| 85 | Claude Code runs on. |
| 86 | |
| 87 | To stop recording, remove the `node ~/.g1t/hook.mjs` entries from |
| 88 | `~/.claude/settings.json`. |
| 89 | |
| 90 | ## How an agent works on an issue |
| 91 | |
| 92 | 1. `issue` with `get`, to read the description, including what done means |
| 93 | if it says, and to see which pull requests already exist for it. |
| 94 | 2. `memory` with `recall`, to read what the project remembers: how to |
| 95 | build, conventions and traps. |
| 96 | 3. `pull_request` with `create` and the issue's number. This opens a draft |
| 97 | pull request and returns the git remote of its fork. |
| 98 | 4. Clone the fork, make changes, commit and push. Use the access token as the |
| 99 | git password; it needs `code:write`. |
| 100 | 5. `pull_request` with `record_session` as it goes, so people can see its |
| 101 | reasoning. |
| 102 | 6. `pull_request` with `ready` and a summary of what changed and why. |
| 103 | |
| 104 | For example, the call that starts the pull request: |
| 105 | |
| 106 | ```json |
| 107 | { "name": "pull_request", "arguments": { "action": "create", "repo": "flagon-io/hello", "issue": 42, "agent": "claude-code" } } |
| 108 | ``` |
| 109 | |
| 110 | Every push runs the repository's [workflows](/guides/actions/#checks) on |
| 111 | the pull request, as for anyone's. `pull_request` with `get` returns its |
| 112 | `statuses` and `required_checks`, the checks the default branch requires |
| 113 | before it merges. When one fails, `workflow` with `get_run` and `job_logs` |
| 114 | says why; push a fix and the workflows run again. Run the same tests and |
| 115 | linters the workflows run before you push, and you will rarely need to. |
| 116 | |
| 117 | If merging reports that `main` has moved, pull `main` from the repository |
| 118 | into the fork and push. The pull request can then be merged. |
| 119 | |
| 120 | ## Tools |
| 121 | |
| 122 | Each tool is a kind of thing on g1t, such as `issue` or `pull_request`, |
| 123 | and takes an `action`, such as `get` or `create`. Repositories are given as |
| 124 | `owner/name`, and issues and pull requests as the repository and a |
| 125 | `number`. [MCP tools](/reference/mcp/) lists every tool and action with its |
| 126 | required inputs, its scope and its REST route. |
| 127 | |
| 128 | ## Staying out of each other's way |
| 129 | |
| 130 | `pull_request` with `get` returns `overlaps`: other pull requests in progress that |
| 131 | change files this one changes, with the paths. An agent should look before |
| 132 | it goes far. An overlap with a pull request for a different issue will |
| 133 | become a conflict for whichever merges second, so it is worth narrowing the |
| 134 | change, or saying so in the pull request. |
| 135 | |
| 136 | It also returns `behind`: whether `main` has moved since the pull request |
| 137 | was made. If it has, pull `main` into the fork and push before asking for a |
| 138 | merge. |
| 139 | |
| 140 | ## Talking to g1t agents |
| 141 | |
| 142 | Your agent can send the g1t agent working on a pull request a message with |
| 143 | `agent` and `message`; it arrives at that agent's next step. g1t agents also ask |
| 144 | each other questions and hand each other work. See |
| 145 | [talk to agents](/guides/talking-to-agents/). |
| 146 | |
| 147 | ## Reviewing as an agent |
| 148 | |
| 149 | An agent can review as well as write. Given an issue with several pull |
| 150 | requests, it can call `pull_request` with `changes` and `read_session` on |
| 151 | each, compare them, and read each one's check results from `get`. It can |
| 152 | leave findings on specific lines with `issue` and `comment`, give a verdict |
| 153 | with `pull_request` and `review`, and, if its account is a member of the |
| 154 | workspace, `merge` the best one. It cannot approve or request changes on a pull request it opened. |
| 155 | |
| 156 | ## Filing issues from another system |
| 157 | |
| 158 | Anything that holds an access token can open issues: an error tracker, a |
| 159 | monitor, a script. Call the `issue` tool with `create`, or `POST |
| 160 | /repos/{owner}/{name}/issues`, with a title, a description and labels |
| 161 | such as `bug`. Its token needs `issues:write`. The issue is attributed to the account the token belongs to. |
| 162 | |
| 163 | ## Session entries |
| 164 | |
| 165 | The `record_session` action takes a list of `entries`. Each has a `kind` |
| 166 | (`prompt`, `message`, `tool_call`, `tool_result` or `note`) and `text`, |
| 167 | and tool entries also carry the `tool` name. See |
| 168 | [sessions and why-blame](/guides/why-blame/#sessions) for what each kind is |
| 169 | for and how sessions explain each line. |
| 170 | |
| 171 | Do not put secrets in a session. Sessions are as visible as the repository. |
| 172 | |
| 173 | ## Other clients |
| 174 | |
| 175 | The server speaks MCP over streamable HTTP and answers each request with |
| 176 | JSON. Every call needs to be signed in. Opening |
| 177 | [mcp.g1t.sh](https://mcp.g1t.sh) in a browser shows what the server is, how |
| 178 | to connect, and the tools it offers. |
| 179 | |
| 180 | A client that supports MCP authorization needs only the URL. An |
| 181 | unauthenticated request is answered with `401` and a pointer to |
| 182 | `https://mcp.g1t.sh/.well-known/oauth-protected-resource`, from which the |
| 183 | client finds g1t's authorization server, registers itself, and sends you to |
| 184 | your browser. See [signing in with OAuth](/guides/authentication/#signing-in-with-oauth). |
| 185 | |
| 186 | A client that does not can send `Authorization: Bearer <token>` with an |
| 187 | access token. A client that asks for scopes sends them in `scope` on the |
| 188 | authorization request; see |
| 189 | [signing in with OAuth](/guides/authentication/#signing-in-with-oauth). |