g1t/docs/PLAN.md

670 lines36,798 bytesCodeBlame

Pick any line to see why it is the way it is: the commit, the pull request and issue it came from, and what the agent was thinking.

Initial g1t: services, event bus, intents and attempts1# g1t plan
2
3g1t is a git forge for agents, built on Cloudflare Workers and Artifacts for
4the "Build the Next-Gen Git Platform on Cloudflare" competition.
5
6- Submission closes **October 14, 2026, 11:59 PM PDT**: a 5–10 minute demo
7 video, this repository (MIT) and run instructions.
8- Judging: 50% originality and quality of the prototype for agent-oriented
9 collaboration; 25% multi-agent concurrency, coordination, context
10 preservation, review and conflict handling; 25% ease of use.
11
12## Product model
13
Issues and pull requests replace intents and attempts14g1t keeps the two things every engineer already knows, issues and pull
15requests, and changes the assumption underneath them. A forge built for
16people expects one pull request per issue. g1t expects many agents working
17at once, in two shapes: several agents on the same issue, and many different
18issues in flight that all have to land on `main`.
Initial g1t: services, event bus, intents and attempts19
20| Concept | What it is |
21| --- | --- |
Issues and pull requests replace intents and attempts22| **Issue** | What should change in a repo: a bug, a feature, a question. Opened by a person, an agent or an integration such as an error tracker. Carries labels, acceptance checks (commands that must pass), comments, and every pull request made for it. |
23| **Pull request** | A proposed change in its own Artifacts fork, made by an agent or a person, usually for an issue. Any number can be open for one issue. Starts as a draft; marked ready; merged or closed. |
24| **Session** | The agent's full context for a pull request: prompt, messages, tool calls, cost. Stored with the pull request and linked from every commit it produced. |
25| **Compare view** | Every pull request for an issue side by side with diff, check results, conflicts against main and against each other, and a reviewer agent's summary. |
26| **Merge** | A person or a policy picks a pull request. A per-repo merge queue lands it. The issue closes, recording which pull request resolved it; the others for that issue close as superseded, or are rebased by their agents when the issue is kept open. |
27
28Issues and pull requests share one sequence of numbers per repository, so
29`#12` names exactly one of them.
Initial g1t: services, event bus, intents and attempts30
31Features that fall out of the model:
32
33- **Why-blame.** Click a line and see the prompt and reasoning that produced
34 it, not only the commit.
Issues and pull requests replace intents and attempts35- **Overlap radar.** Pull requests that touch the same files are flagged
36 while the agents are still working, and the agents are told.
37- **Live lanes.** Watch every pull request progress in real time.
38
39## Why issues and pull requests, not something new
40
41An earlier version of this plan merged the two into one new object, an
42"issue" holding "pull requests". That was wrong, for three reasons.
Initial g1t: services, event bus, intents and attempts43
Issues and pull requests replace intents and attempts44- **Issues come from everywhere.** People file them, agents file them, and
45 Sentry files them. Most are never worked on by whoever opened them. They
46 need their own life: labels, triage, discussion, closing as not planned.
47- **"Which change did we take?" needs two objects.** When five agents each
48 propose a change, the answer has to be recorded somewhere other than the
49 five proposals. On g1t it is on the issue: `resolved by #14`.
50- **Nobody should have to learn a word to use the product.** An engineer who
51 has used any forge can use g1t on the first day, and finds the agent
52 features where they would look for them.
Rust repos service with shipping; pull requests kept in the model53
Issues and pull requests replace intents and attempts54What g1t adds to the familiar pair:
Rust repos service with shipping; pull requests kept in the model55
Issues and pull requests replace intents and attempts56- **Several pull requests per issue is the normal case**, not an accident.
57 The issue's page lists them with their state, and merging one closes the
58 issue with that pull request recorded and the others marked superseded.
59- **A pull request can be part of the work.** Merging with "keep the issue
60 open" leaves the issue and its other pull requests alone.
61- **Every pull request has a fork and a session.** See
62 [forks and branches](https://docs.g1t.sh/concepts/forks/).
63- **Labels need no setup.** A repository starts with `bug`, `feature`,
64 `docs`, `chore` and `question`; any other name becomes a label the first
65 time it is used, so an integration can tag what it files.
Pull requests from branches66- **The developer path is unchanged.** Push a branch, open a pull request
67 from it, get review, merge. Agents get a fork per pull request instead.
Rust repos service with shipping; pull requests kept in the model68- **Both paths meet at `main`.** The same landing rules apply to a person's
Issues and pull requests replace intents and attempts69 pull request and an agent's.
Rust repos service with shipping; pull requests kept in the model70
Initial g1t: services, event bus, intents and attempts71## Converging on main
72
Issues and pull requests replace intents and attempts73Twelve issues started together will finish at different times and touch
Initial g1t: services, event bus, intents and attempts74overlapping code. Getting them all into `main` without a person refereeing
75is the hard part, and it is handled in four places.
76
771. **Before work starts: plan the overlap away.** A project is a graph of
Issues and pull requests replace intents and attempts78 issues. A planner agent can split a large goal into issues, predict
Initial g1t: services, event bus, intents and attempts79 which files each will touch, and add a dependency where two would collide,
80 so one starts from the other's result instead of from `main`.
Issues and pull requests replace intents and attempts812. **While agents work: overlap radar.** Each pull request's changed files and
82 symbols are tracked as it pushes. When two pull requests from different issues
Initial g1t: services, event bus, intents and attempts83 enter the same area, both agents are told what the other is doing there.
Issues and pull requests replace intents and attempts843. **When `main` moves: the author resolves.** Every open pull request is
85 trial-merged against the new `main`. A clean merge updates the pull request
86 silently. A conflict resumes that pull request's agent with its original
Initial g1t: services, event bus, intents and attempts87 session and the incoming change, so the conflict is resolved by the agent
88 that wrote the code and still knows why.
Issues and pull requests replace intents and attempts894. **At landing: a speculative queue.** Approved pull requests enter the
90 repo's queue. g1t builds the combined states (`main`+A, `main`+A+B, …) and runs
91 their checks in parallel. Pull requests land in order as their combined state
Initial g1t: services, event bus, intents and attempts92 passes; one that fails is ejected back to its agent and the states behind
93 it are rebuilt. `main` only ever receives a state that passed.
94
95Landing can be fully automatic: a repo policy such as "checks pass and the
Issues and pull requests replace intents and attempts96reviewer agent approves" merges without a person.
Initial g1t: services, event bus, intents and attempts97
98## Agents aware of each other
99
Issues and pull requests replace intents and attempts100Each repo keeps a live **work registry**: for every running pull request, its
101issue, a running summary of what it has done, and the files and symbols it
Initial g1t: services, event bus, intents and attempts102has touched or plans to touch. Agents use it through MCP tools; g1t also
103acts on it without being asked.
104
Issues and pull requests replace intents and attempts105- **Before starting.** When an issue is opened, or an agent is about to
106 begin a task, g1t searches open issues and running pull requests for the same
Initial g1t: services, event bus, intents and attempts107 goal (by meaning, not wording) and for the same area of code. If a match
108 exists the agent is told who is on it and how far along, and chooses: join
109 as a deliberate racer, wait for the result, or drop the task. Duplicate
Issues and pull requests replace intents and attempts110 issues are offered for merging.
Initial g1t: services, event bus, intents and attempts111- **Finding out-of-scope work.** An agent that discovers something outside
Issues and pull requests replace intents and attempts112 its issue asks the registry who works there. If another pull request owns that
Initial g1t: services, event bus, intents and attempts113 area, it **hands off**: a note, the relevant excerpt of its session, and
114 optionally commits the receiver can take. If nobody does, it opens a child
Issues and pull requests replace intents and attempts115 issue instead of widening its own change.
116- **Asking.** An agent can put a question or a request to another pull request.
Initial g1t: services, event bus, intents and attempts117 The receiver gets it at its next turn.
Issues and pull requests replace intents and attempts118- **Waiting.** An agent that needs another pull request's result parks itself.
Initial g1t: services, event bus, intents and attempts119 Its sandbox sleeps, spend stops, and it resumes from the new state when
Issues and pull requests replace intents and attempts120 that pull request merges.
Initial g1t: services, event bus, intents and attempts121- **Agents that do not cooperate.** For pushes from tools that never call
Issues and pull requests replace intents and attempts122 these tools, g1t compares the pushed change against running pull requests and
Initial g1t: services, event bus, intents and attempts123 flags near-duplicates itself.
124
125Every handoff, question and wait has a state (offered, accepted, declined,
126done), appears in the timeline, and is visible to people. A handoff declined
127twice, or two agents passing work back and forth, goes to the "needs you"
128inbox.
129
130## Review at scale
131
132Cloudflare's brief asks "how do you review everything they produce?". With
133hundreds of agents, a person cannot read every diff, so review is by
134exception.
135
Issues and pull requests replace intents and attempts136- **Evidence, not diffs.** Every pull request carries a proof bundle: checks run
Initial g1t: services, event bus, intents and attempts137 and their output, a preview URL, a plain-language summary, and the
138 behaviour that changed.
Issues and pull requests replace intents and attempts139- **Two agent reviewers.** One reviews the change against the issue. A
Initial g1t: services, event bus, intents and attempts140 second is adversarial: it tries to break the change and reports what it
141 found.
142- **Risk tiers.** Each change is scored from what it touches, how large it
Issues and pull requests replace intents and attempts143 is, and how the reviewers ruled. Low risk merges on policy; high risk goes
Initial g1t: services, event bus, intents and attempts144 to a person with the evidence already assembled.
Issues and pull requests replace intents and attempts145- **Trust is earned.** An agent's record on a path (merged, reverted, caught
Initial g1t: services, event bus, intents and attempts146 by review) raises or lowers the tier its changes land in.
Issues and pull requests replace intents and attempts147- **Sampling.** A share of auto-merged changes is sent to a person anyway,
Initial g1t: services, event bus, intents and attempts148 to keep the policy honest.
149
150## Rethinking the git primitives
151
Issues and pull requests replace intents and attempts152- **No branches for agents.** A pull request is a fork; `main` is the only
Initial g1t: services, event bus, intents and attempts153 long-lived line. There is nothing to name, clean up or go stale.
Issues and pull requests replace intents and attempts154- **Projected main.** New pull requests start from `main` plus everything already
Initial g1t: services, event bus, intents and attempts155 in the landing queue, so they are built on the state they will land on.
156- **Structural merge.** The merge engine merges by syntax tree, not by line,
157 for supported languages. Two agents adding different functions to the same
158 file do not conflict.
159- **Forkable sessions.** A session can be forked at any turn: the code as it
160 was at that moment plus the conversation up to it, continued with a
161 different instruction. Branching applies to the reasoning as well as the
162 code.
Issues and pull requests replace intents and attempts163- **Provenance in history.** Every commit records its issue, session,
164 agent, model and cost, and is signed with a key issued to that pull request. The
Initial g1t: services, event bus, intents and attempts165 history can be audited by machine.
166
167## People in the loop
168
169### Code that arrives from outside
170
171People will keep pushing with plain git, their editor, or another tool. Every
172push goes through g1t's git front end, so none of it bypasses the model.
173
Issues and pull requests replace intents and attempts174- **A push to a branch becomes a pull request.** g1t adopts it with the pusher as
175 author. A reviewer agent writes the issue it appears to serve and offers
176 to attach it to an open issue it matches. From there it gets the same
177 checks, compare view and queue as agent work.
Initial g1t: services, event bus, intents and attempts178- **A push to `main` follows repo policy.** Protected: refused with a message
179 saying which ref to push to instead, so it enters the queue. Open: accepted
180 and treated as "`main` moved", which re-verifies the queue and triggers
Issues and pull requests replace intents and attempts181 resolve-on-move for every open pull request.
Initial g1t: services, event bus, intents and attempts182- **Context is an open format.** A commit trailer names the session that
183 produced it, so any tool can attach its transcript. Commits without one are
184 shown in why-blame as "pushed by a person, no session".
Issues and pull requests replace intents and attempts185- **Approval rules.** Per repo and per path: merge automatically, require a
Initial g1t: services, event bus, intents and attempts186 named person, or require a person when the change is large or the reviewer
187 agent is unsure.
188
189### Joining work that is already running
190
191- **Every session has a live page** that works on a phone: the transcript as
192 it streams, the current diff, check results.
193- **Steer.** Send a message, pause, or redirect. Hosted agents receive it
194 immediately; a person's own Claude Code receives it at its next turn
195 through the CLI hooks.
196- **Answer.** When an agent is blocked on a question, it appears in a "needs
197 you" inbox and as a notification. The answer resumes the agent.
Issues and pull requests replace intents and attempts198- **Take over and hand back.** Check out the pull request's fork, commit by hand,
Initial g1t: services, event bus, intents and attempts199 push, and let the agent continue from there.
200
201### Planning by writing
202
203- **Brief.** Write the outcome in prose on the site, or commit it as a
Issues and pull requests replace intents and attempts204 markdown file. A planner agent turns it into a project: issues, acceptance
Initial g1t: services, event bus, intents and attempts205 checks, dependencies. The person edits the graph before anything starts.
206- **Plan from their own agent.** The same operations are MCP tools, so a
207 person can plan in their own Claude Code session and create the project
208 from there.
209- **The brief stays the source of truth.** Editing it later re-plans: new
Issues and pull requests replace intents and attempts210 issues are added, obsolete ones are closed.
Initial g1t: services, event bus, intents and attempts211
212### Seeing what moved
213
Issues and pull requests replace intents and attempts214- **Project page.** The outcome, the issue graph coloured by state, and how
Initial g1t: services, event bus, intents and attempts215 many acceptance checks pass now compared with when the project started.
216- **Digest.** An agent-written summary per project and per person: what
Issues and pull requests replace intents and attempts217 merged, what is blocked on whom, which conflicts were resolved, what it
Initial g1t: services, event bus, intents and attempts218 cost.
Issues and pull requests replace intents and attempts219- **Timeline.** Every event (push, steer, check, conflict, merge) in order,
Initial g1t: services, event bus, intents and attempts220 each linked to the session and the person or agent behind it.
221
222## One session, any surface
223
224A session belongs to g1t, not to the device it started on. The browser, a
225phone and Claude Code are views of the same session.
226
227- **Browser and phone.** The site is a responsive, installable web app with
228 push notifications. Everything a person does (brief, steer, answer,
Issues and pull requests replace intents and attempts229 approve, merge) works there.
Initial g1t: services, event bus, intents and attempts230- **Claude Code.** Through `mcp.g1t.sh` and the CLI hooks, a local session is
231 a g1t session: its transcript syncs as it runs and it appears in mission
232 control like any other.
233- **Moving a session.** A local session can be sent to the cloud: a hosted
234 agent takes over the fork and the transcript and continues, so the laptop
235 can close. A hosted session can be pulled down: the CLI checks out the fork
236 and resumes it in local Claude Code with its history.
237- **Limit.** A session running only on a laptop stops when the laptop does.
238 It can be steered between turns but not continued until it is moved or the
239 laptop is back.
240
241## For people who do not write code
242
243- **Documents are first-class.** Specs, guides, policies and decisions live
244 in repos as markdown, shown in a Docs view: rendered pages, edited in the
245 browser like a document, with inline comments. "Suggest a change" is an
Issues and pull requests replace intents and attempts246 pull request and "publish" is merge, without git vocabulary.
247- **Document issues.** "Write the onboarding guide for the billing API" is
248 an issue. Its acceptance checks are a checklist judged by a reviewer agent
Initial g1t: services, event bus, intents and attempts249 instead of commands. Agents draft and revise; people comment and approve.
250- **Templates.** Product brief, RFC, decision record. A filled-in template is
251 a brief the planner can turn into a project.
252- **Explain.** Ask about any repo, project or change in plain language and
253 get an answer with links to the code and sessions behind it.
254- **Living documentation.** g1t generates "how this works" pages from the
Issues and pull requests replace intents and attempts255 code and keeps them current. When a merged change contradicts a document,
256 an issue opens to update it.
257- **See it, don't read it.** Every pull request on a deployable repo gets a
258 preview URL (Workers Builds from the pull request's fork), so an approver clicks
Initial g1t: services, event bus, intents and attempts259 through the result instead of reading a diff. Changes are also summarised
260 in plain language.
261- **Roles.** Viewer, commenter, planner, approver: a person can plan and
262 approve work without ever cloning a repo.
263
264## The macro view
265
266The hierarchy above a single repo:
267
268| Level | What it is |
269| --- | --- |
270| **Workspace** | A company or team: its people, repos, agents, budget and policies. |
271| **Initiative** | A business outcome with an owner and measurable results, e.g. "move billing to usage-based pricing". Spans any number of repos. |
Issues and pull requests replace intents and attempts272| **Project** | One deliverable inside an initiative: a brief and its graph of issues. |
273| **Issue / Pull request** | As above. An issue may touch several repos; a pull request for it then holds one fork per repo and they land together. |
Initial g1t: services, event bus, intents and attempts274
275### Portfolio
276
277One page answers "where is the business" across every initiative:
278
279- **Health** per initiative: on track, at risk, or blocked, derived from
Issues and pull requests replace intents and attempts280 facts (checks passing, issues stalled, questions waiting on a person),
Initial g1t: services, event bus, intents and attempts281 not self-reported.
Issues and pull requests replace intents and attempts282- **Progress** as measurable results: acceptance checks passing, issues
283 merged out of planned, and the trend since the start.
Initial g1t: services, event bus, intents and attempts284- **Forecast** from actual throughput: at the current rate, when the
Issues and pull requests replace intents and attempts285 remaining issues land.
Initial g1t: services, event bus, intents and attempts286- **Spend** in tokens and dollars against a budget, per initiative.
287- **Waiting on people**: every decision or approval a person owes, by name.
288- **Roadmap**: initiatives laid out as now, next, later, with optional
289 time-boxed cycles for teams that work in sprints.
290
291### Status without asking
292
293- **Standup.** An agent writes a daily report per initiative and one for the
Issues and pull requests replace intents and attempts294 whole workspace: what merged, what changed direction, what is at risk and
Initial g1t: services, event bus, intents and attempts295 why, what needs a person. Delivered by email or webhook.
296- **Ask.** A question box over the full event log and all sessions: "what
297 happened on the billing migration since Monday?" answers with links to the
298 sessions and commits behind each claim.
299
300### Long-running agents
301
302Work that runs for days needs supervision that does not depend on someone
303watching.
304
Issues and pull requests replace intents and attempts305- **Checkpoints.** A long pull request reports milestones against its issue, so
306 progress is visible before anything merges.
307- **Stall and drift detection.** A pull request with no meaningful progress, or
308 whose changes have wandered away from its issue, is flagged and can be
Initial g1t: services, event bus, intents and attempts309 stopped or re-briefed automatically.
Issues and pull requests replace intents and attempts310- **Budgets.** Hard limits on spend and time per pull request, project and
Initial g1t: services, event bus, intents and attempts311 initiative.
312
313### Context hub
314
315Agents working across repos and days need context that outlives any one
316session and reaches beyond the code. The context hub is one place an agent
317asks, whatever the source.
318
319| Source | What it holds | How it gets there |
320| --- | --- | --- |
321| **Memory** | Decisions, conventions, gotchas, facts about systems | Written by agents and people in g1t |
322| **Code and sessions** | The repos, and the reasoning behind every change | Already in g1t |
323| **Connected sources** | Jira and Linear tickets, Notion and Confluence pages, Google Drive documents, Slack threads, Sentry issues | Connectors, authorised per workspace |
324
325How it behaves:
326
327- **One search.** An agent asks a question and gets ranked results across
328 all sources, each labelled with where it came from, who wrote it, and how
329 fresh it is.
330- **Connected sources stay where they are.** g1t indexes them for search and
331 fetches the current version when an agent opens one. The external system
Issues and pull requests replace intents and attempts332 remains the source of truth, and a link placed on an issue ("see
Initial g1t: services, event bus, intents and attempts333 JIRA-482", a Notion URL) is pulled into the agent's starting context.
334- **Permissions carry over.** A connector only exposes what the connecting
335 account can see, and a workspace admin chooses which spaces, projects or
336 channels are included.
337- **External content is untrusted.** A ticket or page can contain text meant
338 to manipulate an agent. It is marked as reference material, never treated
339 as instructions.
340- **Documentation is separate.** Context is what agents know; documentation
341 is what people read, and it is generated from context and code.
342
343Memory is the part of the hub that g1t owns and agents write to:
344
345- **Memory is written freely.** Any agent or person adds an entry with one
346 call: a decision, a convention, a gotcha, a fact about a system. No review
347 gate. Each entry records who wrote it, from which session, and when.
348- **It is still a repository.** Each workspace has a memory repo in
349 Artifacts, so every write is a commit: versioned, attributable, and
350 revertible.
351- **It is kept healthy by an agent.** A consolidation agent merges
352 duplicates, retires entries that newer ones contradict, and flags
353 conflicts it cannot settle. People can pin an entry (agents may not change
354 it), correct it, or retract it.
355- **Agents read it.** Every session starts with the context relevant to its
Issues and pull requests replace intents and attempts356 issue, found by search, and can query more through MCP.
Initial g1t: services, event bus, intents and attempts357- **Updates are events.** A memory write or a change in a connected source
358 is an event, so "when context changes, update the affected docs" is an
359 automation, on by default.
360- **It is scoped inside the workspace.** Some context applies to the whole
361 workspace, some to one initiative, project or repo, so an agent gets what
362 applies to its work.
363- **It never crosses workspaces.** A workspace is the isolation boundary: its
364 context, sessions and private repos are invisible to every other
365 workspace, and an agent's token is bound to one workspace.
366
367## Working in g1t
368
369- **Mission control.** The signed-in home page: every running session, every
Issues and pull requests replace intents and attempts370 issue waiting on a decision, and what merged, across all repos.
371- **Projects.** Group issues across repos toward one outcome and track how
372 many are open, racing, or merged.
373- **Steering.** Send a message to a running pull request, or to all pull requests on an
374 issue at once, without stopping them.
Initial g1t: services, event bus, intents and attempts375- **Automations.** Rules that start work without a person (next section).
376
377## Automations and integrations
378
379An automation is **when** an event happens, **if** conditions hold, **do**
380something. They are defined as files in the repo (`.g1t/automations/`), the
381way GitHub Actions workflows are, and can also be built in the UI.
382
383### Events that can trigger one
384
385| Source | Examples |
386| --- | --- |
Issues and pull requests replace intents and attempts387| Git | push, merge, check failed, `main` moved |
388| g1t | issue opened, pull request stalled, context updated, handoff declined, budget reached |
Initial g1t: services, event bus, intents and attempts389| Time | cron schedule |
390| Integrations | Sentry issue, PagerDuty incident, Linear or Jira ticket, Slack message or mention, GitHub issue, Stripe event |
391| Anything else | a signed generic webhook, or an email to a per-repo address |
392
Issues and pull requests replace intents and attempts393**Actions**: open an issue (optionally assigning N agents to it), message
394a running pull request, update documentation, notify, call a
Initial g1t: services, event bus, intents and attempts395webhook, write back to the source system.
396
397**Example: Sentry.** A new production error arrives. The automation opens an
Issues and pull requests replace intents and attempts398issue labelled `bug`, with the stack trace, release and frequency in its
399description. Why-blame
Initial g1t: services, event bus, intents and attempts400finds the session that wrote the failing line, so the fixing agent starts
Issues and pull requests replace intents and attempts401with the original reasoning. When the fix merges, g1t comments on the Sentry
Initial g1t: services, event bus, intents and attempts402issue and resolves it.
403
404### Rules every automation obeys
405
406- **Deduplication.** The same Sentry issue firing 500 times maps to one
Issues and pull requests replace intents and attempts407 issue.
Initial g1t: services, event bus, intents and attempts408- **Limits.** Concurrency and budget caps per automation.
409- **Loop protection.** Work started by an automation cannot retrigger the
410 same automation without a person in between.
411- **External input is untrusted.** A webhook payload can contain text written
412 by an attacker. Agents started by external events run with reduced
Issues and pull requests replace intents and attempts413 permissions and cannot merge without the repo's approval rule passing.
Initial g1t: services, event bus, intents and attempts414
415**Checks** are the other half of what GitHub Actions does: build and test
Issues and pull requests replace intents and attempts416commands declared in `.g1t/checks.yaml`, run in sandboxes on every pull request
Initial g1t: services, event bus, intents and attempts417and on every combined state in the landing queue.
418
419Agents can also reach integrations directly: an agent definition lists MCP
420servers (Sentry, Linear and so on) it may use while working.
421
422## Agents and models
423
424### Defining an agent
425
426An agent is a file (`.g1t/agents/<name>.md`, or in the workspace library):
427instructions, the harness and model to run, the tools and MCP servers it may
428use, its sandbox image, permissions and budget. Agents take roles: planner,
429implementer, reviewer, conflict resolver, documenter, memory consolidator.
430Each role has a default that a repo can replace.
431
432### Where it runs, and on whose model
433
434| Option | How it works | Fits |
435| --- | --- | --- |
436| Hosted, g1t's model | g1t runs the sandbox and bills usage | Getting started; no keys to manage |
437| Hosted, your API key | Same sandbox, your Anthropic, OpenAI or Google key | Teams with existing contracts |
438| Hosted, your endpoint | Any OpenAI-compatible URL: Bedrock, Vertex, Azure, a self-hosted model | Private or fine-tuned models |
Issues and pull requests replace intents and attempts439| Your runner | A g1t runner daemon on your own machines picks up pull requests | Code or models that may not leave your network |
Initial g1t: services, event bus, intents and attempts440| Your own session | Local Claude Code, Cursor or any MCP client joins through `mcp.g1t.sh` | Individuals; subscription plans |
441
442Decisions behind this:
443
444- **g1t does not build its own agent loop.** It runs existing harnesses
445 (Claude Code first, through its headless mode) behind a small runner
446 contract: a container image, an entry command, and session events reported
447 through the CLI. Other harnesses plug in by meeting the contract.
448- **All hosted model traffic goes through Cloudflare AI Gateway.** That gives
449 one place for spend tracking, budgets, rate limits, fallback and logs,
450 whichever provider or endpoint is behind it.
451- **Subscriptions stay local.** A Claude subscription cannot be used by a
452 hosted sandbox; it needs an API key. People on subscriptions use their own
453 Claude Code session, which is a full participant.
454- **Keys are secrets.** Stored in Cloudflare Secrets Store, injected into the
Issues and pull requests replace intents and attempts455 sandbox for one pull request, never shown again.
Initial g1t: services, event bus, intents and attempts456
457### Choosing the right agent automatically
458
Issues and pull requests replace intents and attempts459Because several agents can work on the same issue, every issue with more
460than one pull request is an evaluation on real work. g1t records, per repo and per kind of issue, each
Initial g1t: services, event bus, intents and attempts461agent's win rate, cost and time. That produces a leaderboard, and a routing
Issues and pull requests replace intents and attempts462policy: send each new issue to the agent that wins that kind most often,
Initial g1t: services, event bus, intents and attempts463start with the cheapest that is good enough, and escalate to a stronger one
464when checks fail.
465
466## What GitHub ships today, and where g1t differs
467
468GitHub's Agent HQ and Copilot app give each agent session its own git
469worktree and branch, list sessions in a mission-control view grouped by
470project, and let a task be assigned to several agents so their output can be
471compared. Underneath, the unit of work is still a branch and a pull request.
472
473| | GitHub | g1t |
474| --- | --- | --- |
475| Where a session works | A worktree on one developer's machine, or a cloud sandbox | A server-side fork that any agent on any machine can join and anyone can open |
476| Agent context | Lives in the app's session view | Stored with the repository and linked from each commit (why-blame) |
Issues and pull requests replace intents and attempts477| Several agents on one task | Separate pull requests to compare by hand | One issue holding every pull request made for it, compared side by side, with the merged one recorded on the issue |
Initial g1t: services, event bus, intents and attempts478| Collisions between agents | Found as merge conflicts at the end | Flagged during the work (overlap radar) |
Issues and pull requests replace intents and attempts479| Landing changes | One pull request at a time | A merge queue that lands the chosen one and closes the rest as superseded |
Initial g1t: services, event bus, intents and attempts480| Which agents | Those offered through a Copilot subscription | Any MCP client, plus hosted agents |
481
482## How agents connect
483
4841. **Bring your own agent.** A remote MCP server at `mcp.g1t.sh` lets Claude
Issues and pull requests replace intents and attempts485 Code (or any MCP client) list issues, claim one, get a clone URL and
Initial g1t: services, event bus, intents and attempts486 token, report progress and submit. Adding it is one command; sign-in is a
487 browser OAuth flow with no token to paste. The `g1t` CLI installs Claude
488 Code hooks that upload the session transcript as the agent works.
Issues and pull requests replace intents and attempts4892. **g1t agents.** Assign up to five of g1t's own agents to an issue. g1t
490 starts a sandbox for each (Cloudflare Containers), running a coding agent
491 headless against its own pull request and fork.
Initial g1t: services, event bus, intents and attempts4923. **API and CLI.** Everything above is available at `api.g1t.sh` and
493 through `g1t`.
494
495## Public surfaces
496
497| Host | What it serves |
498| --- | --- |
499| `g1t.sh` | The site, git over HTTPS, git over SSH |
Issues and pull requests replace intents and attempts500| `api.g1t.sh` | Versioned REST API with a published OpenAPI document, cursor pagination, rate-limit headers, idempotency keys on writes, server-sent events for live pull request state, and signed webhooks |
Initial g1t: services, event bus, intents and attempts501| `mcp.g1t.sh` | Remote MCP server over streamable HTTP |
502
503g1t is its own OAuth 2.1 authorization server: authorization code with PKCE,
OAuth 2.1 sign-in for MCP clients and other applications504dynamic client registration that stores nothing (a client id encodes its
505own registration, so the open endpoint cannot be used to fill a database),
506discovery metadata and rotating refresh tokens. Still to come: scopes
Issues and pull requests replace intents and attempts507per resource (`repo:read`, `repo:write`, `issue:write`, `pull:write`).
Initial g1t: services, event bus, intents and attempts508MCP clients, the CLI (device flow) and third-party apps all use it. Access
509tokens and SSH keys remain for git itself.
510
511## Architecture
512
513| Component | Language | Runs on | Responsibility |
514| --- | --- | --- | --- |
Issues and pull requests replace intents and attempts515| `crates/contracts`, `packages/contracts` | Rust, TypeScript | — | The interface of every service, the event catalogue, shared types. Services and clients depend on this, never on each other's code. |
OAuth 2.1 sign-in for MCP clients and other applications516| `services/identity` | Rust | Worker + D1 | Accounts, workspaces and memberships, sessions, SSH keys, access tokens, device sign-in, OAuth codes and grants |
Issues and pull requests replace intents and attempts517| `services/repos` | Rust | Worker + D1 + Artifacts | Repository registry, contents, forks, diffs, landing, git over HTTPS. Storage sits behind a `GitStore` port with an Artifacts adapter. |
518| `services/work` | Rust | Worker + D1 | Issues, pull requests, comments, sessions; later a Durable Object per repo for the landing queue and live state |
Events service in Rust, with RFC 3339 times and accurate push events519| `services/events` | Rust | Worker + Queues + D1 | The event bus: durable log, and one queue per subscribing service |
Issues and pull requests replace intents and attempts520| `services/runner`, `crates/runner` | TypeScript, Rust | Worker + Containers | Starts a sandbox per g1t agent; the program inside runs the agent harness and reports through the public API |
Initial g1t: services, event bus, intents and attempts521| `apps/web` | TypeScript | Worker | Server-rendered site. Holds no data; calls services over RPC. |
Issues and pull requests replace intents and attempts522| `apps/docs` | TypeScript | Worker (static) | Documentation and the API explorer |
API and MCP server in Rust; a public index at the API root523| `apps/api` | Rust | Worker | REST API (`api.g1t.sh`), MCP server (`mcp.g1t.sh`) and OpenAPI document, all generated from one list of operations; the OAuth endpoints |
Initial g1t: services, event bus, intents and attempts524| `crates/sshd` | Rust | Container | Git over SSH, bridged to Artifacts |
525| `crates/merged` | Rust | Container | Trial merges, conflict matrix, landing merges (needs real git; the Artifacts binding is read-only) |
526| `crates/core` | Rust | native and WASM | pkt-line, packfile and diff code shared by the above and by the Worker |
Issues and pull requests replace intents and attempts527| `crates/g1t` | Rust | user's machine | CLI: auth, SSH proxy, Claude Code hooks, issues and pull requests |
Initial g1t: services, event bus, intents and attempts528
Issues and pull requests replace intents and attempts529Storage: Artifacts for repositories (one fork per pull request), D1 for accounts
Initial g1t: services, event bus, intents and attempts530and metadata, R2 for session transcripts and logs, Durable Object SQLite for
531per-repo coordination state.
532
533How the services fit together:
534
535- **Each service is its own Worker with its own database.** It deploys,
536 scales and fails on its own. Callers reach it through a typed RPC binding
537 to the interface in `packages/contracts`.
538- **Expected failures are values.** Every call returns a `Result`, so "not
539 found" or "forbidden" crosses a service boundary as data.
540- **Side effects travel as events.** A service publishes what happened
Issues and pull requests replace intents and attempts541 (`git.push`, `issue.opened`, `pull.merged`, …) to the bus and does not
Initial g1t: services, event bus, intents and attempts542 call other services to react. Each subscriber consumes from its own queue.
543 Timelines, webhooks and automations read the same stream, which is what
544 lets something like GitHub Actions be built on top.
545- **Every read takes the viewer.** Authorization is decided inside the
546 service that owns the data, not by its callers.
547
548The Workers runtime scales request handling on its own, so the edge layer
549stays in TypeScript. Rust is used where there is real computation or a real
550protocol to implement.
551
API and MCP server, Rust identity service, registration, site redesign552## Languages
553
554The site is TypeScript. Everything behind it is Rust, compiled to
API and MCP server in Rust; a public index at the API root555WebAssembly for Workers and natively for containers and the CLI. Identity, repos, work, events and the API are all Rust. The one exception
556is the Worker that starts sandboxes, because Cloudflare's Containers
557library is TypeScript. Rust services speak a
API and MCP server, Rust identity service, registration, site redesign558small JSON protocol over service bindings (`POST /rpc/<method>`), with the
559types in `crates/contracts`.
560
561## Identifiers
562
563Every id is a [TypeID](https://github.com/jetify-com/typeid): a prefix naming
564the kind of thing, then a UUIDv7 in lowercase base32, such as
Issues and pull requests replace intents and attempts565`pr_01jb2k7x9hfq0b3zj0f5s2m8ra`.
API and MCP server, Rust identity service, registration, site redesign566
567- The prefix makes an id self-describing and stops ids of different kinds
568 being mixed up.
569- Ids sort by creation time as plain strings. In SQLite (D1 and Durable
570 Objects) that keeps inserts at the end of the primary-key index instead of
571 scattering them, and gives time-ordered paging for free.
572- The suffix decodes to a standard UUIDv7 for any system that wants one.
573- Ids are made by the service that creates the record, not by the database,
574 so they work across services and can be assigned before a write.
575
576## Events at scale, and audit
577
578The current event log is a single D1 database. That is fine for a
579prototype and wrong for the target: D1 is one writer and 10 GB. The design
580for volume splits storage by how the data is read.
581
582| Tier | Store | Holds | Read by |
583| --- | --- | --- | --- |
584| Hot | A Durable Object per repository, with SQLite | Recent events for that repo | Timelines, live pages over WebSocket |
585| Complete | Cloudflare Pipelines into R2 as Apache Iceberg | Every event, forever, partitioned by day and workspace | Analytics, standups, "ask", export |
586| Audit | The same R2 store, under object lock | Who did what, from where, with which credential | Compliance, investigation |
587
588- **No single hot database.** Each repository's recent events live with that
589 repository, so load spreads across as many objects as there are repos.
590- **The complete record is files, not rows.** Iceberg on R2 has no practical
591 size limit and is queried with SQL.
592- **Audit is a property of every event.** The envelope carries the actor
593 (person, agent, token or system), the credential used, the request id and
594 the source address. Audit entries for a workspace are hash-chained, so a
595 removed or altered entry is detectable, and are written under a retention
596 lock.
597- **Delivery is at least once.** Consumers are idempotent on the event id.
598
Initial g1t: services, event bus, intents and attempts599## Accounts and forge basics
600
601- Registration with email verification, sign-in, forgot password (Cloudflare
602 Email Sending), Turnstile on public forms.
603- GitHub sign-in, SSH keys, access tokens, active sessions.
604- Profiles, public and private repositories, repository search (D1 full-text).
605- Rendered README, syntax highlighting, commit history, diffs.
606
607## Built on Cloudflare
608
609| Need | Product |
610| --- | --- |
Issues and pull requests replace intents and attempts611| Repositories; a fork per pull request; data residency per workspace | Artifacts (forks, jurisdictions) |
Initial g1t: services, event bus, intents and attempts612| Reacting to pushes | Artifacts event subscriptions on Queues |
Issues and pull requests replace intents and attempts613| Preview URL per pull request; deploy on merge | Workers Builds and previews |
Initial g1t: services, event bus, intents and attempts614| Site, API, MCP, git front end | Workers |
615| Per-repo coordination, live updates | Durable Objects |
Issues and pull requests replace intents and attempts616| Pull request lifecycles, automations | Workflows, Cron Triggers |
Initial g1t: services, event bus, intents and attempts617| Agent sandboxes, SSH server, merge engine | Sandbox SDK and Containers |
618| Fast starts on large repos | ArtifactFS |
619| Model traffic, spend, budgets | AI Gateway |
620| Summaries, embeddings | Workers AI |
621| Context hub search | Vectorize |
622| Accounts and metadata | D1 |
623| Transcripts and logs | R2 |
624| Email, bot protection, keys | Email Sending, Turnstile, Secrets Store |
625
626## The submission
627
628- **g1t is built on g1t.** This repository is hosted on g1t.sh, its features
Issues and pull requests replace intents and attempts629 are opened as issues and built by racing agents, and it deploys from
Initial g1t: services, event bus, intents and attempts630 Artifacts through Workers Builds. The history is the proof.
Issues and pull requests replace intents and attempts631- **The demo follows one story.** A brief becomes a project; twelve issues
Initial g1t: services, event bus, intents and attempts632 fan out to dozens of agents; agents notice each other, hand off, and
633 resolve a conflict; reviewers triage; the queue lands everything on
634 `main`; why-blame explains a line; the portfolio shows where it all
635 stands. Then the same thing at a thousand agents.
636- **Judges can try it in a minute.** Open registration on g1t.sh, one-click
637 import of a GitHub repo, one command to connect Claude Code, a seeded demo
638 workspace, and a single deploy command for running their own copy.
639- **The formats are open.** The commit trailers, session format and runner
640 contract are published so other tools can interoperate.
641
642## Build order
643
Issues and pull requests replace intents and attempts644Done: site with marketing page; separate docs site with API explorer; git
645over HTTPS; accounts with registration, email verification, password reset
OAuth 2.1 sign-in for MCP clients and other applications646and device sign-in; an OAuth 2.1 server, so MCP clients sign in through the
647browser with no token to paste; workspaces with members; issues with labels, checks and
Pull requests from branches648comments; pull requests in forks or from branches, with diffs and sessions,
649several per issue; merging with a behind check, which resolves the issue and supersedes
Issues and pull requests replace intents and attempts650the rest; g1t agents in sandboxes with a choice of model; REST API, OpenAPI
API and MCP server in Rust; a public index at the API root651and MCP server; event bus. Every service and the API are in Rust.
Initial g1t: services, event bus, intents and attempts652
Pull requests from branches6531. Branch protection, and deleting a branch once its pull request merges.
OAuth 2.1 sign-in for MCP clients and other applications6542. Scopes on OAuth grants and access tokens.
API and MCP server in Rust; a public index at the API root6553. Event storage per the design above: per-repo hot log, Iceberg on R2,
656 hash-chained audit.
Rust repos service with shipping; pull requests kept in the model6574. CLI with Claude Code hooks to record sessions automatically.
Issues and pull requests replace intents and attempts6585. Acceptance checks run in sandboxes; review comments on lines.
Rust repos service with shipping; pull requests kept in the model6596. Server-side merge and rebase; landing queue with speculative checks;
660 resolve-on-move.
Issues and pull requests replace intents and attempts6617. Compare view, proof bundles, reviewers, risk tiers; work registry,
662 handoff.
Rust repos service with shipping; pull requests kept in the model6638. Projects, mission control, steering; why-blame, digest, timeline.
Issues and pull requests replace intents and attempts6649. Context hub, portfolio; automations and integrations (Sentry first).
Rust repos service with shipping; pull requests kept in the model66510. SSH; bot protection; own keys, endpoints and runners.
Issues and pull requests replace intents and attempts66611. Large run (100+ agents across many issues), hardening, demo.
Initial g1t: services, event bus, intents and attempts667
668Later: code search, mirroring to GitHub, passkeys, SSH
669on port 22 without the CLI proxy (needs the Workers inbound TCP private
670beta).