Docs worth reading, and kept that way
Redesign the docs in g1t's own look: the cube in the header, a sidebar grouped by what people come to do, quieter type, lavender only as the accent, and a home page that starts from four paths instead of a list. The API reference gets the same header. Split the long pages into guides that each own one thing: handing off an outcome, the merge queue, talking to agents, sessions and why-blame, workspaces, usage and billing, and the MCP tools. Each says only what the code does. answer_message gets a REST route, POST /repos/{owner}/{name}/messages/{id}/answer, so every operation has one again. llms.txt covers plans, the merge queue, steering, agents asking each other, and the session hook, and links the new pages. CONTRIBUTING.md makes it a rule: a change ships with its docs.
23 files+1755−3580/23 viewed
| 1 | + | # Contributing to g1t | |
| 2 | + | ||
| 3 | + | g1t is built the way it asks others to build: issues and pull requests on | |
| 4 | + | [g1t.sh/syntaqx/g1t](https://g1t.sh/syntaqx/g1t), checks that prove a change | |
| 5 | + | done, and a merge queue that keeps `main` passing. | |
| 6 | + | ||
| 7 | + | ## A change ships with its docs | |
| 8 | + | ||
| 9 | + | Documentation is part of the product, held to the same bar as the code. | |
| 10 | + | A pull request that changes what someone can do, see or call changes the | |
| 11 | + | docs in the same pull request: | |
| 12 | + | ||
| 13 | + | | If you change | Update | | |
| 14 | + | | --- | --- | | |
| 15 | + | | Something a person does on g1t.sh | The guide for it in `apps/docs/src/content/docs/guides/` | | |
| 16 | + | | An API route, a field, or an MCP tool | `apps/api/src/operations.rs` descriptions (they feed the OpenAPI document and the API reference), `reference/mcp.md`, and any guide that shows the call | | |
| 17 | + | | How agents behave | `guides/g1t-agents.md`, and `apps/web/public/llms.txt` | | |
| 18 | + | | Settings, limits or prices | The page that names them, and the table it is in | | |
| 19 | + | | A new feature | A section in the guide that owns it, linked from the docs home if it is a new task | | |
| 20 | + | ||
| 21 | + | The style, in short: plain sentences, second person, no marketing words, | |
| 22 | + | sentence-case headings, a numbered list for steps, a table for options, and | |
| 23 | + | every API mention with its exact route or tool name. Examples are copyable | |
| 24 | + | and real. Nothing is documented that the code does not do. | |
| 25 | + | ||
| 26 | + | Check the docs build before you push: | |
| 27 | + | ||
| 28 | + | ```sh | |
| 29 | + | cd apps/docs && npm run build | |
| 30 | + | ``` | |
| 31 | + | ||
| 32 | + | ## Before you push | |
| 33 | + | ||
| 34 | + | - `cargo test` in the crate or service you changed. | |
| 35 | + | - `npx tsc -b --force` in `apps/web` (the incremental build misses changes | |
| 36 | + | in `packages/contracts`). | |
| 37 | + | - Look at what you changed in a browser. Screenshots catch what type | |
| 38 | + | checks do not. |
| 60 | 60 | &[], | |
| 61 | 61 | ), | |
| 62 | 62 | route( | |
| 63 | + | "POST", | |
| 64 | + | "/repos/:owner/:name/messages/:id/answer", | |
| 65 | + | Op::AnswerMessage, | |
| 66 | + | &[], | |
| 67 | + | ), | |
| 68 | + | route( | |
| 63 | 69 | "GET", | |
| 64 | 70 | "/repos/:owner/:name/events", | |
| 65 | 71 | Op::ListEvents, | |
| 238 | 244 | if let (Some(owner), Some(name)) = (param("owner"), param("name")) { | |
| 239 | 245 | input.insert("repo".to_owned(), Value::String(format!("{owner}/{name}"))); | |
| 240 | 246 | } | |
| 241 | − | if let Some(plan) = param("plan") { | |
| 242 | − | input.insert("plan".to_owned(), Value::String(plan.to_owned())); | |
| 247 | + | for key in ["plan", "id"] { | |
| 248 | + | if let Some(value) = param(key) { | |
| 249 | + | input.insert(key.to_owned(), Value::String(value.to_owned())); | |
| 250 | + | } | |
| 243 | 251 | } | |
| 244 | 252 | if let Some(number) = param("number") { | |
| 245 | 253 | // Not a number: zero, which no issue or pull request has. |
| 7 | 7 | integrations: [ | |
| 8 | 8 | starlight({ | |
| 9 | 9 | title: 'g1t docs', | |
| 10 | − | description: 'Guides and reference for g1t, the git forge built for AI scale.', | |
| 10 | + | description: 'Guides and reference for g1t, the git forge for teams of agents.', | |
| 11 | + | components: { | |
| 12 | + | SiteTitle: './src/components/SiteTitle.astro', | |
| 13 | + | SocialIcons: './src/components/SocialIcons.astro', | |
| 14 | + | }, | |
| 15 | + | expressiveCode: { | |
| 16 | + | themes: ['github-dark-default'], | |
| 17 | + | styleOverrides: { | |
| 18 | + | borderRadius: '0.75rem', | |
| 19 | + | borderColor: 'var(--g1t-line)', | |
| 20 | + | codeBackground: 'var(--g1t-surface)', | |
| 21 | + | codeFontSize: '0.8125rem', | |
| 22 | + | frames: { | |
| 23 | + | editorBackground: 'var(--g1t-surface)', | |
| 24 | + | terminalBackground: 'var(--g1t-surface)', | |
| 25 | + | terminalTitlebarBackground: 'var(--g1t-raised)', | |
| 26 | + | terminalTitlebarBorderBottomColor: 'var(--g1t-line)', | |
| 27 | + | editorTabBarBackground: 'var(--g1t-raised)', | |
| 28 | + | shadowColor: 'transparent', | |
| 29 | + | }, | |
| 30 | + | }, | |
| 31 | + | }, | |
| 11 | 32 | logo: { src: '@g1t/theme/mark.svg', alt: '' }, | |
| 12 | 33 | favicon: '/favicon.svg', | |
| 13 | 34 | customCss: ['@g1t/theme/tokens.css', './src/styles/g1t.css'], | |
| 38 | 59 | label: 'Get started', | |
| 39 | 60 | items: [ | |
| 40 | 61 | { label: 'Quickstart', slug: 'quickstart' }, | |
| 41 | − | { label: 'Concepts', slug: 'concepts/overview' }, | |
| 62 | + | { label: 'How g1t works', slug: 'concepts/overview' }, | |
| 63 | + | ], | |
| 64 | + | }, | |
| 65 | + | { | |
| 66 | + | label: 'Agents', | |
| 67 | + | items: [ | |
| 68 | + | { label: 'g1t agents', slug: 'guides/g1t-agents' }, | |
| 69 | + | { label: 'Outcomes and plans', slug: 'guides/outcomes' }, | |
| 70 | + | { label: 'Talking to agents', slug: 'guides/talking-to-agents' }, | |
| 71 | + | { label: 'Bring your own agent', slug: 'guides/bring-your-own-agent' }, | |
| 72 | + | ], | |
| 73 | + | }, | |
| 74 | + | { | |
| 75 | + | label: 'Landing changes', | |
| 76 | + | items: [ | |
| 77 | + | { label: 'The merge queue', slug: 'guides/merge-queue' }, | |
| 78 | + | { label: 'Sessions and why-blame', slug: 'guides/why-blame' }, | |
| 42 | 79 | { label: 'Forks and branches', slug: 'concepts/forks' }, | |
| 43 | 80 | ], | |
| 44 | 81 | }, | |
| 45 | 82 | { | |
| 46 | − | label: 'Guides', | |
| 83 | + | label: 'Workspaces', | |
| 47 | 84 | items: [ | |
| 48 | − | { label: 'Accounts and authentication', slug: 'guides/authentication' }, | |
| 85 | + | { label: 'Accounts and sign-in', slug: 'guides/authentication' }, | |
| 86 | + | { label: 'Workspaces and tokens', slug: 'guides/workspaces' }, | |
| 87 | + | { label: 'Usage and billing', slug: 'guides/usage-and-billing' }, | |
| 49 | 88 | { label: 'Git', slug: 'guides/git' }, | |
| 50 | − | { label: 'g1t agents', slug: 'guides/g1t-agents' }, | |
| 51 | − | { label: 'Bring your own agent', slug: 'guides/bring-your-own-agent' }, | |
| 52 | 89 | ], | |
| 53 | 90 | }, | |
| 54 | 91 | { | |
| 56 | 93 | items: [ | |
| 57 | 94 | { label: 'API overview', slug: 'reference/api' }, | |
| 58 | 95 | { label: 'API reference', link: '/api/reference/', attrs: { target: '_self' } }, | |
| 96 | + | { label: 'MCP tools', slug: 'reference/mcp' }, | |
| 59 | 97 | { label: 'OpenAPI document', link: 'https://api.g1t.sh/openapi.json' }, | |
| 60 | 98 | { label: 'llms.txt', link: 'https://g1t.sh/llms.txt' }, | |
| 61 | − | ], | |
| 62 | − | }, | |
| 63 | − | { | |
| 64 | − | label: 'g1t', | |
| 65 | − | items: [ | |
| 66 | − | { label: 'Back to g1t.sh', link: 'https://g1t.sh/' }, | |
| 67 | 99 | ], | |
| 68 | 100 | }, | |
| 69 | 101 | ], |
| 1 | + | --- | |
| 2 | + | // The cube, the name and "Docs": the same mark as g1t.sh, so the two read | |
| 3 | + | // as one product. | |
| 4 | + | --- | |
| 5 | + | ||
| 6 | + | <a href="/" class="g1t-title" aria-label="g1t docs home"> | |
| 7 | + | <svg viewBox="0 0 32 32" aria-hidden="true"> | |
| 8 | + | <path d="M16 2.5 28 9.4 16 16.3 4 9.4Z" fill="currentColor"></path> | |
| 9 | + | <path d="M4 10.9 15.3 17.4V30.2L4 23.7Z" fill="currentColor" fill-opacity="0.55"></path> | |
| 10 | + | <path d="M28 10.9 16.7 17.4V30.2L28 23.7Z" fill="currentColor" fill-opacity="0.25"></path> | |
| 11 | + | </svg> | |
| 12 | + | <span class="g1t-title-name">g1t</span> | |
| 13 | + | <span class="g1t-title-docs">Docs</span> | |
| 14 | + | </a> | |
| 15 | + | ||
| 16 | + | <style> | |
| 17 | + | .g1t-title { | |
| 18 | + | display: inline-flex; | |
| 19 | + | align-items: center; | |
| 20 | + | gap: 0.55rem; | |
| 21 | + | color: var(--g1t-fg); | |
| 22 | + | text-decoration: none; | |
| 23 | + | } | |
| 24 | + | svg { | |
| 25 | + | width: 1.35rem; | |
| 26 | + | height: 1.35rem; | |
| 27 | + | } | |
| 28 | + | .g1t-title-name { | |
| 29 | + | font-size: 1.05rem; | |
| 30 | + | font-weight: 700; | |
| 31 | + | letter-spacing: -0.035em; | |
| 32 | + | } | |
| 33 | + | .g1t-title-docs { | |
| 34 | + | border-radius: 999px; | |
| 35 | + | padding: 0.1rem 0.5rem; | |
| 36 | + | font-size: 0.72rem; | |
| 37 | + | font-weight: 500; | |
| 38 | + | color: var(--g1t-muted); | |
| 39 | + | box-shadow: inset 0 0 0 1px var(--g1t-line-strong); | |
| 40 | + | } | |
| 41 | + | </style> |
| 1 | + | --- | |
| 2 | + | // The header's right side: where people go from the docs, then the source. | |
| 3 | + | --- | |
| 4 | + | ||
| 5 | + | <nav class="g1t-nav" aria-label="g1t"> | |
| 6 | + | <a href="/api/reference/">API reference</a> | |
| 7 | + | <a href="https://g1t.sh/">g1t.sh</a> | |
| 8 | + | <a href="https://g1t.sh/register" class="g1t-nav-cta">Sign up</a> | |
| 9 | + | <a href="https://github.com/syntaqx/g1t" aria-label="Source on GitHub" class="g1t-nav-icon"> | |
| 10 | + | <svg viewBox="0 0 16 16" aria-hidden="true" fill="currentColor"> | |
| 11 | + | <path | |
| 12 | + | d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z" | |
| 13 | + | ></path> | |
| 14 | + | </svg> | |
| 15 | + | </a> | |
| 16 | + | </nav> | |
| 17 | + | ||
| 18 | + | <style> | |
| 19 | + | .g1t-nav { | |
| 20 | + | display: flex; | |
| 21 | + | align-items: center; | |
| 22 | + | gap: 0.25rem; | |
| 23 | + | } | |
| 24 | + | a { | |
| 25 | + | border-radius: 0.4rem; | |
| 26 | + | padding: 0.3rem 0.6rem; | |
| 27 | + | font-size: 0.85rem; | |
| 28 | + | color: var(--g1t-muted); | |
| 29 | + | text-decoration: none; | |
| 30 | + | transition: color 0.15s, background 0.15s; | |
| 31 | + | } | |
| 32 | + | a:hover { | |
| 33 | + | background: var(--g1t-raised); | |
| 34 | + | color: var(--g1t-fg); | |
| 35 | + | } | |
| 36 | + | .g1t-nav-cta { | |
| 37 | + | margin-left: 0.25rem; | |
| 38 | + | background: var(--g1t-fg); | |
| 39 | + | color: var(--g1t-bg); | |
| 40 | + | font-weight: 500; | |
| 41 | + | } | |
| 42 | + | .g1t-nav-cta:hover { | |
| 43 | + | background: #fff; | |
| 44 | + | color: var(--g1t-bg); | |
| 45 | + | } | |
| 46 | + | .g1t-nav-icon { | |
| 47 | + | display: inline-flex; | |
| 48 | + | padding: 0.4rem; | |
| 49 | + | } | |
| 50 | + | .g1t-nav-icon svg { | |
| 51 | + | width: 1rem; | |
| 52 | + | height: 1rem; | |
| 53 | + | } | |
| 54 | + | @media (max-width: 50rem) { | |
| 55 | + | a:not(.g1t-nav-icon):not(.g1t-nav-cta) { | |
| 56 | + | display: none; | |
| 57 | + | } | |
| 58 | + | } | |
| 59 | + | </style> |
| 1 | 1 | --- | |
| 2 | − | title: Concepts | |
| 3 | − | description: Issues, pull requests, merging, sessions and events. | |
| 2 | + | title: How g1t works | |
| 3 | + | description: What g1t is for, and how issues, pull requests, checks, review, merging and sessions fit together. | |
| 4 | 4 | --- | |
| 5 | 5 | ||
| 6 | − | g1t is ordinary git: repositories, commits, branches, clone, push and pull all | |
| 7 | − | work as they do anywhere. On top of that it has the two things you already | |
| 8 | − | know from other forges, **issues** and **pull requests**, built so that many | |
| 9 | − | agents can work on the same issue at once. | |
| 6 | + | g1t is a git forge for teams of agents. You hand g1t an outcome, and a team | |
| 7 | + | of agents converges it onto `main`: each change is made in a pull request | |
| 8 | + | of its own, checked in a clean sandbox, reviewed, revised and merged under | |
| 9 | + | your repository's rules. People work exactly as they would on GitHub, with | |
| 10 | + | the same repositories, issues, pull requests and reviews, alongside the | |
| 11 | + | agents. | |
| 10 | 12 | ||
| 13 | + | Underneath it is ordinary git: repositories, commits, branches, clone, push | |
| 14 | + | and pull all work as they do anywhere. On top of that it has the two things | |
| 15 | + | you already know from other forges, **issues** and **pull requests**, built | |
| 16 | + | so that many agents can work at once without getting in each other's way. | |
| 17 | + | ||
| 11 | 18 | | | What it is | | |
| 12 | 19 | | --- | --- | | |
| 20 | + | | **Plan** | An outcome, split by an agent into issues and the order they land in. See [hand off an outcome](/guides/outcomes/). | | |
| 13 | 21 | | **Issue** | What should change: a bug, a feature, a question. | | |
| 14 | 22 | | **Pull request** | A proposed change, in its own fork or on a branch. Usually made for an issue. | | |
| 15 | 23 | | **Session** | The record of how a pull request was made: prompts, reasoning, tool calls. | | |
| 132 | 140 | member of the workspace chooses to merge anyway. | |
| 133 | 141 | ||
| 134 | 142 | Running checks is in preview: they run in repositories of the workspaces | |
| 135 | − | g1t's sandboxes are enabled for. | |
| 143 | + | g1t's sandboxes are enabled for. See [the preview](/guides/usage-and-billing/#the-preview). | |
| 136 | 144 | ||
| 137 | 145 | ## Review | |
| 138 | 146 | ||
| 149 | 157 | on a pull request you opened, and that holds for agents too: one agent can | |
| 150 | 158 | review another's work, but not its own. | |
| 151 | 159 | ||
| 160 | + | Requesting changes on a g1t agent's pull request sends the agent back to | |
| 161 | + | make them. See [talk to agents](/guides/talking-to-agents/#ask-for-changes). | |
| 162 | + | ||
| 152 | 163 | ## Overlap | |
| 153 | 164 | ||
| 154 | 165 | When many changes are in flight, some touch the same files. g1t keeps track | |
| 171 | 182 | ## Merging | |
| 172 | 183 | ||
| 173 | 184 | A member of the repository's workspace merges a pull request once it is | |
| 174 | − | marked ready and its checks have passed. Merging moves `main` to the pull request's head commit. | |
| 185 | + | marked ready and its checks have passed. Merging moves `main` to the pull | |
| 186 | + | request's head commit, or, in a repository that merges through | |
| 187 | + | [the merge queue](/guides/merge-queue/), adds it to the queue. | |
| 175 | 188 | ||
| 176 | 189 | A pull request can only merge if it contains everything already on `main`. | |
| 177 | 190 | If something else landed first, merging is refused and the pull request is | |
| 186 | 199 | pull requests are in flight. | |
| 187 | 200 | ||
| 188 | 201 | ## The merge queue | |
| 189 | − | ||
| 190 | − | Merging one pull request at a time, each caught up with `main`, keeps every | |
| 191 | − | merge clean as text. It does not prove the result works: two changes can | |
| 192 | − | merge without a conflict and still break each other. A repository that | |
| 193 | − | turns on **Merge through a queue** closes that gap. | |
| 194 | 202 | ||
| 195 | − | With the queue on, merging adds a pull request to the queue instead of | |
| 196 | − | changing `main`. g1t then tests up to four at a time, speculatively, each in | |
| 197 | − | its own sandbox and all at once: | |
| 198 | − | ||
| 199 | − | | Entry | Tested as | | |
| 200 | − | | --- | --- | | |
| 201 | − | | 1st | `main` + #41 | | |
| 202 | − | | 2nd | `main` + #41 + #44 | | |
| 203 | − | | 3rd | `main` + #41 + #44 + #46 | | |
| 204 | − | ||
| 205 | − | Each tested state runs the acceptance checks of every pull request in it, | |
| 206 | − | and the checks of the issues already completed: once an issue lands, its | |
| 207 | − | checks become part of what `main` promises, and every later change is held | |
| 208 | − | to them. A change that breaks something that landed before it is caught | |
| 209 | − | here, even when it merges without a conflict. A check that was already | |
| 210 | − | failing on `main` before the change is run on `main` alone to tell, and is | |
| 211 | − | not held against it. Entries land in | |
| 212 | − | order: `main` moves to an entry's tested state once it passed and | |
| 213 | − | everything ahead of it has landed. `main` only ever holds a state whose | |
| 214 | − | checks passed. | |
| 215 | − | ||
| 216 | − | An entry that fails, or does not merge cleanly with what is ahead of it, | |
| 217 | − | leaves the queue. Its pull request gets a failed check run showing the | |
| 218 | − | combination it failed in. A g1t agent's pull request is then sent back | |
| 219 | − | automatically, starting from the `main` it will land on, and joins the | |
| 220 | − | queue again once it passes. The entries behind it are tested again without | |
| 221 | − | it. | |
| 222 | − | ||
| 223 | − | The **Merge queue** page shows each entry, what it is being tested | |
| 224 | − | together with, and how that went. Agents read it through | |
| 225 | − | `get_merge_queue`. | |
| 226 | − | ||
| 227 | − | ## Sessions | |
| 228 | − | ||
| 229 | − | A session is the record of how a pull request was made: the prompt the agent | |
| 230 | − | was given, its messages, the tools it called and what they returned. | |
| 231 | − | ||
| 232 | − | Each session entry is stored with the fork's head commit at the time it was | |
| 233 | − | recorded. That link is what lets g1t show the reasoning behind a change | |
| 234 | − | rather than only the change. | |
| 235 | − | ||
| 236 | − | Agents record their own session through the | |
| 237 | − | [`record_session`](/guides/bring-your-own-agent/) tool or the API. | |
| 238 | − | ||
| 239 | − | ## Why a line is the way it is | |
| 240 | − | ||
| 241 | − | Every file can be shown with **Blame**: beside each run of lines, the commit | |
| 242 | − | that last changed it. Pick a line and g1t shows why it is the way it is: | |
| 203 | + | Merging one pull request at a time keeps every merge clean as text, but two | |
| 204 | + | changes can merge without a conflict and still break each other. A | |
| 205 | + | repository that turns on **Merge through a queue** tests each pull request | |
| 206 | + | together with the ones ahead of it, along with the checks of every issue | |
| 207 | + | already completed, and `main` only moves to a state whose checks passed. | |
| 208 | + | See [merge queue](/guides/merge-queue/). | |
| 243 | 209 | ||
| 244 | − | - the commit that last changed it; | |
| 245 | − | - the pull request it arrived in, and who or what wrote it; | |
| 246 | − | - the issue that asked for it; | |
| 247 | − | - when an agent wrote it, the agent's own account of the change and the | |
| 248 | − | commands it ran, taken from its session. | |
| 210 | + | ## Sessions and why-blame | |
| 249 | 211 | ||
| 250 | − | Blame follows every parent of a merge, so a line that came into a pull | |
| 251 | − | request when it caught up with `main` is credited to whoever wrote it on | |
| 252 | − | `main`, not to the merge. | |
| 253 | − | ||
| 254 | − | Every commit has a page of its own, `/<workspace>/<repo>/commit/<hash>`, | |
| 255 | − | with its diff, its parents and the pull request it arrived in. | |
| 212 | + | A session is the record of how a pull request was made: the prompt the | |
| 213 | + | agent was given, its reasoning, the tools it called and what they returned. | |
| 214 | + | Each entry is tied to the commit that was the head when it was recorded, so | |
| 215 | + | **Blame** on any file can show not only the commit that last changed a | |
| 216 | + | line, but the pull request and issue it came from and the agent's own | |
| 217 | + | account of the change. See [sessions and why-blame](/guides/why-blame/). | |
| 256 | 218 | ||
| 257 | 219 | ## Events | |
| 258 | 220 | ||
| 269 | 231 | - **g1t agents for everyone.** g1t can put its own agents on an issue, each | |
| 270 | 232 | in a sandbox. This is in preview and enabled for selected workspaces; | |
| 271 | 233 | anyone can sign up, host repositories and bring their own agent today. | |
| 234 | + | See [the preview](/guides/usage-and-billing/#the-preview). |
| 1 | 1 | --- | |
| 2 | 2 | title: Accounts and authentication | |
| 3 | − | description: Accounts, email confirmation, access tokens and password reset. | |
| 3 | + | description: Accounts, email confirmation, personal access tokens, OAuth, signing in from a tool, and password reset. | |
| 4 | 4 | --- | |
| 5 | 5 | ||
| 6 | 6 | ## Creating an account | |
| 22 | 22 | use the banner at the top of the site. | |
| 23 | 23 | ||
| 24 | 24 | ## Workspaces | |
| 25 | − | ||
| 26 | − | A workspace owns repositories and is the first part of their address: | |
| 27 | − | `g1t.sh/<workspace>/<repo>`. There is one kind. A workspace for just you and | |
| 28 | − | one for a company are the same thing with a different number of members, so | |
| 29 | − | there is no separate notion of an organization. | |
| 30 | 25 | ||
| 31 | − | Your account does not own repositories itself. After confirming your email | |
| 32 | − | the first thing you do is create a workspace, and repositories go in it. | |
| 33 | − | You can belong to up to ten. | |
| 34 | − | ||
| 35 | − | Usernames and workspaces share one set of names, so a name means the same | |
| 36 | − | thing wherever it appears. Your username is reserved for you: only you can | |
| 37 | − | create a workspace with that name, and nobody can register a username that | |
| 38 | − | is already a workspace. | |
| 39 | − | ||
| 40 | − | | Role | Can | | |
| 41 | − | | --- | --- | | |
| 42 | − | | Member | Create repositories, push, manage issues, merge pull requests. | | |
| 43 | − | | Owner | Everything a member can, and manage members, the workspace's access tokens and its details. | | |
| 44 | − | ||
| 45 | − | A workspace's page, `g1t.sh/<workspace>`, shows its repositories and the | |
| 46 | − | pull requests in progress across them. Members also see **People** and | |
| 47 | − | **Access tokens** there, and owners **Settings**. | |
| 26 | + | Your account does not own repositories itself: a workspace does. After | |
| 27 | + | confirming your email, the first thing you do is create one. Workspaces, | |
| 28 | + | their members and roles, and the access tokens that belong to a workspace | |
| 29 | + | are covered in [workspaces](/guides/workspaces/). | |
| 48 | 30 | ||
| 49 | 31 | ## Access tokens | |
| 50 | 32 | ||
| 62 | 44 | seen it. | |
| 63 | 45 | ||
| 64 | 46 | A token has the full rights of your account. Scoped tokens are planned. | |
| 65 | − | ||
| 66 | − | ### Workspace access tokens | |
| 67 | 47 | ||
| 68 | − | A workspace has access tokens of its own, for CI, integrations and agents | |
| 69 | − | that work for a team. They replace the shared "service account" other | |
| 70 | − | forges need: there is no extra account to create, pay for or lose the | |
| 71 | − | password to. | |
| 72 | − | ||
| 73 | − | | | Personal token | Workspace token | | |
| 74 | − | | --- | --- | --- | | |
| 75 | − | | Belongs to | You | The workspace | | |
| 76 | − | | Acts as | You | The workspace: its name is the author of what it does | | |
| 77 | − | | Can reach | Every workspace you belong to | That workspace only | | |
| 78 | − | | Can do | Everything you can | What a member can; it cannot manage people, tokens or workspaces | | |
| 79 | − | | When its creator leaves | Stops working | Keeps working | | |
| 80 | − | | Created by | You, in Settings | An owner, under **Access tokens** on the workspace's page | | |
| 81 | − | ||
| 82 | − | They are the same kind of token and are sent the same way. With git, any | |
| 83 | − | username works; the token is the password. `GET /user` answers with | |
| 84 | − | `"kind": "workspace"` for one, and `"kind": "user"` for a personal token. | |
| 85 | − | ||
| 86 | − | Every member can see a workspace's tokens: the name, who created each and | |
| 87 | − | when it was last used. Only owners can create or delete them. | |
| 48 | + | For CI and integrations that work for a team, a workspace can have tokens | |
| 49 | + | of its own that act as the workspace and keep working when their creator | |
| 50 | + | leaves. See [workspace access tokens](/guides/workspaces/#workspace-access-tokens). | |
| 88 | 51 | ||
| 89 | 52 | ## Signing in with OAuth | |
| 90 | 53 |
| 30 | 30 | ``` | |
| 31 | 31 | ||
| 32 | 32 | Ask Claude Code to list the open issues on a repository, or to work on one, | |
| 33 | − | and it will use the tools below. | |
| 33 | + | and it will use g1t's tools. [MCP tools](/reference/mcp/) lists every one. | |
| 34 | 34 | ||
| 35 | 35 | ### Recording sessions automatically | |
| 36 | 36 | ||
| 74 | 74 | into the fork and push. The pull request can then be merged. | |
| 75 | 75 | ||
| 76 | 76 | ## Tools | |
| 77 | − | ||
| 78 | − | Repositories are always given as `owner/name`. Issues and pull requests are | |
| 79 | − | given as the repository and a `number`; the two share one sequence, so a | |
| 80 | − | number names exactly one of them. | |
| 81 | 77 | ||
| 82 | − | | Tool | What it does | | |
| 83 | − | | --- | --- | | |
| 84 | − | | `whoami` | The account the token belongs to, and its workspaces. | | |
| 85 | − | | `create_workspace` | Create a workspace. | | |
| 86 | − | | `list_repos` | Repositories you can see, optionally filtered by a query. | | |
| 87 | − | | `get_repo` | One repository's details. | | |
| 88 | − | | `create_repo` | Create a repository in one of your workspaces. | | |
| 89 | − | | `update_repo` | Change its description or visibility, or protect its default branch. | | |
| 90 | − | | `get_repo_settings` | How a repository handles pull requests. | | |
| 91 | − | | `update_repo_settings` | Change the approvals a merge needs and how g1t's agents are reviewed and merged. | | |
| 92 | − | | `get_merge_queue` | The pull requests waiting to land, each with the state it is tested in. | | |
| 93 | − | | `message_agent` | Send the agent on a pull request a message; an agent asks another a `question` or hands it work (`handoff`), giving its own pull request as `from_number`. | | |
| 94 | − | | `answer_message` | Answer a question or a handoff another agent sent you, by its id; decline a handoff that is not yours. | | |
| 95 | − | | `list_issues` | Issues on a repository, by state and label. | | |
| 96 | − | | `get_issue` | An issue with its comments and every pull request made for it. | | |
| 97 | − | | `create_issue` | Open an issue, with labels and acceptance checks. | | |
| 98 | − | | `update_issue` | Change an issue's title, description or labels. | | |
| 99 | − | | `close_issue` | Close an issue as completed or not planned. | | |
| 100 | − | | `reopen_issue` | Reopen a closed issue. | | |
| 101 | − | | `plan_work` | Have an agent read the repository and turn an outcome into issues with their dependencies. | | |
| 102 | − | | `get_plan` | Read a plan and what it proposes. | | |
| 103 | − | | `apply_plan` | Open a plan's issues and, optionally, put g1t agents on them in dependency order. | | |
| 104 | − | | `assign_issue` | Assign an issue to the g1t agent, which opens a pull request and sees it through. | | |
| 105 | − | | `list_labels` | The labels in use on a repository. | | |
| 106 | − | | `add_comment` | Comment on an issue or a pull request, or on one line of a pull request's change. | | |
| 107 | − | | `review_pull_request` | Approve a pull request or request changes. | | |
| 108 | − | | `list_pull_requests` | Pull requests on a repository, open or closed. | | |
| 109 | − | | `get_pull_request` | A pull request's status, comments, reviews, issue, and the result of its acceptance checks. | | |
| 110 | − | | `create_pull_request` | Open a draft pull request with a fork, or one from a branch already pushed. | | |
| 111 | − | | `record_session` | Append prompts, messages and tool calls to the session. | | |
| 112 | − | | `read_session` | Read a pull request's recorded session. | | |
| 113 | − | | `mark_pull_request_ready` | Mark a draft ready for review, with a summary. | | |
| 114 | − | | `close_pull_request` | Close a pull request without merging. | | |
| 115 | − | | `get_pull_request_changes` | The files a pull request changes, with line-by-line diffs. | | |
| 116 | − | | `merge_pull_request` | Land a pull request on `main` and resolve its issue. Workspace members only. | | |
| 117 | − | | `list_events` | A repository's timeline, newest first. | | |
| 78 | + | Repositories are given as `owner/name`, and issues and pull requests as the | |
| 79 | + | repository and a `number`. [MCP tools](/reference/mcp/) lists every tool | |
| 80 | + | with its required inputs and its REST route. | |
| 118 | 81 | ||
| 119 | 82 | ## Staying out of each other's way | |
| 120 | 83 | ||
| 128 | 91 | was made. If it has, pull `main` into the fork and push before asking for a | |
| 129 | 92 | merge. | |
| 130 | 93 | ||
| 131 | − | ## Asking each other | |
| 94 | + | ## Talking to g1t agents | |
| 132 | 95 | ||
| 133 | − | Agents working at the same time can talk through g1t. An agent asks the agent | |
| 134 | − | on another pull request a question, or hands it work that belongs there, | |
| 135 | − | with `message_agent`, naming its own pull request as `from_number`. The | |
| 136 | − | other agent receives it at its next step and replies with | |
| 137 | − | `answer_message`, which reaches the asking agent at its next step in turn. | |
| 138 | − | If the agent asked is not at work, the reply to `message_agent` says so and | |
| 139 | − | points at its change to read instead. Every exchange shows on the outcome | |
| 140 | − | page with where it stands: waiting, read, answered or declined. | |
| 96 | + | Your agent can send the g1t agent working on a pull request a message with | |
| 97 | + | `message_agent`; it arrives at that agent's next step. g1t agents also ask | |
| 98 | + | each other questions and hand each other work. See | |
| 99 | + | [talk to agents](/guides/talking-to-agents/). | |
| 141 | 100 | ||
| 142 | 101 | ## Reviewing as an agent | |
| 143 | 102 | ||
| 157 | 116 | ||
| 158 | 117 | ## Session entries | |
| 159 | 118 | ||
| 160 | − | `record_session` takes a list of entries. Each has a `kind` and `text`, and | |
| 161 | − | tool entries also carry the `tool` name. | |
| 162 | − | ||
| 163 | − | | Kind | Use it for | | |
| 164 | − | | --- | --- | | |
| 165 | − | | `prompt` | What the agent was asked to do. | | |
| 166 | − | | `message` | The agent's own reasoning or explanation. | | |
| 167 | − | | `tool_call` | A tool the agent ran, and with what input. | | |
| 168 | − | | `tool_result` | What the tool returned. | | |
| 169 | − | | `note` | Anything else worth keeping. | | |
| 119 | + | `record_session` takes a list of entries. Each has a `kind` (`prompt`, | |
| 120 | + | `message`, `tool_call`, `tool_result` or `note`) and `text`, and tool | |
| 121 | + | entries also carry the `tool` name. See | |
| 122 | + | [sessions and why-blame](/guides/why-blame/#sessions) for what each kind is | |
| 123 | + | for and how sessions explain each line. | |
| 170 | 124 | ||
| 171 | 125 | Do not put secrets in a session. Sessions are as visible as the repository. | |
| 172 | 126 |
| 10 | 10 | each to its own agent, all working at once. | |
| 11 | 11 | ||
| 12 | 12 | g1t agents are paid for by the workspace they work for; see | |
| 13 | − | [what it costs](#what-it-costs). Everyone can also | |
| 13 | + | [usage and billing](/guides/usage-and-billing/). Everyone can also | |
| 14 | 14 | [bring their own agent](/guides/bring-your-own-agent/), which costs | |
| 15 | 15 | nothing on g1t. | |
| 16 | 16 | ||
| 17 | + | To hand over a whole outcome rather than one issue at a time, have an agent | |
| 18 | + | plan it first: see [hand off an outcome](/guides/outcomes/). | |
| 19 | + | ||
| 17 | 20 | ## Assigning agents | |
| 18 | 21 | ||
| 19 | 22 | One issue: | |
| 59 | 62 | summary as its description. | |
| 60 | 63 | ||
| 61 | 64 | Everything it reads, runs and decides is recorded in the pull request's | |
| 62 | − | **Session** as it happens. The **Changes** tab shows the resulting diff. | |
| 65 | + | **Session** as it happens; see [sessions and why-blame](/guides/why-blame/). | |
| 66 | + | The **Changes** tab shows the resulting diff. | |
| 63 | 67 | ||
| 64 | 68 | If an agent fails, or finishes without changing anything, its pull request | |
| 65 | 69 | is closed and its session says why. | |
| 110 | 114 | | Review by a second agent | On | Off leaves review to people. | | |
| 111 | 115 | | Revisions before asking you | 2 | How often an agent is sent back before g1t stops. | | |
| 112 | 116 | | Merge automatically when ready | Off | Lands a g1t agent's pull request once every rule is met. | | |
| 113 | − | | Merge through a queue | Off | Merging tests a pull request together with those ahead of it; `main` only moves to a combination that passed. See [the merge queue](/concepts/overview/#the-merge-queue). | | |
| 117 | + | | Merge through a queue | Off | Merging tests a pull request together with those ahead of it; `main` only moves to a combination that passed. See [merge queue](/guides/merge-queue/). | | |
| 114 | 118 | ||
| 115 | 119 | A g1t agent's pull request follows the same rules as anyone's. If the | |
| 116 | 120 | repository wants approvals from people, it waits for them, and shows | |
| 117 | 121 | **Needs you** until they arrive. | |
| 118 | 122 | ||
| 119 | − | ### Talking to an agent while it works | |
| 123 | + | ### Talking to an agent | |
| 120 | 124 | ||
| 121 | − | While a g1t agent is making or revising a change, its pull request shows | |
| 122 | − | **Message the agent**. Write a correction, a hint or a change of plan; the | |
| 123 | − | agent reads it at its next step, without starting over, and it is | |
| 124 | − | recorded in the session. A message sent as the agent is finishing still | |
| 125 | − | reaches it: the agent keeps going to act on it. Your own agent can send | |
| 126 | − | one through the `message_agent` tool or `POST | |
| 127 | − | /repos/{owner}/{name}/pulls/{number}/messages`. | |
| 128 | − | ||
| 129 | − | ### Asking the agent for changes | |
| 125 | + | While a g1t agent works, you can steer it with **Message the agent** on its | |
| 126 | + | pull request; it reads the message at its next step, without starting | |
| 127 | + | over. Once it is done, a review with **Request changes** sends it back to | |
| 128 | + | make them, and the checks and review run again. g1t agents working at the | |
| 129 | + | same time can also ask each other questions and hand each other work. See | |
| 130 | + | [talk to agents](/guides/talking-to-agents/). | |
| 130 | 131 | ||
| 131 | − | Review a g1t agent's pull request the way you would anyone's: comment on | |
| 132 | − | lines, then submit **Request changes** with what you want. The agent is | |
| 133 | − | sent back with your review, your comments on lines included, makes the | |
| 134 | − | changes, and the checks and review run again on the result. You do not | |
| 135 | − | need to reassign anything. Each time counts towards **Revisions before | |
| 136 | − | asking you**; past that, g1t stops and the page says so. | |
| 137 | − | ||
| 138 | 132 | ### Merging automatically | |
| 139 | 133 | ||
| 140 | 134 | A repository can land a g1t agent's pull request by itself once it is | |
| 178 | 172 | ||
| 179 | 173 | | Work | Model today | | |
| 180 | 174 | | --- | --- | | |
| 181 | − | | Making a change for an issue | Claude Sonnet 5.5 | | |
| 175 | + | | Making a change for an issue, and revising it | Claude Sonnet 5.5 | | |
| 182 | 176 | | Reviewing a pull request | Claude Sonnet 5.5 | | |
| 183 | 177 | | Catching up with `main` and resolving conflicts | Claude Sonnet 5.5 | | |
| 178 | + | | Planning an outcome | Claude Sonnet 5.5 | | |
| 184 | 179 | ||
| 185 | 180 | Every session opens with a note naming the model that ran, and an agent's | |
| 186 | 181 | review says which model wrote it, so what you got is always on the record. | |
| 203 | 198 | ||
| 204 | 199 | | Setting | What it does | | |
| 205 | 200 | | --- | --- | | |
| 206 | − | | `AGENT_ROUTES` | The model for each kind of work: `implement`, `review` and `update`. | | |
| 201 | + | | `AGENT_ROUTES` | The model for each kind of work: `implement`, `review`, `update` and `plan`. | | |
| 207 | 202 | | `AI_GATEWAY_ID` | The gateway to route through. Empty sends requests to the provider directly. | | |
| 208 | 203 | | `AI_GATEWAY_TOKEN` | Secret. Authenticates to the gateway. With the provider's key stored in the gateway, this is the only credential a sandbox gets. | | |
| 209 | 204 | | `ANTHROPIC_API_KEY` | Secret. The provider's key, if the gateway does not hold it. | | |
| 211 | 206 | ## What it costs | |
| 212 | 207 | ||
| 213 | 208 | A workspace pays for the g1t agents that work on its repositories, from | |
| 214 | − | credit it buys in advance. | |
| 215 | − | ||
| 216 | − | - An owner adds credit by card under **Billing** on the workspace's page. | |
| 217 | − | - Each run is charged when it finishes: what the model cost, plus 20%. A | |
| 218 | − | change, a review, a revision and a catch-up that needed an agent are each | |
| 219 | − | a run. Acceptance checks are free. | |
| 220 | − | - The charge goes to the workspace that owns the repository, whoever | |
| 221 | − | assigned the issue, so only its members can put agents to work there. | |
| 222 | − | - With no credit, agents do not start, and assigning an issue says so. | |
| 223 | − | Runs already under way finish, so a balance can dip slightly below zero. | |
| 224 | − | - The statement on the Billing page lists every run with the pull request | |
| 225 | − | it was for, and each pull request's session ends with what its run cost | |
| 226 | − | before the margin. | |
| 227 | − | ||
| 228 | − | There is no subscription and no seat price. A small change costs a few | |
| 229 | − | cents. | |
| 230 | − | ||
| 231 | − | ## Seeing what agents cost | |
| 232 | − | ||
| 233 | − | A workspace's **Usage** page shows what its agents have cost over a period: | |
| 234 | − | spend per day by kind of work (making changes, reviews, revisions, | |
| 235 | − | catching up, planning), and by repository, model and pull request, with | |
| 236 | − | the credit left and how long it lasts at the current rate. The sidebar | |
| 237 | − | shows this month's usage. | |
| 209 | + | credit an owner buys in advance: each run is charged what the model cost, | |
| 210 | + | plus 20%. Acceptance checks are free. With no credit, agents do not start. | |
| 211 | + | The workspace's **Usage** page shows what its agents have cost, by day, | |
| 212 | + | kind of work, repository, model and pull request. See | |
| 213 | + | [usage and billing](/guides/usage-and-billing/). | |
| 238 | 214 | ||
| 239 | 215 | ## What a sandbox has | |
| 240 | 216 | ||
| 247 | 223 | - g1t's own agents, and the sandboxes that run acceptance checks and the | |
| 248 | 224 | merge queue, are enabled for selected workspaces while they are in | |
| 249 | 225 | preview. Everywhere else, everything else works: repositories, issues, | |
| 250 | − | pull requests, review, and your own agent through MCP. | |
| 226 | + | pull requests, review, and your own agent through MCP. See | |
| 227 | + | [the preview](/guides/usage-and-billing/#the-preview). | |
| 251 | 228 | - An agent is given one fork and the issue. Its credential, though, is your | |
| 252 | 229 | account's for the length of the run; credentials limited to the pull | |
| 253 | 230 | request are planned. |
| 41 | 41 | ||
| 42 | 42 | ## Private repositories | |
| 43 | 43 | ||
| 44 | + | A private repository is visible only to members of its workspace. To | |
| 45 | + | everyone else it looks exactly like a repository that does not exist, both | |
| 46 | + | on the site and to git. | |
| 47 | + | ||
| 44 | 48 | ## Protected branches | |
| 45 | 49 | ||
| 46 | 50 | A repository can protect its default branch under **Settings**. Pushing to | |
| 47 | 51 | it is then refused, for members and agents alike, and git says why: | |
| 48 | 52 | ||
| 49 | − | ``` | |
| 53 | + | ```text | |
| 50 | 54 | ! [remote rejected] main -> main (main is protected: push a branch and open a pull request) | |
| 51 | 55 | ``` | |
| 52 | 56 | ||
| 53 | 57 | Changes reach a protected branch only by merging a pull request. The first | |
| 54 | 58 | push to an empty repository is still allowed. | |
| 55 | − | ||
| 56 | − | A private repository is visible only to members of its workspace. To everyone | |
| 57 | − | else it looks | |
| 58 | − | exactly like a repository that does not exist, both on the site and to git. | |
| 59 | 59 | ||
| 60 | 60 | ## Branches | |
| 61 | 61 |
| 1 | + | --- | |
| 2 | + | title: Merge queue | |
| 3 | + | description: Test each pull request together with the ones ahead of it, so main only moves to a state whose checks passed. | |
| 4 | + | --- | |
| 5 | + | ||
| 6 | + | Merging one pull request at a time, each caught up with `main`, keeps every | |
| 7 | + | merge clean as text. It does not prove the result works: two changes can | |
| 8 | + | merge without a conflict and still break each other. With the merge queue | |
| 9 | + | on, a pull request is tested together with everything ahead of it before it | |
| 10 | + | lands, and `main` only ever moves to a state whose checks passed. | |
| 11 | + | ||
| 12 | + | The merge queue runs in g1t's sandboxes, which are in preview and enabled | |
| 13 | + | for selected workspaces. Elsewhere, an entry fails at once with a message | |
| 14 | + | saying so; turn the queue off to merge directly. | |
| 15 | + | ||
| 16 | + | ## Turn it on | |
| 17 | + | ||
| 18 | + | 1. Open the repository's **Settings** tab. You need to be a member of its | |
| 19 | + | workspace. | |
| 20 | + | 2. Turn on **Merge through a queue**. | |
| 21 | + | 3. Save. | |
| 22 | + | ||
| 23 | + | From the API, send `merge_queue` to `PATCH /repos/{owner}/{name}/settings` | |
| 24 | + | (or `update_repo_settings`): | |
| 25 | + | ||
| 26 | + | ```sh | |
| 27 | + | curl -X PATCH https://api.g1t.sh/repos/acme/web/settings \ | |
| 28 | + | -H "Authorization: Bearer $G1T_TOKEN" \ | |
| 29 | + | -H "Content-Type: application/json" \ | |
| 30 | + | -d '{"merge_queue": true}' | |
| 31 | + | ``` | |
| 32 | + | ||
| 33 | + | ## What merging does with the queue on | |
| 34 | + | ||
| 35 | + | Merging a pull request, from its page (**Add to the merge queue**), with | |
| 36 | + | `merge_pull_request`, or with `POST /repos/{owner}/{name}/pulls/{number}/merge`, | |
| 37 | + | adds it to the queue instead of changing `main`. Everything a merge needs | |
| 38 | + | is still checked first: the pull request must be ready for review, its | |
| 39 | + | checks must have passed and it must have the approvals the repository asks | |
| 40 | + | for. Only members of the workspace can add to the queue. Merging a pull | |
| 41 | + | request that is already queued changes nothing. | |
| 42 | + | ||
| 43 | + | The pull request's conversation records who added it, and its page shows | |
| 44 | + | where it is in the queue. A member can take it out with **Remove from the | |
| 45 | + | queue**. Closing a pull request also takes it out. | |
| 46 | + | ||
| 47 | + | ## How entries are tested | |
| 48 | + | ||
| 49 | + | g1t takes up to four entries from the front of the queue and tests them all | |
| 50 | + | at once, speculatively, each in its own sandbox. Each sandbox builds `main` | |
| 51 | + | with that entry and every entry ahead of it merged in, in queue order: | |
| 52 | + | ||
| 53 | + | | Entry | Tested as | | |
| 54 | + | | --- | --- | | |
| 55 | + | | 1st | `main` + #41 | | |
| 56 | + | | 2nd | `main` + #41 + #44 | | |
| 57 | + | | 3rd | `main` + #41 + #44 + #46 | | |
| 58 | + | | 4th | `main` + #41 + #44 + #46 + #47 | | |
| 59 | + | ||
| 60 | + | If every entry passes, the four can land one after another without being | |
| 61 | + | tested again. The next batch starts when nothing is being tested. A batch | |
| 62 | + | that takes longer than 45 minutes is tested again. | |
| 63 | + | ||
| 64 | + | ### What each state is held to | |
| 65 | + | ||
| 66 | + | Each tested state runs: | |
| 67 | + | ||
| 68 | + | - the acceptance checks of every pull request in it; and | |
| 69 | + | - the **contract**: the checks of issues already completed on the | |
| 70 | + | repository, from the 30 most recently closed. Once an issue lands, its | |
| 71 | + | checks become part of what `main` promises, and every later change is | |
| 72 | + | held to them. | |
| 73 | + | ||
| 74 | + | So a change that breaks something that landed before it is caught here, | |
| 75 | + | even when it merges without a conflict and its own checks pass. | |
| 76 | + | ||
| 77 | + | A contract check that fails is run again on `main` alone. If it fails there | |
| 78 | + | too, it was broken already: it is marked as passing with a note, "already | |
| 79 | + | failing on the default branch; not held against this", and does not hold | |
| 80 | + | the change back. | |
| 81 | + | ||
| 82 | + | ## How entries land | |
| 83 | + | ||
| 84 | + | Entries land in order. When an entry has passed and everything ahead of it | |
| 85 | + | has landed, `main` moves to exactly the state that was tested. The issue | |
| 86 | + | closes and the other pull requests for it are superseded, as with any | |
| 87 | + | merge. | |
| 88 | + | ||
| 89 | + | Before landing, g1t checks that nothing has changed underneath: | |
| 90 | + | ||
| 91 | + | - If the pull request was pushed to after it was tested, it and the entries | |
| 92 | + | tested on top of it are tested again. | |
| 93 | + | - If `main` moved outside the queue, every entry is tested again on the new | |
| 94 | + | `main`. | |
| 95 | + | ||
| 96 | + | ## When an entry fails | |
| 97 | + | ||
| 98 | + | An entry fails when its checks fail in the combined state, when it does not | |
| 99 | + | merge cleanly with what is ahead of it, or when the state cannot be built. | |
| 100 | + | It leaves the queue, and: | |
| 101 | + | ||
| 102 | + | 1. Its pull request gets a failed check run. Each command is named with the | |
| 103 | + | state it ran in, such as `cargo test (merge queue, on the default branch | |
| 104 | + | with #41 merged in first)`, and the run says why it failed. A conflict | |
| 105 | + | names the pull request ahead it collided with. | |
| 106 | + | 2. Its conversation records that it was taken out of the queue, and why. | |
| 107 | + | 3. The entries that were tested on top of it are tested again without it. | |
| 108 | + | ||
| 109 | + | A g1t agent's pull request is then sent back to revise, like any failed | |
| 110 | + | check, starting from `main` as it is now. The revision counts towards | |
| 111 | + | **Revisions before asking you**. Once it is ready again, a repository with | |
| 112 | + | **Merge automatically when ready** on adds it to the queue again by itself; | |
| 113 | + | otherwise it waits for a member to merge it again. A pull request you or | |
| 114 | + | your own agent opened is yours to fix and merge again. | |
| 115 | + | ||
| 116 | + | ## The Merge queue page | |
| 117 | + | ||
| 118 | + | Every repository has a **Merge queue** page, at | |
| 119 | + | `g1t.sh/<workspace>/<repo>/queue`, in the repository's sidebar. It | |
| 120 | + | refreshes on its own while anything is queued. | |
| 121 | + | ||
| 122 | + | **In the queue** lists the entries in order, starting from `main`'s commit. | |
| 123 | + | Each shows: | |
| 124 | + | ||
| 125 | + | | | | | |
| 126 | + | | --- | --- | | |
| 127 | + | | State | **Waiting**, **Testing** or **Passed**. | | |
| 128 | + | | Tested as | `main` and the pull requests merged into it, such as `main + #41 + #44`. | | |
| 129 | + | | Checks | How many of the checks passed. | | |
| 130 | + | | Who | The agent or person who made the pull request, and who queued it. | | |
| 131 | + | | Commit | The tested state's commit. | | |
| 132 | + | ||
| 133 | + | **Recently** lists the last 20 that left the queue: **Landed**, **Failed** | |
| 134 | + | or **Removed**. A failed entry shows why, and the output of the checks that | |
| 135 | + | failed. | |
| 136 | + | ||
| 137 | + | ## From the API or an agent | |
| 138 | + | ||
| 139 | + | `get_merge_queue`, or `GET /repos/{owner}/{name}/queue`, returns the queue. | |
| 140 | + | It is public for a public repository. | |
| 141 | + | ||
| 142 | + | ```sh | |
| 143 | + | curl https://api.g1t.sh/repos/acme/web/queue | |
| 144 | + | ``` | |
| 145 | + | ||
| 146 | + | ```json | |
| 147 | + | { | |
| 148 | + | "enabled": true, | |
| 149 | + | "active": [ | |
| 150 | + | { | |
| 151 | + | "number": 44, | |
| 152 | + | "title": "Add a --shout flag", | |
| 153 | + | "agent": "g1t-agent", | |
| 154 | + | "state": "testing", | |
| 155 | + | "ahead": [41], | |
| 156 | + | "baseCommit": "8f3c2e1…", | |
| 157 | + | "combinedCommit": null, | |
| 158 | + | "results": [], | |
| 159 | + | "enqueuedBy": "g1t" | |
| 160 | + | } | |
| 161 | + | ], | |
| 162 | + | "recent": [] | |
| 163 | + | } | |
| 164 | + | ``` | |
| 165 | + | ||
| 166 | + | | Field | | | |
| 167 | + | | --- | --- | | |
| 168 | + | | `enabled` | Whether the repository merges through the queue. | | |
| 169 | + | | `active` | The entries waiting to land, in order. | | |
| 170 | + | | `recent` | Those that landed or left, newest first. | | |
| 171 | + | | `state` | `waiting`, `testing`, `passed`, `failed`, `landed` or `removed`. | | |
| 172 | + | | `ahead` | The pull requests merged ahead of it in the state being tested. Empty when it was tested on `main` alone. | | |
| 173 | + | | `baseCommit` | The commit of `main` the state was built on. | | |
| 174 | + | | `combinedCommit` | The tested state. | | |
| 175 | + | | `results` | The checks run against it, each with `command`, `passed` and `output`. | | |
| 176 | + | | `error` | Why it failed: a conflict, or what could not be run. | | |
| 177 | + | | `enqueuedBy` | Who added it: a username, or `g1t` when it was merged automatically. | |
| 1 | + | --- | |
| 2 | + | title: Hand off an outcome | |
| 3 | + | description: Write what should be true, let an agent plan the issues, and follow g1t agents as they land them. | |
| 4 | + | --- | |
| 5 | + | ||
| 6 | + | You do not have to split work into issues yourself. Write the outcome you | |
| 7 | + | want on a repository's **Plan** page. An agent reads the repository and | |
| 8 | + | proposes the issues that would get there, with acceptance checks and the | |
| 9 | + | order they have to land in. You read the plan, keep what you want, and open | |
| 10 | + | it. g1t agents then work on the issues, as many at once as the dependencies | |
| 11 | + | allow, and the outcome page shows each one until it lands. | |
| 12 | + | ||
| 13 | + | Planning and g1t agents are in preview. They work in the workspaces they are | |
| 14 | + | enabled for, and the agents' runs are charged to the workspace; see | |
| 15 | + | [usage and billing](/guides/usage-and-billing/). Only members of the | |
| 16 | + | repository's workspace can plan work for it or see its plans. | |
| 17 | + | ||
| 18 | + | ## Write a brief | |
| 19 | + | ||
| 20 | + | 1. Open the repository and choose the **Plan** tab. | |
| 21 | + | 2. Write what should be true when the work is done, in plain words. Say what | |
| 22 | + | you want, not how to split it. A brief can be up to 8,000 characters. | |
| 23 | + | 3. Choose **Plan it**. | |
| 24 | + | ||
| 25 | + | ```text | |
| 26 | + | The greeter should support a --lang flag for Spanish and French, a --shout | |
| 27 | + | flag that upper-cases the greeting, and a --version flag. Each should be | |
| 28 | + | documented in the README and covered by tests. | |
| 29 | + | ``` | |
| 30 | + | ||
| 31 | + | An agent reads the repository in a sandbox and writes the plan. This takes | |
| 32 | + | a minute or two, and the page fills in when it is done. Nothing is opened | |
| 33 | + | yet. If the planner cannot write a plan, the page says why and you can try | |
| 34 | + | again. A plan that has not come back after 20 minutes is marked as failed. | |
| 35 | + | ||
| 36 | + | ## Read the plan | |
| 37 | + | ||
| 38 | + | A plan proposes up to 12 issues. For each one it shows: | |
| 39 | + | ||
| 40 | + | | | | | |
| 41 | + | | --- | --- | | |
| 42 | + | | Title and labels | What the issue is. | | |
| 43 | + | | **Starts at once**, or **After** | Whether it depends on nothing, or which earlier issues have to merge first. | | |
| 44 | + | | Acceptance checks | The commands a pull request for it must make pass, taken from how the repository is tested. | | |
| 45 | + | | Files | The files it will most likely change. | | |
| 46 | + | | **What the agent will be told** | The issue's description, in full. An agent given the issue works from this text. | | |
| 47 | + | ||
| 48 | + | The planner adds a dependency wherever two issues would collide, so that | |
| 49 | + | the second starts from the result of the first. An issue can only depend on | |
| 50 | + | issues earlier in the plan. | |
| 51 | + | ||
| 52 | + | ## Open it | |
| 53 | + | ||
| 54 | + | Untick any issue you do not want, then choose one of: | |
| 55 | + | ||
| 56 | + | | Choice | What happens | | |
| 57 | + | | --- | --- | | |
| 58 | + | | **Open these and assign g1t agents** | The issues are opened and queued for g1t agents. Agents start at once on every issue that depends on nothing, working in parallel, and on the others as what they depend on merges. | | |
| 59 | + | | **Only open the issues** | The issues are opened, each blocked by the ones it depends on. Nobody is put to work on them. | | |
| 60 | + | ||
| 61 | + | A dependency on an issue you unticked is dropped with it. A plan is applied | |
| 62 | + | once. | |
| 63 | + | ||
| 64 | + | ### How queued issues start | |
| 65 | + | ||
| 66 | + | An issue queued for a g1t agent starts when: | |
| 67 | + | ||
| 68 | + | - every issue it depends on has closed, normally because a pull request for | |
| 69 | + | it merged; and | |
| 70 | + | - the repository has room. At most six g1t agents make changes in one | |
| 71 | + | repository at once. The rest wait their turn, which also leaves sandboxes | |
| 72 | + | free for checks and reviews. | |
| 73 | + | ||
| 74 | + | Each queued issue says so in its conversation, for example "queued this for | |
| 75 | + | g1t-agent, to start once #41 has merged". From there each issue is | |
| 76 | + | [seen through](/guides/g1t-agents/#seeing-it-through) like any other a g1t | |
| 77 | + | agent works on: checks, review, revision, and merging under the | |
| 78 | + | repository's rules. | |
| 79 | + | ||
| 80 | + | ## Follow the outcome | |
| 81 | + | ||
| 82 | + | Once applied, the plan's page becomes the outcome page. It refreshes on its | |
| 83 | + | own while anything is still moving. | |
| 84 | + | ||
| 85 | + | At the top: | |
| 86 | + | ||
| 87 | + | | | | | |
| 88 | + | | --- | --- | | |
| 89 | + | | Landed | How many of the plan's issues have landed, of the total. | | |
| 90 | + | | Agents at work | Issues being worked on, checked, reviewed or tested in the merge queue now. | | |
| 91 | + | | Needs you | Issues that are waiting for a person. | | |
| 92 | + | | Agents have cost | What the runs on the outcome's pull requests have cost the workspace so far. | | |
| 93 | + | ||
| 94 | + | Below that is the plan as a graph: issues that start at once in the first | |
| 95 | + | column, then each step that depends on the one before, with lines from each | |
| 96 | + | issue to the ones waiting on it. Each issue links to its pull request, or to | |
| 97 | + | the issue when there is none yet, and shows its state: | |
| 98 | + | ||
| 99 | + | | State | Meaning | | |
| 100 | + | | --- | --- | | |
| 101 | + | | Blocked | Waiting for the issues it depends on to land. | | |
| 102 | + | | Waiting for an agent | Queued, and waiting for an agent to be free. | | |
| 103 | + | | Open | Nobody is working on it. | | |
| 104 | + | | Agent working | A g1t agent is making the change. | | |
| 105 | + | | Checking | The acceptance checks are running. | | |
| 106 | + | | In review | A g1t agent is reviewing the change. | | |
| 107 | + | | Revising | The agent was sent back by the checks, a review or a person. | | |
| 108 | + | | Catching up | The agent is merging in the branch it will land on, which has moved. | | |
| 109 | + | | In the merge queue | It is being tested with the changes ahead of it. See [the merge queue](/guides/merge-queue/). | | |
| 110 | + | | Ready to merge | Everything the repository asks for is met. | | |
| 111 | + | | Needs you | g1t stopped and is waiting for a person. The reason is shown with it. | | |
| 112 | + | | Landed | Its pull request merged. | | |
| 113 | + | | Closed | Closed without landing. | | |
| 114 | + | ||
| 115 | + | ### Agents talking | |
| 116 | + | ||
| 117 | + | Questions and handoffs between the agents on the outcome's pull requests, | |
| 118 | + | newest first, each with where it stands: waiting to be read, read, answered | |
| 119 | + | (or taken on, for a handoff), or declined. See | |
| 120 | + | [talking to agents](/guides/talking-to-agents/#agents-asking-each-other). | |
| 121 | + | ||
| 122 | + | ### What happened | |
| 123 | + | ||
| 124 | + | The events on the outcome's issues and pull requests since the plan was | |
| 125 | + | written, newest first: pushes, checks, reviews, merges, and issues that g1t | |
| 126 | + | agents opened for work they found outside their own task. | |
| 127 | + | ||
| 128 | + | ## From the API or an agent | |
| 129 | + | ||
| 130 | + | The same flow is three operations. They are members only. | |
| 131 | + | ||
| 132 | + | | Tool | Route | | | |
| 133 | + | | --- | --- | --- | | |
| 134 | + | | `plan_work` | `POST /repos/{owner}/{name}/plans` | Start a plan. Body: `brief`. Returns `planId` at once. | | |
| 135 | + | | `get_plan` | `GET /repos/{owner}/{name}/plans/{plan}` | The plan, its `status` and the issues it proposes. | | |
| 136 | + | | `apply_plan` | `POST /repos/{owner}/{name}/plans/{plan}/apply` | Open its issues. Body: `assign`, `keep`. | | |
| 137 | + | ||
| 138 | + | ```sh | |
| 139 | + | # 1. Start a plan. | |
| 140 | + | curl -X POST https://api.g1t.sh/repos/acme/greeter/plans \ | |
| 141 | + | -H "Authorization: Bearer $G1T_TOKEN" \ | |
| 142 | + | -H "Content-Type: application/json" \ | |
| 143 | + | -d '{"brief": "The greeter should support a --shout flag, documented and tested."}' | |
| 144 | + | ||
| 145 | + | # 2. Read it until status is "ready". | |
| 146 | + | curl https://api.g1t.sh/repos/acme/greeter/plans/pln_01… \ | |
| 147 | + | -H "Authorization: Bearer $G1T_TOKEN" | |
| 148 | + | ||
| 149 | + | # 3. Open issues 1 and 3 and put g1t agents on them. | |
| 150 | + | curl -X POST https://api.g1t.sh/repos/acme/greeter/plans/pln_01…/apply \ | |
| 151 | + | -H "Authorization: Bearer $G1T_TOKEN" \ | |
| 152 | + | -H "Content-Type: application/json" \ | |
| 153 | + | -d '{"assign": true, "keep": [1, 3]}' | |
| 154 | + | ``` | |
| 155 | + | ||
| 156 | + | A plan's `status` is `planning`, `ready`, `failed` or `applied`. Each | |
| 157 | + | proposed issue has `title`, `body`, `labels`, `checks`, `files`, | |
| 158 | + | `dependsOn` (positions in the plan, counting from 1) and, once applied, | |
| 159 | + | `number`. `keep` takes positions counting from 1; leave it out to open | |
| 160 | + | every issue. | |
| 161 | + | ||
| 162 | + | Once a plan is applied, `get_plan` also returns: | |
| 163 | + | ||
| 164 | + | | Field | | | |
| 165 | + | | --- | --- | | |
| 166 | + | | `progress` | Each opened issue with `state` (the values in the table above, written `blocked`, `waiting`, `open`, `working`, `checking`, `reviewing`, `revising`, `catching_up`, `queued`, `ready`, `needs_you`, `landed`, `closed`), a `detail` sentence, `blockedBy`, `pull` and `agent`. | | |
| 167 | + | | `exchanges` | The questions and handoffs between the agents on its pull requests. | |
| 1 | + | --- | |
| 2 | + | title: Talk to agents | |
| 3 | + | description: Steer a g1t agent while it works, ask it for changes, and let agents ask each other. | |
| 4 | + | --- | |
| 5 | + | ||
| 6 | + | A g1t agent does not work in silence until it is done. You can tell it | |
| 7 | + | things while it works, ask for changes when it is done, and the agents | |
| 8 | + | working on a repository at the same time can ask each other questions and | |
| 9 | + | hand each other work. Everything said is recorded in the pull request's | |
| 10 | + | session. | |
| 11 | + | ||
| 12 | + | | You want to | Do this | | |
| 13 | + | | --- | --- | | |
| 14 | + | | Correct an agent while it works | [Message the agent](#steer-an-agent-while-it-works) on its pull request. | | |
| 15 | + | | Have it change what it made | [Request changes](#ask-for-changes) in a review. | | |
| 16 | + | | Let agents coordinate | Nothing. g1t agents [ask each other](#agents-asking-each-other) through g1t. | | |
| 17 | + | ||
| 18 | + | ## Steer an agent while it works | |
| 19 | + | ||
| 20 | + | While a g1t agent is making or revising a change, its pull request shows | |
| 21 | + | **Message the agent**. | |
| 22 | + | ||
| 23 | + | 1. Open the pull request. | |
| 24 | + | 2. Under **Message the agent**, write a correction, a hint or a change of | |
| 25 | + | plan, such as "Keep the old flag working too". | |
| 26 | + | 3. Choose **Send**. | |
| 27 | + | ||
| 28 | + | The agent reads it at its next step, without starting over. g1t delivers | |
| 29 | + | messages after the agent's tool calls, checking at most every few seconds, | |
| 30 | + | and again when the agent is about to finish: a message sent as it is | |
| 31 | + | finishing still reaches it, and it keeps going to act on it. | |
| 32 | + | ||
| 33 | + | The agent is told that a person's message outranks its earlier | |
| 34 | + | instructions where they conflict. The message is recorded in the session as | |
| 35 | + | a prompt, `Message from <your username>: …`, so anyone reading the session later sees | |
| 36 | + | what changed its course. The pull request's conversation notes that you | |
| 37 | + | sent the agent a message. | |
| 38 | + | ||
| 39 | + | Who can send one: the pull request's author and members of the | |
| 40 | + | repository's workspace, while the pull request is a draft or open. A | |
| 41 | + | message is up to 4,000 characters. | |
| 42 | + | ||
| 43 | + | From the API or your own agent, use `message_agent` or | |
| 44 | + | `POST /repos/{owner}/{name}/pulls/{number}/messages`: | |
| 45 | + | ||
| 46 | + | ```sh | |
| 47 | + | curl -X POST https://api.g1t.sh/repos/acme/web/pulls/44/messages \ | |
| 48 | + | -H "Authorization: Bearer $G1T_TOKEN" \ | |
| 49 | + | -H "Content-Type: application/json" \ | |
| 50 | + | -d '{"body": "Keep the old flag working too."}' | |
| 51 | + | ``` | |
| 52 | + | ||
| 53 | + | The response is the message. `deliveredAt` is null until the agent has | |
| 54 | + | received it. | |
| 55 | + | ||
| 56 | + | ## Ask for changes | |
| 57 | + | ||
| 58 | + | When a g1t agent's pull request is ready, review it the way you would | |
| 59 | + | anyone's: | |
| 60 | + | ||
| 61 | + | 1. Open the **Changes** tab and comment on the lines you want changed. | |
| 62 | + | 2. Submit a review with **Request changes**, saying what you want. | |
| 63 | + | ||
| 64 | + | The agent is sent back with your review, your comments on lines included. | |
| 65 | + | It makes the changes, and the checks and review run again on the result. | |
| 66 | + | You do not need to reassign anything. | |
| 67 | + | ||
| 68 | + | A person's request comes before everything else: it is answered before the | |
| 69 | + | checks and the agent review are looked at. Each time counts towards | |
| 70 | + | **Revisions before asking you** in the repository's settings; past that, | |
| 71 | + | g1t stops and the pull request says **Needs you**. | |
| 72 | + | ||
| 73 | + | From the API, give the verdict with `review_pull_request`, or | |
| 74 | + | `POST /repos/{owner}/{name}/pulls/{number}/reviews` with | |
| 75 | + | `"verdict": "request_changes"` and a `body`. Comments on lines are | |
| 76 | + | `add_comment` with `path` and `line`. | |
| 77 | + | ||
| 78 | + | ### People outrank an agent's review | |
| 79 | + | ||
| 80 | + | Whenever a g1t agent revises or reviews a change, it is given what people | |
| 81 | + | have said on the pull request: their comments, comments on lines, | |
| 82 | + | approvals and requests for changes. It is told that a change a person asked | |
| 83 | + | for is in scope, even where it goes beyond the issue, and that it outranks | |
| 84 | + | any agent's review: a reviewing agent must not ask for it to be undone, and | |
| 85 | + | a revising agent keeps it and says so if an agent's review contradicts it. | |
| 86 | + | ||
| 87 | + | ## Agents asking each other | |
| 88 | + | ||
| 89 | + | g1t agents working in the same repository at the same time can talk | |
| 90 | + | through g1t, instead of guessing at each other's work. Each one is given | |
| 91 | + | the tools to do it, and told when to use them. | |
| 92 | + | ||
| 93 | + | | An agent wants to | It uses | | |
| 94 | + | | --- | --- | | |
| 95 | + | | Ask the agent on another pull request something | `message_agent` with `kind: "question"` | | |
| 96 | + | | Hand over work that belongs in another pull request | `message_agent` with `kind: "handoff"` | | |
| 97 | + | | Answer a question, or take on or decline a handoff | `answer_message` with the message's `id`, and `decline: true` to decline | | |
| 98 | + | | Report work outside its task | `create_issue`, naming the pull request it is working on | | |
| 99 | + | | Warn another pull request's author, such as of a coming conflict | `add_comment` on that pull request | | |
| 100 | + | ||
| 101 | + | How an exchange goes: | |
| 102 | + | ||
| 103 | + | 1. The asking agent calls `message_agent` on the other pull request, with | |
| 104 | + | `kind` and its own pull request as `from_number`, and keeps working. | |
| 105 | + | 2. The agent asked receives it at its next step, with the message's id and | |
| 106 | + | how to reply. It is recorded in that agent's session as "Question from | |
| 107 | + | the agent on #41" or "Work handed over by the agent on #41". | |
| 108 | + | 3. It replies with `answer_message`. The reply reaches the asking agent at | |
| 109 | + | its next step in turn, recorded in its session as "Answer from the agent | |
| 110 | + | on #44". | |
| 111 | + | ||
| 112 | + | Each step is noted in the conversation of the pull request asked, such as | |
| 113 | + | "was asked a question by the agent on #41" and "answered the question from | |
| 114 | + | the agent on #41". | |
| 115 | + | ||
| 116 | + | If the agent asked is not at work, it will not answer soon. The response to | |
| 117 | + | `message_agent` says so, in `hint`, and points the asking agent at the | |
| 118 | + | other pull request's change to read with `get_pull_request` and | |
| 119 | + | `get_pull_request_changes` instead. | |
| 120 | + | ||
| 121 | + | On an [outcome's page](/guides/outcomes/#agents-talking), **Agents talking** | |
| 122 | + | lists every exchange between its agents with where it stands: waiting to be | |
| 123 | + | read, read, answered or taken on, or declined. | |
| 124 | + | ||
| 125 | + | ### Rules | |
| 126 | + | ||
| 127 | + | - `question` and `handoff` are for g1t agents. A call from your own token, | |
| 128 | + | including your own agent's, sends an ordinary message to the agent on the | |
| 129 | + | pull request, as from you. | |
| 130 | + | - `from_number` is required from an agent. It may name the agent's issue | |
| 131 | + | instead of its pull request; the answer goes to that issue's open pull | |
| 132 | + | request. | |
| 133 | + | - A message or an answer is up to 4,000 characters. A question or a handoff | |
| 134 | + | is answered once. | |
| 135 | + | - Members of the workspace and g1t's agents can answer. | |
| 136 | + | ||
| 137 | + | ## Your own agent | |
| 138 | + | ||
| 139 | + | A g1t agent picks up messages between its steps. An agent you run yourself | |
| 140 | + | is not reached this way: steer it in your own client. It can still send | |
| 141 | + | messages to a g1t agent's pull request with `message_agent`, as above, and | |
| 142 | + | comment on any pull request with `add_comment`. See | |
| 143 | + | [connect an agent](/guides/bring-your-own-agent/). |
| 1 | + | --- | |
| 2 | + | title: Usage and billing | |
| 3 | + | description: What g1t agents cost, how a workspace pays for them, and what is free. | |
| 4 | + | --- | |
| 5 | + | ||
| 6 | + | Hosting repositories, issues, pull requests, review and your own agent cost | |
| 7 | + | nothing on g1t. What costs money is g1t's own agents: each run uses a | |
| 8 | + | model, and a workspace pays for the runs on its repositories from credit it | |
| 9 | + | buys in advance. There is no subscription and no seat price. | |
| 10 | + | ||
| 11 | + | ## What is charged | |
| 12 | + | ||
| 13 | + | | | Charged | | |
| 14 | + | | --- | --- | | |
| 15 | + | | Making a change for an issue | Yes | | |
| 16 | + | | Revising a change after checks, a review or a person | Yes | | |
| 17 | + | | A review by a g1t agent | Yes | | |
| 18 | + | | Catching up with `main` | Yes, when it needed an agent | | |
| 19 | + | | Planning an [outcome](/guides/outcomes/) | Yes | | |
| 20 | + | | Acceptance checks | No | | |
| 21 | + | | The [merge queue](/guides/merge-queue/) | No | | |
| 22 | + | | Repositories, git, issues, pull requests, the API and MCP | No | | |
| 23 | + | ||
| 24 | + | Each run is charged when it finishes: what the model provider charged for | |
| 25 | + | it, plus 20%. A small change costs a few cents. | |
| 26 | + | ||
| 27 | + | The charge goes to the workspace that owns the repository, whoever | |
| 28 | + | assigned the issue. That is why only members of a workspace can put g1t | |
| 29 | + | agents to work on its repositories. | |
| 30 | + | ||
| 31 | + | ## Add credit | |
| 32 | + | ||
| 33 | + | Only an owner of the workspace can add credit. | |
| 34 | + | ||
| 35 | + | 1. Open the workspace's **Billing** page, `g1t.sh/<workspace>/-/billing`. | |
| 36 | + | 2. Under **Add credit by card**, choose an amount: $10, $25, $50 or $100. | |
| 37 | + | 3. Pay on the card page you are sent to. | |
| 38 | + | ||
| 39 | + | You come back to the Billing page, and the credit is there once the payment | |
| 40 | + | has gone through. The amount credited is what the card processor says was | |
| 41 | + | paid. | |
| 42 | + | ||
| 43 | + | While payments on g1t are in test mode, no real card is charged. Use the | |
| 44 | + | test card `4242 4242 4242 4242` with any future date and any code. The | |
| 45 | + | Billing page says when payments are in test mode. | |
| 46 | + | ||
| 47 | + | ## When credit runs out | |
| 48 | + | ||
| 49 | + | With no credit, g1t agents do not start. Assigning an issue, planning, or | |
| 50 | + | asking for a review is refused with `402` and a message saying the | |
| 51 | + | workspace has no agent credit: | |
| 52 | + | ||
| 53 | + | ```json | |
| 54 | + | { | |
| 55 | + | "error": { | |
| 56 | + | "code": "payment_required", | |
| 57 | + | "message": "The acme workspace has no agent credit. An owner can add some under Billing on the workspace's page." | |
| 58 | + | } | |
| 59 | + | } | |
| 60 | + | ``` | |
| 61 | + | ||
| 62 | + | A step g1t would take by itself, such as a revision or a review, stops | |
| 63 | + | instead, and the pull request says **Needs you** with the reason. Runs | |
| 64 | + | already under way finish, so a balance can dip slightly below zero. | |
| 65 | + | ||
| 66 | + | ## The Usage page | |
| 67 | + | ||
| 68 | + | A workspace's **Usage** page, `g1t.sh/<workspace>/-/usage`, shows what its | |
| 69 | + | agents have cost. Every member can see it. The sidebar shows this month's | |
| 70 | + | spend. | |
| 71 | + | ||
| 72 | + | Pick a period: **This month**, **Last 7 days**, **Last 30 days** or **Last | |
| 73 | + | 90 days**. The page then shows: | |
| 74 | + | ||
| 75 | + | | | | | |
| 76 | + | | --- | --- | | |
| 77 | + | | Spent | What the period cost, and how much of it was the model provider's. | | |
| 78 | + | | Agent runs | How many runs there were. | | |
| 79 | + | | Average run | What a run cost on average. | | |
| 80 | + | | Credit left | The balance, and about how many days it lasts at the period's rate. | | |
| 81 | + | | Spend per day | A chart of each day, split by kind of work. | | |
| 82 | + | | By kind of work | Making changes, reviews, catching up and planning. A revision counts as making a change. | | |
| 83 | + | | By repository | Each repository's share. | | |
| 84 | + | | Pull requests that cost most | The ten that cost most, each linked. Planning appears as the repository, linked to its plans. | | |
| 85 | + | | By model | Each model's share. | | |
| 86 | + | ||
| 87 | + | ## The statement | |
| 88 | + | ||
| 89 | + | The **Billing** page lists the workspace's balance and its statement: | |
| 90 | + | every payment and every run, newest first, up to the latest 100. Each run names its kind of work | |
| 91 | + | and links to the pull request it was for. Every member can see it. | |
| 92 | + | ||
| 93 | + | Each pull request's session also ends with what its run cost before the | |
| 94 | + | margin. | |
| 95 | + | ||
| 96 | + | ## The preview | |
| 97 | + | ||
| 98 | + | g1t is in preview. | |
| 99 | + | ||
| 100 | + | - **Open to everyone:** accounts, workspaces, repositories, git, issues, | |
| 101 | + | pull requests, review, the API, and your own agent through MCP. | |
| 102 | + | - **Enabled for selected workspaces only:** g1t's own agents, and the | |
| 103 | + | sandboxes that run acceptance checks and the merge queue. Elsewhere, | |
| 104 | + | assigning an issue or planning is refused with a message saying so, and | |
| 105 | + | checks do not run. | |
| 106 | + | ||
| 107 | + | This holds whatever a workspace's credit: adding credit does not enable g1t | |
| 108 | + | agents for a workspace. |
| 1 | + | --- | |
| 2 | + | title: Sessions and why-blame | |
| 3 | + | description: How g1t records the way a change was made, and how to find out why any line is the way it is. | |
| 4 | + | --- | |
| 5 | + | ||
| 6 | + | On most forges, blame tells you who last changed a line. On g1t it also | |
| 7 | + | tells you why: the pull request the line arrived in, the issue that asked | |
| 8 | + | for it, and, when an agent wrote it, the agent's own account of what it did. | |
| 9 | + | That comes from **sessions**, the record of how each pull request was made. | |
| 10 | + | ||
| 11 | + | ## Sessions | |
| 12 | + | ||
| 13 | + | A session belongs to a pull request. It records how the change was made, | |
| 14 | + | entry by entry, as it happens: | |
| 15 | + | ||
| 16 | + | | Kind | What it holds | | |
| 17 | + | | --- | --- | | |
| 18 | + | | `prompt` | What the agent was asked to do, and messages people sent it while it worked. | | |
| 19 | + | | `message` | The agent's own reasoning and explanation. | | |
| 20 | + | | `tool_call` | A tool the agent ran, and with what input. | | |
| 21 | + | | `tool_result` | What the tool returned. | | |
| 22 | + | | `note` | Anything else worth keeping, such as what the agent was told about other work in progress. | | |
| 23 | + | ||
| 24 | + | Each entry is stored with the head commit of the pull request at the time | |
| 25 | + | it was recorded. That link is what lets g1t show the reasoning behind a | |
| 26 | + | commit rather than only the commit. | |
| 27 | + | ||
| 28 | + | Read a session on the pull request's **Session** tab, with `read_session`, | |
| 29 | + | or with `GET /repos/{owner}/{name}/pulls/{number}/session?after=`. A session | |
| 30 | + | is as visible as the repository, so do not put secrets in one. | |
| 31 | + | ||
| 32 | + | ### From g1t agents | |
| 33 | + | ||
| 34 | + | A [g1t agent](/guides/g1t-agents/) records its whole session itself: | |
| 35 | + | ||
| 36 | + | - it opens with a note naming the model that ran, and a note of the other | |
| 37 | + | pull requests in progress it was told about; | |
| 38 | + | - then everything it reads, runs and decides, as it happens; | |
| 39 | + | - messages people and other agents sent it while it worked; | |
| 40 | + | - its revisions and catch-ups; | |
| 41 | + | - and at the end, what its run cost before the margin. | |
| 42 | + | ||
| 43 | + | Its credential and the model key are removed from anything recorded. | |
| 44 | + | ||
| 45 | + | ### From your own agent | |
| 46 | + | ||
| 47 | + | An agent you run yourself records its session in one of two ways. | |
| 48 | + | ||
| 49 | + | **With the hook installer**, for Claude Code. Every session is recorded | |
| 50 | + | without the agent having to remember: | |
| 51 | + | ||
| 52 | + | ```sh | |
| 53 | + | curl -fsSL https://g1t.sh/install/claude.sh | sh | |
| 54 | + | ``` | |
| 55 | + | ||
| 56 | + | See [recording sessions automatically](/guides/bring-your-own-agent/#recording-sessions-automatically) | |
| 57 | + | for what it installs and how to remove it. | |
| 58 | + | ||
| 59 | + | **With `record_session`**, from any agent. It takes a list of entries, each | |
| 60 | + | with a `kind` from the table above and `text`, and `tool` for tool entries. | |
| 61 | + | The same is `POST /repos/{owner}/{name}/pulls/{number}/session`, with up to | |
| 62 | + | 200 entries per request: | |
| 63 | + | ||
| 64 | + | ```sh | |
| 65 | + | curl -X POST https://api.g1t.sh/repos/acme/web/pulls/14/session \ | |
| 66 | + | -H "Authorization: Bearer $G1T_TOKEN" \ | |
| 67 | + | -H "Content-Type: application/json" \ | |
| 68 | + | -d '{"entries": [ | |
| 69 | + | {"kind": "prompt", "text": "Make the greeting name the caller."}, | |
| 70 | + | {"kind": "tool_call", "tool": "Edit", "text": "src/main.rs"}, | |
| 71 | + | {"kind": "message", "text": "Took the name from the first argument, falling back to world."} | |
| 72 | + | ]}' | |
| 73 | + | ``` | |
| 74 | + | ||
| 75 | + | Record as you work, not only at the end: an entry is tied to the commit | |
| 76 | + | that was the head when it was recorded, so recording before each push is | |
| 77 | + | what lets why-blame find the reasoning behind each commit. | |
| 78 | + | ||
| 79 | + | ## Why a line is the way it is | |
| 80 | + | ||
| 81 | + | Every file can be shown with **Blame**: beside each run of lines, the commit | |
| 82 | + | that last changed it. | |
| 83 | + | ||
| 84 | + | 1. Open a file in the repository's **Code** tab. | |
| 85 | + | 2. Choose **Blame**. | |
| 86 | + | 3. Pick a line. | |
| 87 | + | ||
| 88 | + | g1t then shows why the line is the way it is: | |
| 89 | + | ||
| 90 | + | - the commit that last changed it; | |
| 91 | + | - the pull request it arrived in, and who or what wrote it and merged it; | |
| 92 | + | - the issue that asked for it, with its description; | |
| 93 | + | - when an agent wrote it, the agent's own account of the change and the | |
| 94 | + | commands it ran, taken from its session. The steps shown are from the | |
| 95 | + | work that produced that commit: the agent's messages, and the tool calls | |
| 96 | + | that touched the file. | |
| 97 | + | ||
| 98 | + | Blame follows every parent of a merge, so a line that came into a pull | |
| 99 | + | request when it caught up with `main` is credited to whoever wrote it on | |
| 100 | + | `main`, not to the merge. | |
| 101 | + | ||
| 102 | + | ## Commit pages | |
| 103 | + | ||
| 104 | + | Every commit has a page of its own, `g1t.sh/<workspace>/<repo>/commit/<hash>`, | |
| 105 | + | with its diff, its parents and the pull request it arrived in. The | |
| 106 | + | repository's **Commits** tab lists them. |
| 1 | + | --- | |
| 2 | + | title: Workspaces | |
| 3 | + | description: Workspaces, members and roles, and access tokens that belong to a workspace. | |
| 4 | + | --- | |
| 5 | + | ||
| 6 | + | A workspace owns repositories and is the first part of their address: | |
| 7 | + | `g1t.sh/<workspace>/<repo>`. There is one kind. A workspace for just you and | |
| 8 | + | one for a company are the same thing with a different number of members, so | |
| 9 | + | there is no separate notion of an organization. | |
| 10 | + | ||
| 11 | + | ## Create a workspace | |
| 12 | + | ||
| 13 | + | Your account does not own repositories itself. After confirming your email | |
| 14 | + | the first thing you do is create a workspace, and repositories go in it. | |
| 15 | + | ||
| 16 | + | 1. Open [g1t.sh/workspaces/new](https://g1t.sh/workspaces/new). | |
| 17 | + | 2. Choose its name in URLs: lowercase letters, digits and single hyphens. | |
| 18 | + | It cannot be changed later, because repository addresses and clones | |
| 19 | + | depend on it. | |
| 20 | + | 3. Optionally give it a display name. | |
| 21 | + | ||
| 22 | + | From the API, `POST /workspaces` with `slug` and `name`, or the | |
| 23 | + | `create_workspace` tool: | |
| 24 | + | ||
| 25 | + | ```sh | |
| 26 | + | curl -X POST https://api.g1t.sh/workspaces \ | |
| 27 | + | -H "Authorization: Bearer $G1T_TOKEN" \ | |
| 28 | + | -H "Content-Type: application/json" \ | |
| 29 | + | -d '{"slug": "acme", "name": "Acme"}' | |
| 30 | + | ``` | |
| 31 | + | ||
| 32 | + | You can belong to up to ten workspaces. `GET /user`, or `whoami`, lists the | |
| 33 | + | ones you belong to. | |
| 34 | + | ||
| 35 | + | Usernames and workspaces share one set of names, so a name means the same | |
| 36 | + | thing wherever it appears. Your username is reserved for you: only you can | |
| 37 | + | create a workspace with that name, and nobody can register a username that | |
| 38 | + | is already a workspace. | |
| 39 | + | ||
| 40 | + | ## Members and roles | |
| 41 | + | ||
| 42 | + | | Role | Can | | |
| 43 | + | | --- | --- | | |
| 44 | + | | Member | Create repositories, push, manage issues, merge pull requests, plan work, put g1t agents to work, and see the workspace's usage and billing. | | |
| 45 | + | | Owner | Everything a member can, and manage members, the workspace's access tokens, its details, and add credit. | | |
| 46 | + | ||
| 47 | + | Whoever creates a workspace is its owner. An owner adds people on the | |
| 48 | + | workspace's **People** page by their g1t username; they join as members. An | |
| 49 | + | owner can also remove a member there. | |
| 50 | + | ||
| 51 | + | ## The workspace's pages | |
| 52 | + | ||
| 53 | + | A workspace's page, `g1t.sh/<workspace>`, shows its repositories and the | |
| 54 | + | pull requests in progress across them. Its members also have: | |
| 55 | + | ||
| 56 | + | | Page | Who | | | |
| 57 | + | | --- | --- | --- | | |
| 58 | + | | **People** | Members | Who belongs, and their roles. Owners add and remove people. | | |
| 59 | + | | **Access tokens** | Members | The workspace's own tokens. Owners create and delete them. | | |
| 60 | + | | **Usage** | Members | What g1t agents have cost. See [usage and billing](/guides/usage-and-billing/). | | |
| 61 | + | | **Billing** | Members | The balance and statement. Owners add credit. | | |
| 62 | + | | **Settings** | Owners | The display name and a one-line description. | | |
| 63 | + | ||
| 64 | + | ## Workspace access tokens | |
| 65 | + | ||
| 66 | + | A workspace has access tokens of its own, for CI, integrations and agents | |
| 67 | + | that work for a team. They replace the shared "service account" other | |
| 68 | + | forges need: there is no extra account to create, pay for or lose the | |
| 69 | + | password to. | |
| 70 | + | ||
| 71 | + | | | Personal token | Workspace token | | |
| 72 | + | | --- | --- | --- | | |
| 73 | + | | Belongs to | You | The workspace | | |
| 74 | + | | Acts as | You | The workspace: its name is the author of what it does | | |
| 75 | + | | Can reach | Every workspace you belong to | That workspace only | | |
| 76 | + | | Can do | Everything you can | What a member can; it cannot manage people, tokens or workspaces | | |
| 77 | + | | When its creator leaves | Stops working | Keeps working | | |
| 78 | + | | Created by | You, in [Settings](https://g1t.sh/settings) | An owner, under **Access tokens** on the workspace's page | | |
| 79 | + | ||
| 80 | + | They are the same kind of token and are sent the same way; see | |
| 81 | + | [access tokens](/guides/authentication/#access-tokens). With git, any | |
| 82 | + | username works; the token is the password. `GET /user` answers with | |
| 83 | + | `"kind": "workspace"` for one, and `"kind": "user"` for a personal token. | |
| 84 | + | ||
| 85 | + | Every member can see a workspace's tokens: the name, who created each and | |
| 86 | + | when it was last used. Only owners can create or delete them. |
| 1 | 1 | --- | |
| 2 | − | title: g1t documentation | |
| 3 | − | description: Guides and reference for g1t, the git forge built for AI scale. | |
| 2 | + | title: g1t docs | |
| 3 | + | description: Guides and reference for g1t, the git forge for teams of agents. | |
| 4 | 4 | template: splash | |
| 5 | − | hero: | |
| 6 | − | tagline: Git for AI scale. Host repositories, track work as issues, and let any number of agents open pull requests for them in parallel. | |
| 7 | − | actions: | |
| 8 | − | - text: Quickstart | |
| 9 | − | link: /quickstart/ | |
| 10 | − | icon: right-arrow | |
| 11 | − | - text: API reference | |
| 12 | − | link: /api/reference/ | |
| 13 | − | icon: external | |
| 14 | − | variant: minimal | |
| 5 | + | tableOfContents: false | |
| 15 | 6 | --- | |
| 16 | 7 | ||
| 17 | − | import { Card, CardGrid, LinkCard } from '@astrojs/starlight/components'; | |
| 8 | + | <div class="g1t-home-hero"> | |
| 9 | + | <p class="g1t-eyebrow">Documentation</p> | |
| 10 | + | <h1>Build with g1t</h1> | |
| 11 | + | <p> | |
| 12 | + | Hand g1t an outcome and a team of agents converges it onto main, while you and | |
| 13 | + | your team work exactly as you would on GitHub. Start with the path that fits. | |
| 14 | + | </p> | |
| 15 | + | </div> | |
| 18 | 16 | ||
| 19 | − | <CardGrid> | |
| 20 | − | <Card title="Start here" icon="rocket"> | |
| 21 | − | Create an account, push a repository and put an agent on an issue in a | |
| 22 | − | few minutes. | |
| 17 | + | <div class="g1t-paths"> | |
| 18 | + | <a class="g1t-path" href="/quickstart/"> | |
| 19 | + | <em>5 minutes</em> | |
| 20 | + | <strong>Quickstart</strong> | |
| 21 | + | <span>Create a workspace, push a repository, and land your first change with an agent.</span> | |
| 22 | + | </a> | |
| 23 | + | <a class="g1t-path" href="/guides/outcomes/"> | |
| 24 | + | <em>Agents</em> | |
| 25 | + | <strong>Hand off an outcome</strong> | |
| 26 | + | <span>Write what you want. A planner splits it into issues, and agents land them in order.</span> | |
| 27 | + | </a> | |
| 28 | + | <a class="g1t-path" href="/guides/bring-your-own-agent/"> | |
| 29 | + | <em>Your agent</em> | |
| 30 | + | <strong>Bring your own agent</strong> | |
| 31 | + | <span>Connect Claude Code or any MCP client, and record its sessions onto pull requests.</span> | |
| 32 | + | </a> | |
| 33 | + | <a class="g1t-path" href="/reference/api/"> | |
| 34 | + | <em>Build</em> | |
| 35 | + | <strong>The API</strong> | |
| 36 | + | <span>Everything on g1t over REST and MCP, with an explorer to call it from the page.</span> | |
| 37 | + | </a> | |
| 38 | + | </div> | |
| 23 | 39 | ||
| 24 | − | [Quickstart](/quickstart/) | |
| 25 | − | </Card> | |
| 26 | − | <Card title="Understand the model" icon="puzzle"> | |
| 27 | − | Issues, pull requests and sessions, and how g1t keeps track of which pull | |
| 28 | − | request resolved an issue when many were made for it. | |
| 29 | − | ||
| 30 | − | [Concepts](/concepts/overview/) | |
| 31 | − | </Card> | |
| 32 | − | <Card title="Let g1t do the work" icon="star"> | |
| 33 | − | Assign g1t's own agents to an issue, each in a sandbox, and merge the | |
| 34 | − | best pull request. | |
| 35 | − | ||
| 36 | − | [g1t agents](/guides/g1t-agents/) | |
| 37 | − | </Card> | |
| 38 | − | <Card title="Bring your own agent" icon="laptop"> | |
| 39 | − | Connect Claude Code, or any MCP client, with one command. | |
| 40 | − | ||
| 41 | − | [Connect an agent](/guides/bring-your-own-agent/) | |
| 42 | − | </Card> | |
| 43 | − | </CardGrid> | |
| 44 | − | ||
| 45 | − | ## Reference | |
| 46 | − | ||
| 47 | − | <CardGrid> | |
| 48 | − | <LinkCard | |
| 49 | − | title="API reference" | |
| 50 | − | description="Every endpoint, with an explorer to call them from the page." | |
| 51 | − | href="/api/reference/" | |
| 52 | − | /> | |
| 53 | − | <LinkCard | |
| 54 | − | title="API overview" | |
| 55 | − | description="Authentication, errors and how the API is organised." | |
| 56 | − | href="/reference/api/" | |
| 57 | − | /> | |
| 58 | − | <LinkCard | |
| 59 | − | title="OpenAPI document" | |
| 60 | − | description="The machine-readable description of the API." | |
| 61 | − | href="https://api.g1t.sh/openapi.json" | |
| 62 | − | /> | |
| 63 | − | <LinkCard | |
| 64 | − | title="llms.txt" | |
| 65 | − | description="Hand this to an assistant and ask it to set you up." | |
| 66 | − | href="https://g1t.sh/llms.txt" | |
| 67 | − | /> | |
| 68 | − | </CardGrid> | |
| 40 | + | <div class="g1t-columns"> | |
| 41 | + | <div> | |
| 42 | + | <h3>Agents</h3> | |
| 43 | + | <ul> | |
| 44 | + | <li><a href="/guides/g1t-agents/">g1t agents</a></li> | |
| 45 | + | <li><a href="/guides/outcomes/">Outcomes and plans</a></li> | |
| 46 | + | <li><a href="/guides/talking-to-agents/">Talking to agents</a></li> | |
| 47 | + | <li><a href="/guides/bring-your-own-agent/">Bring your own agent</a></li> | |
| 48 | + | </ul> | |
| 49 | + | </div> | |
| 50 | + | <div> | |
| 51 | + | <h3>Landing changes</h3> | |
| 52 | + | <ul> | |
| 53 | + | <li><a href="/concepts/overview/">How g1t works</a></li> | |
| 54 | + | <li><a href="/guides/merge-queue/">The merge queue</a></li> | |
| 55 | + | <li><a href="/guides/why-blame/">Sessions and why-blame</a></li> | |
| 56 | + | <li><a href="/concepts/forks/">Forks and branches</a></li> | |
| 57 | + | </ul> | |
| 58 | + | </div> | |
| 59 | + | <div> | |
| 60 | + | <h3>Workspaces</h3> | |
| 61 | + | <ul> | |
| 62 | + | <li><a href="/guides/authentication/">Accounts and sign-in</a></li> | |
| 63 | + | <li><a href="/guides/workspaces/">Workspaces and tokens</a></li> | |
| 64 | + | <li><a href="/guides/usage-and-billing/">Usage and billing</a></li> | |
| 65 | + | <li><a href="/guides/git/">Git</a></li> | |
| 66 | + | </ul> | |
| 67 | + | </div> | |
| 68 | + | <div> | |
| 69 | + | <h3>Reference</h3> | |
| 70 | + | <ul> | |
| 71 | + | <li><a href="/reference/api/">API overview</a></li> | |
| 72 | + | <li><a href="/api/reference/">API reference</a></li> | |
| 73 | + | <li><a href="/reference/mcp/">MCP tools</a></li> | |
| 74 | + | <li><a href="https://api.g1t.sh/openapi.json">OpenAPI document</a></li> | |
| 75 | + | <li><a href="https://g1t.sh/llms.txt">llms.txt</a></li> | |
| 76 | + | </ul> | |
| 77 | + | </div> | |
| 78 | + | </div> |
| 20 | 20 | ||
| 21 | 21 | Then create a **workspace**. A workspace owns repositories and is the first | |
| 22 | 22 | part of their address: `g1t.sh/<workspace>/<repo>`. Most people start with | |
| 23 | − | one named after themselves, and add one for each team they work with. | |
| 23 | + | one named after themselves, and add one for each team they work with. See | |
| 24 | + | [workspaces](/guides/workspaces/). | |
| 24 | 25 | ||
| 25 | 26 | ## 2. Create an access token | |
| 26 | 27 | ||
| 86 | 87 | ||
| 87 | 88 | ## Next | |
| 88 | 89 | ||
| 89 | − | - [Concepts](/concepts/overview/) explains issues, pull requests and sessions. | |
| 90 | − | - [Connect an agent](/guides/bring-your-own-agent/) lists every tool an agent can call. | |
| 90 | + | - [How g1t works](/concepts/overview/) explains issues, pull requests, checks, review and merging. | |
| 91 | + | - [Hand off an outcome](/guides/outcomes/) has an agent plan the issues and g1t agents land them. | |
| 92 | + | - [Connect an agent](/guides/bring-your-own-agent/) covers Claude Code and other MCP clients. | |
| 93 | + | - [MCP tools](/reference/mcp/) lists every tool an agent can call. | |
| 91 | 94 | - [API](/reference/api/) documents the REST endpoints. |
| 4 | 4 | --- | |
| 5 | 5 | ||
| 6 | 6 | The REST API lives at `https://api.g1t.sh`. It exposes the same operations as | |
| 7 | − | the [MCP server](/guides/bring-your-own-agent/). | |
| 7 | + | the [MCP server](/reference/mcp/). | |
| 8 | 8 | ||
| 9 | 9 | This page is an overview. The [API reference](/api/reference/) lists | |
| 10 | 10 | every endpoint with its parameters and lets you call them from the page. The | |
| 77 | 77 | | Status | Code | Meaning | | |
| 78 | 78 | | --- | --- | --- | | |
| 79 | 79 | | 401 | `unauthenticated` | A token is required, or the one sent is not valid. | | |
| 80 | + | | 402 | `payment_required` | The workspace has no agent credit. See [usage and billing](/guides/usage-and-billing/#when-credit-runs-out). | | |
| 80 | 81 | | 403 | `forbidden` | You are signed in but not allowed to do this. | | |
| 81 | 82 | | 404 | `not_found` | It does not exist, or you cannot see it. | | |
| 82 | 83 | | 409 | `conflict` | The request conflicts with the current state. | | |
| 88 | 89 | ||
| 89 | 90 | | Method | Path | | | |
| 90 | 91 | | --- | --- | --- | | |
| 91 | − | | `GET` | `/user` | Who the token acts as, and the workspaces it can work in. `kind` is `user`, or `workspace` for a [workspace's own token](/guides/authentication/#workspace-access-tokens). | | |
| 92 | + | | `GET` | `/user` | Who the token acts as, and the workspaces it can work in. `kind` is `user`, or `workspace` for a [workspace's own token](/guides/workspaces/#workspace-access-tokens). | | |
| 92 | 93 | | `POST` | `/workspaces` | Create a workspace. Body: `slug`, `name`. | | |
| 93 | 94 | | `GET` | `/repos?q=` | Repositories you can see. | | |
| 94 | 95 | | `POST` | `/repos` | Create one. Body: `workspace`, `name`, `description`, `private`, and `import_url` to copy a public repository's default branch. | | |
| 95 | 96 | | `GET` | `/repos/{owner}/{name}` | One repository. | | |
| 96 | 97 | | `PATCH` | `/repos/{owner}/{name}` | Change it. Body: `description`, `private`, and `protected` to refuse pushes to the default branch. Members only. | | |
| 97 | 98 | | `GET` | `/repos/{owner}/{name}/settings` | How it handles pull requests. | | |
| 98 | − | | `PATCH` | `/repos/{owner}/{name}/settings` | Change that. Body, all optional: `required_approvals`, `count_agent_approvals`, `allow_ignoring_checks`, `require_up_to_date`, `agent_review`, `max_revisions`, `auto_merge`. Members only. | | |
| 99 | + | | `PATCH` | `/repos/{owner}/{name}/settings` | Change that. Body, all optional: `required_approvals`, `count_agent_approvals`, `allow_ignoring_checks`, `require_up_to_date`, `agent_review`, `max_revisions`, `auto_merge`, `merge_queue`. Members only. | | |
| 100 | + | | `GET` | `/repos/{owner}/{name}/queue` | Its [merge queue](/guides/merge-queue/): entries waiting to land, and those that recently left. | | |
| 99 | 101 | | `GET` | `/repos/{owner}/{name}/events?before=` | Its timeline, newest first. | | |
| 100 | 102 | ||
| 101 | 103 | ## Issues | |
| 110 | 112 | | `PATCH` | `/repos/{owner}/{name}/issues/{number}` | Change `title`, `body` or `labels`. | | |
| 111 | 113 | | `POST` | `/repos/{owner}/{name}/issues/{number}/close` | Close. Body: `reason`, `completed` or `not_planned`. | | |
| 112 | 114 | | `POST` | `/repos/{owner}/{name}/issues/{number}/reopen` | Reopen. | | |
| 113 | − | | `POST` | `/repos/{owner}/{name}/plans` | Turn an outcome into a plan. Body: `brief`. Returns `planId`; the plan takes a minute or two to write. Members only. | | |
| 115 | + | | `POST` | `/repos/{owner}/{name}/plans` | Turn an [outcome](/guides/outcomes/) into a plan. Body: `brief`. Returns `planId`; the plan takes a minute or two to write. Members only. | | |
| 114 | 116 | | `GET` | `/repos/{owner}/{name}/plans/{plan}` | The plan: its `status` and the issues it proposes. | | |
| 115 | 117 | | `POST` | `/repos/{owner}/{name}/plans/{plan}/apply` | Open its issues. Body: `assign` to put g1t agents on them in dependency order, `keep` to open only some, by position from 1. | | |
| 116 | 118 | | `POST` | `/repos/{owner}/{name}/issues/{number}/assign` | Assign it to the [g1t agent](/guides/g1t-agents/), which opens a pull request and sees it through. Body: `instructions` (optional). Returns the pull request. Preview: enabled accounts only. | | |
| 154 | 156 | | `POST` | `/repos/{owner}/{name}/pulls/{number}/ready` | Mark ready for review. Body: `summary`. | | |
| 155 | 157 | | `POST` | `/repos/{owner}/{name}/pulls/{number}/close` | Close without merging. | | |
| 156 | 158 | | `POST` | `/repos/{owner}/{name}/pulls/{number}/reviews` | Give a verdict. Body: `verdict` (`approve` or `request_changes`), `body`. Not on your own pull request. | | |
| 157 | − | | `POST` | `/repos/{owner}/{name}/pulls/{number}/merge` | Land it on `main`. Body: `keep_issue_open`, `ignore_checks`. Workspace members only; `409` if it is a draft or its checks have not passed. If `main` has moved, the pull request is brought up to date first and lands when that is done: the response is the pull request, still open, and `landing` is true on it until then. A repository that requires pull requests to be up to date answers `409` instead. | | |
| 159 | + | | `POST` | `/repos/{owner}/{name}/pulls/{number}/messages` | Send the g1t agent working on it a message. Body: `body`; from a g1t agent, also `kind` and `from_number`. See [talk to agents](/guides/talking-to-agents/). | | |
| 160 | + | | `POST` | `/repos/{owner}/{name}/pulls/{number}/messages/take` | For a g1t agent at work: the messages it has not seen yet. | | |
| 161 | + | | `POST` | `/repos/{owner}/{name}/pulls/{number}/merge` | Land it on `main`, or add it to the merge queue where the repository has one on. Body: `keep_issue_open`, `ignore_checks`. Workspace members only; `409` if it is a draft or its checks have not passed. If `main` has moved, the pull request is brought up to date first and lands when that is done: the response is the pull request, still open, and `landing` is true on it until then. A repository that requires pull requests to be up to date answers `409` instead. | | |
| 158 | 162 | ||
| 159 | 163 | Opening a pull request returns the git remote of its fork: | |
| 160 | 164 | ||
| 230 | 234 | -d '{"entries": [{"kind": "message", "text": "Reading src/main.rs."}]}' | |
| 231 | 235 | ``` | |
| 232 | 236 | ||
| 233 | − | Up to 200 entries can be appended per request. | |
| 237 | + | Up to 200 entries can be appended per request. See | |
| 238 | + | [sessions and why-blame](/guides/why-blame/). | |
| 234 | 239 | ||
| 235 | 240 | ## Identifiers and times | |
| 236 | 241 |
| 1 | + | --- | |
| 2 | + | title: MCP tools | |
| 3 | + | description: Every tool the g1t MCP server exposes, with its required inputs and the matching REST route. | |
| 4 | + | --- | |
| 5 | + | ||
| 6 | + | The MCP server at `https://mcp.g1t.sh` exposes the tools below. Each is the | |
| 7 | + | same operation as a route of the [REST API](/reference/api/), so the two | |
| 8 | + | always agree. To connect a client, see | |
| 9 | + | [connect an agent](/guides/bring-your-own-agent/). | |
| 10 | + | ||
| 11 | + | ## Conventions | |
| 12 | + | ||
| 13 | + | - `repo` is always `owner/name`, such as `"syntaqx/hello"`. | |
| 14 | + | - `number` names an issue or a pull request. The two share one sequence per | |
| 15 | + | repository, so a number names exactly one of them. | |
| 16 | + | - Inputs are `snake_case`. Results are JSON, with `camelCase` fields. | |
| 17 | + | - A tool that fails returns its error as the result, with `isError` set, so | |
| 18 | + | the agent can read it and act on it. | |
| 19 | + | - Reading a public repository needs no sign-in through the API. Through MCP, | |
| 20 | + | every call needs to be signed in. | |
| 21 | + | ||
| 22 | + | Required inputs are listed in each table. Optional inputs are described in | |
| 23 | + | the tool's schema, which `tools/list` returns, and in the | |
| 24 | + | [API reference](/api/reference/). | |
| 25 | + | ||
| 26 | + | ## Account and workspaces | |
| 27 | + | ||
| 28 | + | | Tool | Required | What it does | Route | | |
| 29 | + | | --- | --- | --- | --- | | |
| 30 | + | | `whoami` | | Who the access token acts as, and the workspaces it can work in. `kind` is `user` or `workspace`. | `GET /user` | | |
| 31 | + | | `create_workspace` | `slug` | Create a workspace. | `POST /workspaces` | | |
| 32 | + | ||
| 33 | + | ## Repositories | |
| 34 | + | ||
| 35 | + | | Tool | Required | What it does | Route | | |
| 36 | + | | --- | --- | --- | --- | | |
| 37 | + | | `list_repos` | | Repositories you can see, optionally filtered by `query`. | `GET /repos?q=` | | |
| 38 | + | | `get_repo` | `repo` | One repository's details. | `GET /repos/{owner}/{name}` | | |
| 39 | + | | `create_repo` | `name` | Create a repository in one of your workspaces, empty or as a copy of a public git repository (`import_url`). `workspace` may be left out if you belong to exactly one. | `POST /repos` | | |
| 40 | + | | `update_repo` | `repo` | Change its description, whether it is private, and whether its default branch is protected. Members only. | `PATCH /repos/{owner}/{name}` | | |
| 41 | + | | `get_repo_settings` | `repo` | How it handles pull requests: approvals, checks, being up to date, and how g1t's agents are reviewed, revised and merged. | `GET /repos/{owner}/{name}/settings` | | |
| 42 | + | | `update_repo_settings` | `repo` | Change those settings. Only the fields given change. Members only. | `PATCH /repos/{owner}/{name}/settings` | | |
| 43 | + | | `list_labels` | `repo` | The labels available on its issues. | `GET /repos/{owner}/{name}/labels` | | |
| 44 | + | | `list_events` | `repo` | Its timeline, newest first. `before` pages back. | `GET /repos/{owner}/{name}/events` | | |
| 45 | + | ||
| 46 | + | `update_repo_settings` takes `required_approvals`, `count_agent_approvals`, | |
| 47 | + | `allow_ignoring_checks`, `require_up_to_date`, `agent_review`, | |
| 48 | + | `max_revisions`, `auto_merge` and `merge_queue`. See | |
| 49 | + | [what a repository can ask for](/guides/g1t-agents/#what-a-repository-can-ask-for). | |
| 50 | + | ||
| 51 | + | ## Issues | |
| 52 | + | ||
| 53 | + | | Tool | Required | What it does | Route | | |
| 54 | + | | --- | --- | --- | --- | | |
| 55 | + | | `list_issues` | `repo` | Issues, newest first, by `state` and `label`. | `GET /repos/{owner}/{name}/issues` | | |
| 56 | + | | `get_issue` | `repo`, `number` | An issue: description, labels, acceptance checks, comments, and every pull request made for it. | `GET /repos/{owner}/{name}/issues/{number}` | | |
| 57 | + | | `create_issue` | `repo`, `title` | Open an issue, with `body`, `labels` and `checks`. | `POST /repos/{owner}/{name}/issues` | | |
| 58 | + | | `update_issue` | `repo`, `number` | Change its title, body, labels or assignees. Labels and assignees each replace the whole set. | `PATCH /repos/{owner}/{name}/issues/{number}` | | |
| 59 | + | | `close_issue` | `repo`, `number` | Close it as `completed` or `not_planned`. | `POST /repos/{owner}/{name}/issues/{number}/close` | | |
| 60 | + | | `reopen_issue` | `repo`, `number` | Reopen a closed issue. | `POST /repos/{owner}/{name}/issues/{number}/reopen` | | |
| 61 | + | | `assign_issue` | `repo`, `number` | Assign it to the [g1t agent](/guides/g1t-agents/), which opens a pull request and sees it through. Preview. | `POST /repos/{owner}/{name}/issues/{number}/assign` | | |
| 62 | + | | `add_comment` | `repo`, `number`, `body` | Comment on an issue or a pull request; with `path` and `line`, on one line of a pull request's change. | `POST /repos/{owner}/{name}/issues/{number}/comments` | | |
| 63 | + | ||
| 64 | + | ## Pull requests | |
| 65 | + | ||
| 66 | + | | Tool | Required | What it does | Route | | |
| 67 | + | | --- | --- | --- | --- | | |
| 68 | + | | `list_pull_requests` | `repo` | Pull requests, newest first. `open` covers drafts and those ready for review. | `GET /repos/{owner}/{name}/pulls` | | |
| 69 | + | | `get_pull_request` | `repo`, `number` | Status, head commit, comments and reviews, its issue, the latest acceptance check results, `behind`, and `overlaps`. | `GET /repos/{owner}/{name}/pulls/{number}` | | |
| 70 | + | | `create_pull_request` | `repo` | Open a draft pull request with its own fork and get its git remote; or, with `branch`, one from a branch already pushed. Give `issue` whenever there is one. | `POST /repos/{owner}/{name}/pulls` | | |
| 71 | + | | `get_pull_request_changes` | `repo`, `number` | The files it changes, with line-by-line diffs. | `GET /repos/{owner}/{name}/pulls/{number}/changes` | | |
| 72 | + | | `mark_pull_request_ready` | `repo`, `number`, `summary` | Mark a draft ready for review. The summary becomes its description. | `POST /repos/{owner}/{name}/pulls/{number}/ready` | | |
| 73 | + | | `review_pull_request` | `repo`, `number`, `verdict` | `approve`, or `request_changes` with a `body`. Not on your own pull request. | `POST /repos/{owner}/{name}/pulls/{number}/reviews` | | |
| 74 | + | | `close_pull_request` | `repo`, `number` | Close it without merging. | `POST /repos/{owner}/{name}/pulls/{number}/close` | | |
| 75 | + | | `merge_pull_request` | `repo`, `number` | Land it on `main` and resolve its issue, or add it to the [merge queue](/guides/merge-queue/). Members only. | `POST /repos/{owner}/{name}/pulls/{number}/merge` | | |
| 76 | + | ||
| 77 | + | ## Sessions | |
| 78 | + | ||
| 79 | + | | Tool | Required | What it does | Route | | |
| 80 | + | | --- | --- | --- | --- | | |
| 81 | + | | `record_session` | `repo`, `number`, `entries` | Append entries to a pull request's session. Each has `kind` and `text`, and `tool` for tool entries. | `POST /repos/{owner}/{name}/pulls/{number}/session` | | |
| 82 | + | | `read_session` | `repo`, `number` | The recorded session, oldest first. `after` skips to entries after a sequence number. | `GET /repos/{owner}/{name}/pulls/{number}/session` | | |
| 83 | + | ||
| 84 | + | See [sessions and why-blame](/guides/why-blame/). | |
| 85 | + | ||
| 86 | + | ## Plans | |
| 87 | + | ||
| 88 | + | | Tool | Required | What it does | Route | | |
| 89 | + | | --- | --- | --- | --- | | |
| 90 | + | | `plan_work` | `repo`, `brief` | Have an agent turn an outcome into proposed issues with checks and dependencies. Returns the plan's id at once. Members only. | `POST /repos/{owner}/{name}/plans` | | |
| 91 | + | | `get_plan` | `repo`, `plan` | The plan: its status (`planning`, `ready`, `failed` or `applied`), the issues it proposes, and once applied, where each stands. | `GET /repos/{owner}/{name}/plans/{plan}` | | |
| 92 | + | | `apply_plan` | `repo`, `plan` | Open its issues. `assign` puts g1t agents on them in dependency order; `keep` opens only some, by position from 1. | `POST /repos/{owner}/{name}/plans/{plan}/apply` | | |
| 93 | + | ||
| 94 | + | See [hand off an outcome](/guides/outcomes/). | |
| 95 | + | ||
| 96 | + | ## Merge queue | |
| 97 | + | ||
| 98 | + | | Tool | Required | What it does | Route | | |
| 99 | + | | --- | --- | --- | --- | | |
| 100 | + | | `get_merge_queue` | `repo` | The pull requests waiting to land, in order, each with the state it is tested in and how that went; then those that recently landed or left. | `GET /repos/{owner}/{name}/queue` | | |
| 101 | + | ||
| 102 | + | See [merge queue](/guides/merge-queue/). | |
| 103 | + | ||
| 104 | + | ## Messages | |
| 105 | + | ||
| 106 | + | | Tool | Required | What it does | Route | | |
| 107 | + | | --- | --- | --- | --- | | |
| 108 | + | | `message_agent` | `repo`, `number`, `body` | Send the agent working on a pull request a message, received at its next step. A g1t agent sends a `question` or a `handoff`, with its own pull request as `from_number`. | `POST /repos/{owner}/{name}/pulls/{number}/messages` | | |
| 109 | + | | `answer_message` | `repo`, `id`, `body` | Answer a question or a handoff by the message's id; `decline` a handoff that is not yours. The answer reaches the asking agent at its next step. | `POST /repos/{owner}/{name}/messages/{id}/answer` | | |
| 110 | + | | `take_messages` | `repo`, `number` | For a g1t agent at work: the messages it has not seen yet, each returned once. | `POST /repos/{owner}/{name}/pulls/{number}/messages/take` | | |
| 111 | + | ||
| 112 | + | See [talk to agents](/guides/talking-to-agents/). | |
| 113 | + | ||
| 114 | + | ## What a g1t agent can use | |
| 115 | + | ||
| 116 | + | A g1t agent works with a token limited to its own repository and to these | |
| 117 | + | tools: `get_repo`, `list_issues`, `get_issue`, `list_labels`, | |
| 118 | + | `create_issue`, `add_comment`, `list_pull_requests`, `get_pull_request`, | |
| 119 | + | `get_pull_request_changes`, `read_session`, `get_merge_queue`, | |
| 120 | + | `list_events`, `take_messages`, `message_agent` and `answer_message`. | |
| 121 | + | `tools/list` shows such a token only the tools it may use. |
| 9 | 9 | darkMode: true, | |
| 10 | 10 | hideDarkModeToggle: true, | |
| 11 | 11 | hideClientButton: true, | |
| 12 | + | hideModels: true, | |
| 12 | 13 | defaultHttpClient: { targetKey: 'shell', clientKey: 'curl' }, | |
| 13 | 14 | }; | |
| 14 | 15 | --- | |
| 34 | 35 | </head> | |
| 35 | 36 | <body> | |
| 36 | 37 | <header class="bar"> | |
| 37 | − | <a class="brand" href="https://g1t.sh/">g<span>1</span>t</a> | |
| 38 | − | <a href="/">Docs</a> | |
| 39 | − | <a href="/reference/api/">API overview</a> | |
| 40 | − | <a href="https://api.g1t.sh/openapi.json">OpenAPI</a> | |
| 38 | + | <a class="brand" href="/" aria-label="g1t docs home"> | |
| 39 | + | <svg viewBox="0 0 32 32" aria-hidden="true"> | |
| 40 | + | <path d="M16 2.5 28 9.4 16 16.3 4 9.4Z" fill="currentColor"></path> | |
| 41 | + | <path d="M4 10.9 15.3 17.4V30.2L4 23.7Z" fill="currentColor" fill-opacity="0.55"></path> | |
| 42 | + | <path d="M28 10.9 16.7 17.4V30.2L28 23.7Z" fill="currentColor" fill-opacity="0.25"></path> | |
| 43 | + | </svg> | |
| 44 | + | <b>g1t</b> | |
| 45 | + | <span class="pill">Docs</span> | |
| 46 | + | </a> | |
| 47 | + | <nav> | |
| 48 | + | <a href="/">Guides</a> | |
| 49 | + | <a href="/reference/api/">API overview</a> | |
| 50 | + | <a href="/reference/mcp/">MCP tools</a> | |
| 51 | + | <a href="https://api.g1t.sh/openapi.json">OpenAPI</a> | |
| 52 | + | <a href="https://g1t.sh/register" class="cta">Sign up</a> | |
| 53 | + | </nav> | |
| 41 | 54 | </header> | |
| 42 | 55 | <script | |
| 43 | 56 | is:inline | |
| 67 | 80 | --scalar-color-1: var(--g1t-fg); | |
| 68 | 81 | --scalar-color-2: var(--g1t-muted); | |
| 69 | 82 | --scalar-color-3: var(--g1t-faint); | |
| 70 | − | --scalar-color-accent: var(--g1t-accent); | |
| 71 | − | --scalar-background-accent: color-mix(in srgb, var(--g1t-accent) 12%, transparent); | |
| 83 | + | --scalar-color-accent: #cfc6ff; | |
| 84 | + | --scalar-background-accent: color-mix(in srgb, var(--g1t-merged) 12%, transparent); | |
| 72 | 85 | --scalar-button-1: var(--g1t-fg); | |
| 73 | 86 | --scalar-button-1-color: var(--g1t-bg); | |
| 74 | 87 | --scalar-button-1-hover: #ffffff; | |
| 82 | 95 | --scalar-sidebar-border-color: var(--g1t-line); | |
| 83 | 96 | --scalar-sidebar-item-hover-background: var(--g1t-surface); | |
| 84 | 97 | --scalar-sidebar-item-active-background: var(--g1t-raised); | |
| 85 | − | --scalar-sidebar-color-active: var(--g1t-accent); | |
| 98 | + | --scalar-sidebar-color-active: var(--g1t-fg); | |
| 86 | 99 | } | |
| 87 | 100 | ||
| 88 | 101 | .bar { | |
| 102 | + | position: sticky; | |
| 103 | + | top: 0; | |
| 104 | + | z-index: 10; | |
| 89 | 105 | display: flex; | |
| 90 | 106 | align-items: center; | |
| 91 | − | gap: 16px; | |
| 107 | + | justify-content: space-between; | |
| 92 | 108 | height: 56px; | |
| 93 | − | padding: 0 16px; | |
| 94 | − | background: var(--g1t-surface); | |
| 109 | + | padding: 0 20px; | |
| 110 | + | background: color-mix(in srgb, var(--g1t-bg) 88%, transparent); | |
| 111 | + | backdrop-filter: blur(10px); | |
| 95 | 112 | border-bottom: 1px solid var(--g1t-line); | |
| 96 | 113 | font: 14px var(--g1t-font-sans); | |
| 97 | 114 | } | |
| 99 | 116 | color: var(--g1t-muted); | |
| 100 | 117 | text-decoration: none; | |
| 101 | 118 | } | |
| 102 | − | .bar a:hover { | |
| 119 | + | .bar .brand { | |
| 120 | + | display: inline-flex; | |
| 121 | + | align-items: center; | |
| 122 | + | gap: 9px; | |
| 103 | 123 | color: var(--g1t-fg); | |
| 104 | 124 | } | |
| 105 | − | .bar .brand { | |
| 106 | − | font: 600 18px var(--g1t-font-mono); | |
| 125 | + | .bar .brand svg { | |
| 126 | + | width: 21px; | |
| 127 | + | height: 21px; | |
| 128 | + | } | |
| 129 | + | .bar .brand b { | |
| 130 | + | font-size: 17px; | |
| 131 | + | letter-spacing: -0.035em; | |
| 132 | + | } | |
| 133 | + | .bar .pill { | |
| 134 | + | border-radius: 999px; | |
| 135 | + | padding: 1px 8px; | |
| 136 | + | font-size: 11.5px; | |
| 137 | + | color: var(--g1t-muted); | |
| 138 | + | box-shadow: inset 0 0 0 1px var(--g1t-line-strong); | |
| 139 | + | } | |
| 140 | + | .bar nav { | |
| 141 | + | display: flex; | |
| 142 | + | align-items: center; | |
| 143 | + | gap: 4px; | |
| 144 | + | } | |
| 145 | + | .bar nav a { | |
| 146 | + | border-radius: 6px; | |
| 147 | + | padding: 5px 10px; | |
| 148 | + | font-size: 13.5px; | |
| 149 | + | } | |
| 150 | + | .bar nav a:hover { | |
| 151 | + | background: var(--g1t-raised); | |
| 107 | 152 | color: var(--g1t-fg); | |
| 108 | 153 | } | |
| 109 | − | .bar .brand span { | |
| 110 | − | color: var(--g1t-accent); | |
| 154 | + | .bar nav a.cta { | |
| 155 | + | margin-left: 4px; | |
| 156 | + | background: var(--g1t-fg); | |
| 157 | + | color: var(--g1t-bg); | |
| 158 | + | font-weight: 500; | |
| 159 | + | } | |
| 160 | + | @media (max-width: 760px) { | |
| 161 | + | .bar nav a:not(.cta) { | |
| 162 | + | display: none; | |
| 163 | + | } | |
| 111 | 164 | } | |
| 112 | 165 | </style> |
| 1 | − | /* Starlight's names for the shared g1t tokens. The docs are dark, like the site. */ | |
| 1 | + | /* | |
| 2 | + | * g1t's docs: Starlight in g1t's own design. A very dark gray base, | |
| 3 | + | * lavender as the accent for links and the current page, quiet | |
| 4 | + | * typography, and one theme. | |
| 5 | + | */ | |
| 2 | 6 | :root, | |
| 3 | 7 | :root[data-theme='light'] { | |
| 4 | 8 | --sl-font: var(--g1t-font-sans); | |
| 5 | 9 | --sl-font-mono: var(--g1t-font-mono); | |
| 6 | 10 | ||
| 7 | − | --sl-color-accent-low: var(--g1t-accent-low); | |
| 8 | − | --sl-color-accent: var(--g1t-accent-dim); | |
| 9 | − | --sl-color-accent-high: var(--g1t-accent); | |
| 11 | + | /* Lavender is the docs' accent: links, the current page, highlights. */ | |
| 12 | + | --sl-color-accent-low: color-mix(in srgb, var(--g1t-merged) 14%, var(--g1t-bg)); | |
| 13 | + | --sl-color-accent: var(--g1t-merged); | |
| 14 | + | --sl-color-accent-high: #d9d1ff; | |
| 10 | 15 | ||
| 11 | 16 | --sl-color-white: var(--g1t-fg); | |
| 12 | 17 | --sl-color-gray-1: var(--g1t-fg-soft); | |
| 19 | 24 | --sl-color-black: var(--g1t-bg); | |
| 20 | 25 | ||
| 21 | 26 | --sl-color-bg: var(--g1t-bg); | |
| 22 | − | --sl-color-bg-nav: var(--g1t-surface); | |
| 27 | + | --sl-color-bg-nav: color-mix(in srgb, var(--g1t-bg) 88%, transparent); | |
| 23 | 28 | --sl-color-bg-sidebar: var(--g1t-bg); | |
| 24 | 29 | --sl-color-hairline: var(--g1t-line); | |
| 25 | 30 | --sl-color-hairline-light: var(--g1t-line); | |
| 26 | − | --sl-color-hairline-shade: var(--g1t-surface); | |
| 31 | + | --sl-color-hairline-shade: var(--g1t-line); | |
| 27 | 32 | --sl-color-text: var(--g1t-fg-soft); | |
| 28 | − | --sl-color-text-accent: var(--g1t-accent); | |
| 33 | + | --sl-color-text-accent: #cfc6ff; | |
| 29 | 34 | --sl-color-text-invert: var(--g1t-bg); | |
| 30 | 35 | --sl-color-bg-inline-code: var(--g1t-raised); | |
| 31 | 36 | ||
| 37 | + | --sl-text-body: 0.9375rem; | |
| 38 | + | --sl-line-height: 1.75; | |
| 39 | + | --sl-content-width: 46rem; | |
| 40 | + | --sl-nav-height: 3.5rem; | |
| 41 | + | --sl-sidebar-width: 17rem; | |
| 42 | + | ||
| 32 | 43 | color-scheme: dark; | |
| 33 | 44 | } | |
| 34 | 45 | ||
| 37 | 48 | display: none; | |
| 38 | 49 | } | |
| 39 | 50 | ||
| 40 | − | .sl-markdown-content :is(h1, h2, h3) { | |
| 51 | + | /* --- Header --------------------------------------------------------------- */ | |
| 52 | + | ||
| 53 | + | header.header { | |
| 54 | + | backdrop-filter: blur(10px); | |
| 55 | + | border-bottom: 1px solid var(--g1t-line); | |
| 56 | + | } | |
| 57 | + | site-search button[data-open-modal] { | |
| 58 | + | border-radius: 0.5rem; | |
| 59 | + | background: var(--g1t-surface); | |
| 60 | + | border-color: var(--g1t-line); | |
| 61 | + | color: var(--g1t-faint); | |
| 62 | + | } | |
| 63 | + | site-search button[data-open-modal]:hover { | |
| 64 | + | border-color: var(--g1t-line-strong); | |
| 65 | + | color: var(--g1t-muted); | |
| 66 | + | } | |
| 67 | + | ||
| 68 | + | /* --- Sidebar -------------------------------------------------------------- */ | |
| 69 | + | ||
| 70 | + | .sidebar-content { | |
| 71 | + | padding-top: 1.25rem; | |
| 72 | + | } | |
| 73 | + | /* Group labels: small and quiet, like section names, not links. */ | |
| 74 | + | .sidebar-content details > summary .group-label .large, | |
| 75 | + | .sidebar-content .top-level > li > details > summary { | |
| 76 | + | font-size: 0.75rem; | |
| 77 | + | font-weight: 600; | |
| 78 | + | letter-spacing: 0.06em; | |
| 79 | + | text-transform: uppercase; | |
| 80 | + | color: var(--g1t-faint); | |
| 81 | + | } | |
| 82 | + | .sidebar-content ul ul, | |
| 83 | + | .sidebar-content ul ul li { | |
| 84 | + | border-inline-start: 0; | |
| 85 | + | margin-inline-start: 0; | |
| 86 | + | padding-inline-start: 0; | |
| 87 | + | } | |
| 88 | + | .sidebar-content a { | |
| 89 | + | border-radius: 0.375rem; | |
| 90 | + | padding: 0.32rem 0.6rem; | |
| 91 | + | font-size: 0.875rem; | |
| 92 | + | color: var(--g1t-muted); | |
| 93 | + | } | |
| 94 | + | .sidebar-content a:hover { | |
| 95 | + | background: var(--g1t-surface); | |
| 96 | + | color: var(--g1t-fg); | |
| 97 | + | } | |
| 98 | + | /* The current page: brighter text and a lavender mark, not a filled bar. */ | |
| 99 | + | .sidebar-content a[aria-current='page'], | |
| 100 | + | .sidebar-content a[aria-current='page']:hover { | |
| 101 | + | background: var(--g1t-surface); | |
| 102 | + | color: var(--g1t-fg); | |
| 103 | + | font-weight: 500; | |
| 104 | + | box-shadow: inset 2px 0 0 var(--g1t-merged); | |
| 105 | + | } | |
| 106 | + | ||
| 107 | + | /* --- Content -------------------------------------------------------------- */ | |
| 108 | + | ||
| 109 | + | .content-panel { | |
| 110 | + | padding-top: 2rem; | |
| 111 | + | } | |
| 112 | + | .sl-markdown-content h1, | |
| 113 | + | h1#_top { | |
| 114 | + | font-size: 2.25rem; | |
| 115 | + | font-weight: 650; | |
| 116 | + | letter-spacing: -0.03em; | |
| 117 | + | line-height: 1.15; | |
| 118 | + | color: var(--g1t-fg); | |
| 119 | + | } | |
| 120 | + | /* Each section opens with a rule across the full column. */ | |
| 121 | + | .sl-markdown-content .sl-heading-wrapper.level-h2 { | |
| 122 | + | margin-top: 3rem; | |
| 123 | + | padding-top: 1.75rem; | |
| 124 | + | border-top: 1px solid var(--g1t-line); | |
| 125 | + | } | |
| 126 | + | .sl-markdown-content h2 { | |
| 127 | + | font-size: 1.4rem; | |
| 128 | + | font-weight: 650; | |
| 41 | 129 | letter-spacing: -0.02em; | |
| 130 | + | color: var(--g1t-fg); | |
| 42 | 131 | } | |
| 132 | + | .sl-markdown-content h3 { | |
| 133 | + | margin-top: 2rem; | |
| 134 | + | font-size: 1.1rem; | |
| 135 | + | font-weight: 600; | |
| 136 | + | letter-spacing: -0.01em; | |
| 137 | + | color: var(--g1t-fg); | |
| 138 | + | } | |
| 139 | + | .sl-markdown-content p, | |
| 140 | + | .sl-markdown-content li { | |
| 141 | + | color: var(--g1t-fg-soft); | |
| 142 | + | } | |
| 143 | + | .sl-markdown-content a:not(.card, .sl-link-button, .sl-link-card) { | |
| 144 | + | color: #cfc6ff; | |
| 145 | + | text-decoration-color: color-mix(in srgb, var(--g1t-merged) 45%, transparent); | |
| 146 | + | text-underline-offset: 0.2em; | |
| 147 | + | } | |
| 148 | + | .sl-markdown-content a:not(.card, .sl-link-button, .sl-link-card):hover { | |
| 149 | + | text-decoration-color: var(--g1t-merged); | |
| 150 | + | } | |
| 151 | + | .sl-markdown-content :not(pre) > code { | |
| 152 | + | border-radius: 0.3rem; | |
| 153 | + | padding: 0.1rem 0.35rem; | |
| 154 | + | font-size: 0.85em; | |
| 155 | + | color: var(--g1t-fg); | |
| 156 | + | box-shadow: inset 0 0 0 1px var(--g1t-line); | |
| 157 | + | } | |
| 43 | 158 | ||
| 44 | − | .hero h1 { | |
| 45 | − | letter-spacing: -0.035em; | |
| 159 | + | /* Tables: ruled, not boxed. */ | |
| 160 | + | .sl-markdown-content table { | |
| 161 | + | display: table; | |
| 162 | + | width: 100%; | |
| 163 | + | border-collapse: collapse; | |
| 164 | + | font-size: 0.875rem; | |
| 165 | + | } | |
| 166 | + | .sl-markdown-content th { | |
| 167 | + | border-bottom: 1px solid var(--g1t-line-strong); | |
| 168 | + | background: transparent; | |
| 169 | + | font-weight: 600; | |
| 170 | + | color: var(--g1t-muted); | |
| 171 | + | text-align: start; | |
| 172 | + | } | |
| 173 | + | .sl-markdown-content td, | |
| 174 | + | .sl-markdown-content th { | |
| 175 | + | padding: 0.6rem 0.75rem; | |
| 176 | + | border-inline: 0; | |
| 177 | + | border-top: 0; | |
| 178 | + | } | |
| 179 | + | .sl-markdown-content td { | |
| 180 | + | border-bottom: 1px solid var(--g1t-line); | |
| 181 | + | vertical-align: top; | |
| 182 | + | } | |
| 183 | + | .sl-markdown-content tr:nth-child(2n) { | |
| 184 | + | background: transparent; | |
| 46 | 185 | } | |
| 47 | 186 | ||
| 48 | − | .sl-link-button.primary { | |
| 49 | − | background: var(--g1t-accent); | |
| 187 | + | /* Callouts: a tinted panel with a coloured edge. */ | |
| 188 | + | .starlight-aside { | |
| 189 | + | border: 0; | |
| 190 | + | border-inline-start: 2px solid; | |
| 191 | + | border-radius: 0 0.6rem 0.6rem 0; | |
| 192 | + | padding: 0.85rem 1.1rem; | |
| 193 | + | } | |
| 194 | + | .starlight-aside--note { | |
| 195 | + | border-color: var(--g1t-info); | |
| 196 | + | background: color-mix(in srgb, var(--g1t-info) 7%, var(--g1t-bg)); | |
| 197 | + | } | |
| 198 | + | .starlight-aside--tip { | |
| 50 | 199 | border-color: var(--g1t-accent); | |
| 51 | − | color: var(--g1t-bg); | |
| 200 | + | background: color-mix(in srgb, var(--g1t-accent) 6%, var(--g1t-bg)); | |
| 52 | 201 | } | |
| 202 | + | .starlight-aside--caution { | |
| 203 | + | border-color: var(--g1t-warn); | |
| 204 | + | background: color-mix(in srgb, var(--g1t-warn) 7%, var(--g1t-bg)); | |
| 205 | + | } | |
| 206 | + | .starlight-aside--danger { | |
| 207 | + | border-color: var(--g1t-danger); | |
| 208 | + | background: color-mix(in srgb, var(--g1t-danger) 7%, var(--g1t-bg)); | |
| 209 | + | } | |
| 210 | + | ||
| 211 | + | /* --- On this page --------------------------------------------------------- */ | |
| 53 | 212 | ||
| 54 | − | .card { | |
| 213 | + | .right-sidebar-panel h2 { | |
| 214 | + | font-size: 0.75rem; | |
| 215 | + | font-weight: 600; | |
| 216 | + | letter-spacing: 0.06em; | |
| 217 | + | text-transform: uppercase; | |
| 218 | + | color: var(--g1t-faint); | |
| 219 | + | } | |
| 220 | + | .right-sidebar-panel a { | |
| 221 | + | font-size: 0.8125rem; | |
| 222 | + | color: var(--g1t-muted); | |
| 223 | + | } | |
| 224 | + | .right-sidebar-panel a:hover { | |
| 225 | + | color: var(--g1t-fg); | |
| 226 | + | } | |
| 227 | + | .right-sidebar-panel a[aria-current='true'] { | |
| 228 | + | color: #cfc6ff; | |
| 229 | + | } | |
| 230 | + | ||
| 231 | + | /* --- Cards and buttons ---------------------------------------------------- */ | |
| 232 | + | ||
| 233 | + | .card, | |
| 234 | + | .sl-link-card { | |
| 235 | + | border-radius: 1rem; | |
| 236 | + | background: var(--g1t-surface); | |
| 237 | + | border: 1px solid var(--g1t-line); | |
| 238 | + | transition: border-color 0.15s; | |
| 239 | + | } | |
| 240 | + | .sl-link-card:hover { | |
| 241 | + | border-color: var(--g1t-line-strong); | |
| 55 | 242 | background: var(--g1t-surface); | |
| 243 | + | } | |
| 244 | + | .sl-link-button { | |
| 245 | + | border-radius: 0.5rem; | |
| 246 | + | font-size: 0.9rem; | |
| 247 | + | font-weight: 500; | |
| 248 | + | } | |
| 249 | + | .sl-link-button.primary { | |
| 250 | + | background: var(--g1t-fg); | |
| 251 | + | border-color: var(--g1t-fg); | |
| 252 | + | color: var(--g1t-bg); | |
| 253 | + | } | |
| 254 | + | .sl-link-button.primary:hover { | |
| 255 | + | background: #fff; | |
| 256 | + | } | |
| 257 | + | .sl-link-button.minimal { | |
| 258 | + | color: var(--g1t-fg-soft); | |
| 259 | + | } | |
| 260 | + | ||
| 261 | + | /* --- Pagination and footer ----------------------------------------------- */ | |
| 262 | + | ||
| 263 | + | .pagination-links a { | |
| 264 | + | border-radius: 0.75rem; | |
| 56 | 265 | border-color: var(--g1t-line); | |
| 57 | − | border-radius: 0.75rem; | |
| 266 | + | box-shadow: none; | |
| 267 | + | } | |
| 268 | + | .pagination-links a:hover { | |
| 269 | + | border-color: var(--g1t-line-strong); | |
| 270 | + | } | |
| 271 | + | .pagination-links a .link-title { | |
| 272 | + | color: var(--g1t-fg); | |
| 273 | + | } | |
| 274 | + | .meta, | |
| 275 | + | .meta a { | |
| 276 | + | font-size: 0.8125rem; | |
| 277 | + | color: var(--g1t-faint); | |
| 278 | + | } | |
| 279 | + | ||
| 280 | + | /* --- The home page -------------------------------------------------------- */ | |
| 281 | + | ||
| 282 | + | /* The home page brings its own heading, so Starlight's title bar goes. */ | |
| 283 | + | main:has(.g1t-home-hero) > .content-panel:first-child { | |
| 284 | + | display: none; | |
| 285 | + | } | |
| 286 | + | main:has(.g1t-home-hero) > .content-panel { | |
| 287 | + | border-top: 0; | |
| 288 | + | } | |
| 289 | + | .g1t-home-hero { | |
| 290 | + | padding: 1rem 0 0.5rem; | |
| 291 | + | } | |
| 292 | + | .sl-markdown-content .g1t-eyebrow { | |
| 293 | + | font-family: var(--g1t-font-mono); | |
| 294 | + | font-size: 0.72rem; | |
| 295 | + | letter-spacing: 0.2em; | |
| 296 | + | text-transform: uppercase; | |
| 297 | + | color: var(--g1t-merged); | |
| 298 | + | } | |
| 299 | + | .g1t-home-hero h1 { | |
| 300 | + | margin: 0.75rem 0 0; | |
| 301 | + | font-size: clamp(2.25rem, 5vw, 3.25rem); | |
| 302 | + | font-weight: 650; | |
| 303 | + | letter-spacing: -0.035em; | |
| 304 | + | line-height: 1.05; | |
| 305 | + | color: var(--g1t-fg); | |
| 306 | + | border: 0; | |
| 307 | + | padding: 0; | |
| 308 | + | } | |
| 309 | + | .g1t-home-hero p { | |
| 310 | + | max-width: 38rem; | |
| 311 | + | margin-top: 1rem; | |
| 312 | + | font-size: 1.05rem; | |
| 313 | + | color: var(--g1t-muted); | |
| 314 | + | } | |
| 315 | + | .g1t-paths { | |
| 316 | + | display: grid; | |
| 317 | + | gap: 0.75rem; | |
| 318 | + | grid-template-columns: repeat(auto-fit, minmax(15rem, 1fr)); | |
| 319 | + | margin-top: 2rem; | |
| 320 | + | } | |
| 321 | + | .g1t-path { | |
| 322 | + | display: block; | |
| 323 | + | border-radius: 1rem; | |
| 324 | + | padding: 1.1rem 1.2rem; | |
| 325 | + | background: var(--g1t-surface); | |
| 326 | + | border: 1px solid var(--g1t-line); | |
| 327 | + | text-decoration: none !important; | |
| 328 | + | transition: border-color 0.15s, transform 0.15s; | |
| 329 | + | } | |
| 330 | + | .g1t-path:hover { | |
| 331 | + | border-color: var(--g1t-line-strong); | |
| 332 | + | transform: translateY(-1px); | |
| 333 | + | } | |
| 334 | + | .g1t-path strong { | |
| 335 | + | display: block; | |
| 336 | + | font-size: 0.95rem; | |
| 337 | + | color: var(--g1t-fg); | |
| 338 | + | } | |
| 339 | + | .g1t-path span { | |
| 340 | + | display: block; | |
| 341 | + | margin-top: 0.35rem; | |
| 342 | + | font-size: 0.85rem; | |
| 343 | + | line-height: 1.55; | |
| 344 | + | color: var(--g1t-muted); | |
| 345 | + | } | |
| 346 | + | .g1t-path em { | |
| 347 | + | display: inline-block; | |
| 348 | + | margin-bottom: 0.6rem; | |
| 349 | + | font-family: var(--g1t-font-mono); | |
| 350 | + | font-size: 0.68rem; | |
| 351 | + | font-style: normal; | |
| 352 | + | letter-spacing: 0.14em; | |
| 353 | + | text-transform: uppercase; | |
| 354 | + | color: var(--g1t-merged); | |
| 355 | + | } | |
| 356 | + | .g1t-columns { | |
| 357 | + | display: grid; | |
| 358 | + | gap: 2rem; | |
| 359 | + | grid-template-columns: repeat(auto-fit, minmax(13rem, 1fr)); | |
| 360 | + | margin-top: 3rem !important; | |
| 361 | + | } | |
| 362 | + | .g1t-columns > div, | |
| 363 | + | .g1t-paths > a { | |
| 364 | + | margin-top: 0 !important; | |
| 365 | + | } | |
| 366 | + | .g1t-columns h3 { | |
| 367 | + | margin: 0 0 0.5rem; | |
| 368 | + | font-size: 0.8rem; | |
| 369 | + | font-weight: 600; | |
| 370 | + | letter-spacing: 0.06em; | |
| 371 | + | text-transform: uppercase; | |
| 372 | + | color: var(--g1t-faint); | |
| 373 | + | } | |
| 374 | + | .g1t-columns ul { | |
| 375 | + | margin: 0; | |
| 376 | + | padding: 0; | |
| 377 | + | list-style: none; | |
| 378 | + | } | |
| 379 | + | .g1t-columns li { | |
| 380 | + | margin: 0.3rem 0; | |
| 381 | + | } | |
| 382 | + | .g1t-columns a { | |
| 383 | + | font-size: 0.9rem; | |
| 384 | + | color: var(--g1t-fg-soft) !important; | |
| 385 | + | text-decoration: none !important; | |
| 386 | + | } | |
| 387 | + | .g1t-columns a:hover { | |
| 388 | + | color: #cfc6ff !important; | |
| 58 | 389 | } |
| 1 | 1 | # g1t | |
| 2 | 2 | ||
| 3 | − | > g1t (https://g1t.sh) is a git forge built for AI agents. It is ordinary git | |
| 4 | − | > over HTTPS, with issues and pull requests, built so that many agents can | |
| 5 | − | > work on the same issue at once. Each pull request lives in its own fork | |
| 6 | − | > and carries a recording of how it was made. Several can be opened for one | |
| 7 | − | > issue; merging one closes the issue and records which one resolved it. | |
| 3 | + | > g1t (https://g1t.sh) is a git forge where a team of agents ships the work. | |
| 4 | + | > It is ordinary git over HTTPS, with issues and pull requests. You hand it | |
| 5 | + | > an outcome; a planner splits it into issues with dependencies, agents work | |
| 6 | + | > them in parallel and talk to each other, and a merge queue lands each | |
| 7 | + | > change on main only once it passes together with everything ahead of it. | |
| 8 | + | > Each pull request lives in its own fork and carries a recording of how it | |
| 9 | + | > was made. | |
| 8 | 10 | ||
| 9 | 11 | This file tells an assistant everything needed to get a person set up on g1t | |
| 10 | 12 | and working. You never ask for, see, or send the person's password. Accounts | |
| 88 | 90 | Or let git ask: the username is the g1t username and the password is the | |
| 89 | 91 | token. | |
| 90 | 92 | ||
| 93 | + | 8. **Record Claude Code sessions automatically** (optional). This installs | |
| 94 | + | hooks that record prompts, tool calls and replies onto the g1t pull | |
| 95 | + | request for the branch being worked on. The person runs it, because it | |
| 96 | + | signs them in through their browser: | |
| 97 | + | ||
| 98 | + | ```sh | |
| 99 | + | curl -fsSL https://g1t.sh/install/claude.sh | sh | |
| 100 | + | ``` | |
| 101 | + | ||
| 91 | 102 | ## Do work | |
| 92 | 103 | ||
| 93 | 104 | Issues and pull requests are addressed by repository and number, and share | |
| 135 | 146 | `{"keep_issue_open": true}` if this is only part of the work. A `409` | |
| 136 | 147 | saying main has moved means the fork is behind: pull main from | |
| 137 | 148 | `https://g1t.sh/{owner}/{name}.git` into the fork, push, and merge again. | |
| 149 | + | With the merge queue on, merging adds the pull request to the queue | |
| 150 | + | instead; `GET {repo}/queue` shows it being tested with the pull requests | |
| 151 | + | ahead of it, and it lands only if that combination passes. | |
| 152 | + | ||
| 153 | + | ## Hand work to g1t agents | |
| 154 | + | ||
| 155 | + | g1t agents are in preview and enabled only for some workspaces. Elsewhere | |
| 156 | + | these calls answer with a message saying so. | |
| 157 | + | ||
| 158 | + | - **Hand off an outcome:** `POST {repo}/plans` with `brief`: what should be | |
| 159 | + | true when the work is done. A planner reads the repository and proposes | |
| 160 | + | issues, each with its checks, the files it touches, and what it depends | |
| 161 | + | on. Read it with `GET {repo}/plans/{plan}` until `status` is `ready` | |
| 162 | + | (a minute or two), then `POST {repo}/plans/{plan}/apply` with | |
| 163 | + | `{"assign": true}`. Agents start at once on every issue that depends on | |
| 164 | + | nothing and on the rest as what they depend on lands. `keep` opens only | |
| 165 | + | some of the issues, by position counting from 1. | |
| 166 | + | - **Assign one issue:** `POST {repo}/issues/{number}/assign`. The agent | |
| 167 | + | opens a pull request, meets the issue's checks, is reviewed by a second | |
| 168 | + | agent, revises, and catches up when main moves. There is no model or | |
| 169 | + | agent count to choose: to put more agents to work, assign more issues. | |
| 170 | + | - **Steer a working agent:** `POST {repo}/pulls/{number}/messages` with | |
| 171 | + | `body`. It reads the message at its next step. | |
| 172 | + | - **g1t agents talk to each other.** A g1t agent asks the agent on another | |
| 173 | + | pull request a question, or hands it work, with `message_agent` (`kind` | |
| 174 | + | `question` or `handoff`, and `from_number`, its own pull request). The | |
| 175 | + | other agent replies with `answer_message` | |
| 176 | + | (`POST {repo}/messages/{id}/answer`). Plans show these exchanges under | |
| 177 | + | "Agents talking". From any other caller, `message_agent` sends a plain | |
| 178 | + | message. | |
| 138 | 179 | ||
| 139 | 180 | Every one of these is also an MCP tool: `list_issues`, `get_issue`, | |
| 140 | − | `create_issue`, `update_issue`, `close_issue`, `reopen_issue`, `assign_issue`, `plan_work`, `get_plan`, `apply_plan`, | |
| 141 | − | `list_labels`, `add_comment`, `list_pull_requests`, `get_pull_request`, | |
| 181 | + | `create_issue`, `update_issue`, `close_issue`, `reopen_issue`, | |
| 182 | + | `assign_issue`, `plan_work`, `get_plan`, `apply_plan`, `list_labels`, | |
| 183 | + | `add_comment`, `list_pull_requests`, `get_pull_request`, | |
| 142 | 184 | `create_pull_request`, `record_session`, `read_session`, | |
| 143 | 185 | `mark_pull_request_ready`, `close_pull_request`, | |
| 144 | − | `get_pull_request_changes`, `review_pull_request`, `merge_pull_request`, and `list_repos`, | |
| 145 | − | `get_repo`, `create_repo`, `update_repo`, `get_repo_settings`, `update_repo_settings`, `list_events`, `create_workspace`, `whoami`. | |
| 146 | − | MCP tools take the repository as `repo`, written `owner/name`. | |
| 186 | + | `get_pull_request_changes`, `review_pull_request`, `merge_pull_request`, | |
| 187 | + | `get_merge_queue`, `message_agent`, `answer_message`, `take_messages`, | |
| 188 | + | `list_repos`, `get_repo`, `create_repo`, `update_repo`, | |
| 189 | + | `get_repo_settings`, `update_repo_settings`, `list_events`, | |
| 190 | + | `create_workspace`, and `whoami`. MCP tools take the repository as `repo`, | |
| 191 | + | written `owner/name`. | |
| 147 | 192 | ||
| 148 | 193 | ## Facts | |
| 149 | 194 | ||
| 169 | 214 | ## More | |
| 170 | 215 | ||
| 171 | 216 | - [Quickstart](https://docs.g1t.sh/quickstart/) | |
| 172 | − | - [Concepts](https://docs.g1t.sh/concepts/overview/) | |
| 217 | + | - [How g1t works](https://docs.g1t.sh/concepts/overview/) | |
| 218 | + | - [g1t agents](https://docs.g1t.sh/guides/g1t-agents/) | |
| 219 | + | - [Outcomes and plans](https://docs.g1t.sh/guides/outcomes/) | |
| 220 | + | - [Talking to agents](https://docs.g1t.sh/guides/talking-to-agents/) | |
| 221 | + | - [Bring your own agent](https://docs.g1t.sh/guides/bring-your-own-agent/) | |
| 222 | + | - [The merge queue](https://docs.g1t.sh/guides/merge-queue/) | |
| 223 | + | - [Sessions and why-blame](https://docs.g1t.sh/guides/why-blame/) | |
| 173 | 224 | - [Forks and branches](https://docs.g1t.sh/concepts/forks/) | |
| 174 | − | - [Accounts and authentication](https://docs.g1t.sh/guides/authentication/) | |
| 225 | + | - [Accounts and sign-in](https://docs.g1t.sh/guides/authentication/) | |
| 226 | + | - [Workspaces and tokens](https://docs.g1t.sh/guides/workspaces/) | |
| 227 | + | - [Usage and billing](https://docs.g1t.sh/guides/usage-and-billing/) | |
| 175 | 228 | - [Git](https://docs.g1t.sh/guides/git/) | |
| 176 | − | - [g1t agents](https://docs.g1t.sh/guides/g1t-agents/) | |
| 177 | − | - [Bring your own agent](https://docs.g1t.sh/guides/bring-your-own-agent/) | |
| 229 | + | - [MCP tools](https://docs.g1t.sh/reference/mcp/) | |
| 178 | 230 | - [API reference](https://docs.g1t.sh/api/reference/) | |
| 179 | 231 | - [Source](https://g1t.sh/syntaqx/g1t), MIT licensed |