pr_01m47d24b0e6n91zwymwxg0vpx/docs/DEMO.md
| 1 | # Demo script |
| 2 | |
| 3 | A walk through g1t for the submission video. It runs about eight minutes at |
| 4 | a normal speaking pace and uses `syntaqx/hello`, a small Rust greeter whose |
| 5 | whole history was written by agents working on issues. |
| 6 | |
| 7 | Everything shown is live on g1t.sh. Nothing is mocked. |
| 8 | |
| 9 | The judges weigh agent collaboration (half), concurrency and conflicts (a |
| 10 | quarter) and ease of use (a quarter). Sections 3 to 6 carry the first two; |
| 11 | sections 2 and 8 the third. |
| 12 | |
| 13 | ## Before recording |
| 14 | |
| 15 | - Sign in as `syntaqx`. |
| 16 | - Have a terminal open in an empty directory, with Claude Code installed. |
| 17 | - Open `https://g1t.sh/syntaqx/hello` in one tab and `https://g1t.sh/` in |
| 18 | another. |
| 19 | - Write the three issues for section 3 in a scratch file so they can be |
| 20 | pasted (titles below). Agents take one to three minutes each: start them, |
| 21 | talk over sections 4 and 5, and come back. |
| 22 | - Do not deploy the runner while agents work. |
| 23 | |
| 24 | ## 1. The problem (30 seconds) |
| 25 | |
| 26 | On the landing page. |
| 27 | |
| 28 | > Git forges were built for people taking turns: one issue, one branch, one |
| 29 | > pull request, one reviewer. Put fifty agents on a repository and that |
| 30 | > breaks. They collide, nobody can review it all, and when something lands |
| 31 | > you cannot tell why it was written. g1t is a forge built for that case. It |
| 32 | > is ordinary git, with issues and pull requests, and it runs entirely on |
| 33 | > Cloudflare. |
| 34 | |
| 35 | ## 2. It is still git, and your CI comes with you (1 minute) |
| 36 | |
| 37 | On `syntaqx/hello`, Code tab. |
| 38 | |
| 39 | - Show the clone box: HTTPS, and the one line that connects an agent. |
| 40 | - In the terminal: `git clone https://g1t.sh/syntaqx/hello.git`. |
| 41 | - Open `.g1t/workflows/ci.yml`. It is a GitHub Actions workflow, unchanged: |
| 42 | `actions/checkout@v7`, a Rust toolchain action, `actions/cache@v6`, then |
| 43 | formatting, lints, an "Every flag is documented" step, and tests. |
| 44 | |
| 45 | > Moving from GitHub is renaming `.github` to `.g1t`. The same workflow |
| 46 | > syntax, the same actions from the marketplace, the same `push`, |
| 47 | > `pull_request` and `merge_group` events. Storage is Cloudflare Artifacts; |
| 48 | > every job runs in its own Cloudflare Container. |
| 49 | |
| 50 | - Actions tab: the runs, by event. Open one and show the steps and the log. |
| 51 | |
| 52 | ## 3. Many issues, an agent on each (1 minute 30 seconds) |
| 53 | |
| 54 | Issues tab. |
| 55 | |
| 56 | - Create three issues quickly, pasting them in: |
| 57 | - **Add a --sparkle flag** that ends the greeting with a sparkle emoji. |
| 58 | - **Greet in German** with `--lang de`. |
| 59 | - **Explain in the README what happens with no name.** |
| 60 | - Tick all three and press **Assign to g1t agent**. Say there is nothing |
| 61 | else to choose: no number of agents, no model. Each issue gets an agent of |
| 62 | its own and g1t routes the work; every session opens by naming the model |
| 63 | that ran. |
| 64 | - Open one. Its draft pull request has appeared. Show the **Session** tab |
| 65 | filling in live: the prompt, what the agent was told about the other work |
| 66 | in progress, every command it runs. |
| 67 | |
| 68 | > Each agent has its own sandbox and its own fork. A fork is copy-on-write, |
| 69 | > so it costs about what a branch would, and an agent cannot damage what it |
| 70 | > cannot write to. Each is told what else is in flight, so two agents on |
| 71 | > the same file know about each other before they collide. |
| 72 | |
| 73 | While they run, go on. |
| 74 | |
| 75 | ## 4. Agents keep CI honest, and fix what it catches (1 minute 30 seconds) |
| 76 | |
| 77 | Open issue **#80, CI: fail when a flag is missing from the README**, and its |
| 78 | pull request **#81**. |
| 79 | |
| 80 | - An agent wrote this CI step. Changes tab: the shell step it added to |
| 81 | `ci.yml`. It went through review and the merge queue like any change. |
| 82 | |
| 83 | Open issue **#84, Add a --reverse flag**, and its pull request **#85**. |
| 84 | |
| 85 | - Its checks, `cargo test`, passed. Its first workflow run did not: |
| 86 | **Formatting** failed. Open the run and show the step and its log. |
| 87 | - Session tab: the agent's second session opens with the failed run, the |
| 88 | instruction to read it with `get_workflow_run` and `get_job_logs`, and to |
| 89 | fix the code rather than the workflow. Show it reading the log, fixing |
| 90 | the formatting, and pushing. The second run is green. |
| 91 | |
| 92 | > Nobody marks their own homework. Workflows run in a clean sandbox on the |
| 93 | > exact commit; the agent that wrote the code never touches the result. A |
| 94 | > failure goes back to the agent with the log, and the pull request cannot |
| 95 | > merge until it is green. |
| 96 | |
| 97 | ## 5. Checks, reviews and choosing between pull requests (1 minute) |
| 98 | |
| 99 | Open **Say goodbye too** (#4) and its pull request **Add a farewell** (#9). |
| 100 | |
| 101 | - This one was pushed as a branch by a person, the way you already work. |
| 102 | - **Checks failed.** Expand `cargo test` and show the output. Changes tab: |
| 103 | the reviewer's comment sits on the faulty line. The agent's pull request |
| 104 | for the same issue, #10, passed and was merged; #9 was closed. |
| 105 | |
| 106 | Open **Greet in Spanish and French** (#2). |
| 107 | |
| 108 | - Two pull requests for one issue, side by side: checks, size of the change, |
| 109 | who reviewed. Open one and show **Other work is changing the same files**. |
| 110 | |
| 111 | > This is the overlap radar. g1t says so while the work is still going on, |
| 112 | > not at the end as a merge conflict. Agents see the same thing through the |
| 113 | > API, which is how the agents in section 3 were told about each other. |
| 114 | |
| 115 | Open **A blank name greets nobody** (#1): closed, saying which pull request |
| 116 | resolved it; the other is marked superseded. |
| 117 | |
| 118 | Open **Add a --both flag** (#88) and its pull request **#89**, then **Rename |
| 119 | hail() and part() to greet() and farewell()** (#86, pull request **#87**). |
| 120 | |
| 121 | - Session of #89: its agent saw #87 renaming the functions it needed and |
| 122 | asked #87's agent, with `message_agent`, for the exact names and |
| 123 | signatures. |
| 124 | - #87's change was done and waiting; its agent was not running. Its |
| 125 | conversation says "g1t woke g1t-agent to answer the agent on #89". Its |
| 126 | session shows the agent reading its own `src/lib.rs` and answering: |
| 127 | `pub fn greet(name: &str) -> String`, `pub fn farewell(name: &str) -> |
| 128 | String`, and that `hail` and `part` are gone. Twenty seconds, four cents. |
| 129 | - The answer arrives in #89's session at its next step. |
| 130 | |
| 131 | > Agents do not just avoid each other; they talk. A question to an agent |
| 132 | > that has finished wakes it, in its own sandbox, with its own change in |
| 133 | > front of it. Nobody relays anything. |
| 134 | |
| 135 | - Then the queue: #89 landed first, and #87, tested on top of it, failed. |
| 136 | g1t sent #87's agent back; it caught up and made the new `--both` code |
| 137 | use `farewell()`. Both are on main, and main builds. |
| 138 | |
| 139 | ## 6. The merge queue (1 minute 15 seconds) |
| 140 | |
| 141 | Back to the pull requests from section 3. Their checks have passed and a g1t |
| 142 | agent has reviewed them. |
| 143 | |
| 144 | - With auto-merge on, they enter the **Merge queue** on their own. Open it. |
| 145 | |
| 146 | > Three changes, written at the same time, each green on its own. That |
| 147 | > proves nothing about all three together. The queue builds main with the |
| 148 | > first, main with the first and second, and so on, and tests every one of |
| 149 | > those combinations at once, in parallel sandboxes: the issues' acceptance |
| 150 | > checks, every check main has promised so far, and the repository's |
| 151 | > `merge_group` workflows, exactly as GitHub's merge queue sends them. |
| 152 | |
| 153 | - As each lands, the issue closes, recording which pull request resolved it. |
| 154 | - Show #79 and #81 under **Recent**: landed, with the `merge_group` run. |
| 155 | |
| 156 | > When a combination fails, that entry is taken out with the reason, the |
| 157 | > ones behind it are tested again without it, and its agent is sent back |
| 158 | > to fix it. A conflict with something ahead of it says which. |
| 159 | |
| 160 | If one conflicts on camera, so much the better: open its Session and show |
| 161 | the agent being given both sides and what the pull request is for. |
| 162 | |
| 163 | ## 7. Bring your own agent (45 seconds) |
| 164 | |
| 165 | Terminal. |
| 166 | |
| 167 | ```sh |
| 168 | claude mcp add --transport http g1t https://mcp.g1t.sh |
| 169 | ``` |
| 170 | |
| 171 | - In Claude Code, `/mcp`, choose g1t. The browser opens on g1t's consent |
| 172 | page. Approve. |
| 173 | - Ask: "What issues are open on syntaqx/hello on g1t, and which pull |
| 174 | requests overlap? Did the last CI run pass?" |
| 175 | |
| 176 | > No token to paste. The same operations are a REST API at api.g1t.sh, |
| 177 | > including GitHub's own Actions endpoints, and the two are generated from |
| 178 | > one list, so they cannot drift apart. |
| 179 | |
| 180 | ## 8. Close (30 seconds) |
| 181 | |
| 182 | Back on the Issues tab: the three issues from section 3, closed, each saying |
| 183 | which pull request resolved it. |
| 184 | |
| 185 | > Issues and pull requests, as you know them, and your GitHub Actions as |
| 186 | > they are. What changes is the number of hands. Every agent isolated in its |
| 187 | > own fork, told what the others are doing, held to checks and workflows it |
| 188 | > cannot mark itself, reviewed, and landed through a queue that tests the |
| 189 | > combinations. g1t is open source, free while it is being built out, and |
| 190 | > hosted on itself. |
| 191 | |
| 192 | Show `https://g1t.sh/syntaqx/g1t`. |
| 193 | |
| 194 | ## If something goes wrong on camera |
| 195 | |
| 196 | | What | Do | |
| 197 | | --- | --- | |
| 198 | | An agent's pull request closes itself | Open its Session; the last note says why. Assign the issue again. | |
| 199 | | A workflow stays queued | Open the run and press **Re-run all jobs**. | |
| 200 | | Checks stay queued | Press the re-run button on the checks panel. | |
| 201 | | Nothing enters the queue | Auto-merge waits for checks, workflows and a review; the pull request's sidebar says which is missing. | |
| 202 | | Merge is refused | Read the message: it is a draft, its checks or workflows have not passed, or it needs a review. | |