Skip to content

Where people and agents ship software together. The open-source git platform for the whole job: issues, agents, checks and deploys to the edge.

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