pr_01m47d15m3e54sn21z27rpy5n9/docs/PLAN.md

670 lines36,735 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.
66- **The developer path is unchanged.** Push, open a pull request, get review,
67 merge. Pull requests from a branch pushed to the repo itself are next in
68 the build order; today each one has a fork.
Rust repos service with shipping; pull requests kept in the model69- **Both paths meet at `main`.** The same landing rules apply to a person's
Issues and pull requests replace intents and attempts70 pull request and an agent's.
Rust repos service with shipping; pull requests kept in the model71
Initial g1t: services, event bus, intents and attempts72## Converging on main
73
Issues and pull requests replace intents and attempts74Twelve issues started together will finish at different times and touch
Initial g1t: services, event bus, intents and attempts75overlapping code. Getting them all into `main` without a person refereeing
76is the hard part, and it is handled in four places.
77
781. **Before work starts: plan the overlap away.** A project is a graph of
Issues and pull requests replace intents and attempts79 issues. A planner agent can split a large goal into issues, predict
Initial g1t: services, event bus, intents and attempts80 which files each will touch, and add a dependency where two would collide,
81 so one starts from the other's result instead of from `main`.
Issues and pull requests replace intents and attempts822. **While agents work: overlap radar.** Each pull request's changed files and
83 symbols are tracked as it pushes. When two pull requests from different issues
Initial g1t: services, event bus, intents and attempts84 enter the same area, both agents are told what the other is doing there.
Issues and pull requests replace intents and attempts853. **When `main` moves: the author resolves.** Every open pull request is
86 trial-merged against the new `main`. A clean merge updates the pull request
87 silently. A conflict resumes that pull request's agent with its original
Initial g1t: services, event bus, intents and attempts88 session and the incoming change, so the conflict is resolved by the agent
89 that wrote the code and still knows why.
Issues and pull requests replace intents and attempts904. **At landing: a speculative queue.** Approved pull requests enter the
91 repo's queue. g1t builds the combined states (`main`+A, `main`+A+B, …) and runs
92 their checks in parallel. Pull requests land in order as their combined state
Initial g1t: services, event bus, intents and attempts93 passes; one that fails is ejected back to its agent and the states behind
94 it are rebuilt. `main` only ever receives a state that passed.
95
96Landing can be fully automatic: a repo policy such as "checks pass and the
Issues and pull requests replace intents and attempts97reviewer agent approves" merges without a person.
Initial g1t: services, event bus, intents and attempts98
99## Agents aware of each other
100
Issues and pull requests replace intents and attempts101Each repo keeps a live **work registry**: for every running pull request, its
102issue, a running summary of what it has done, and the files and symbols it
Initial g1t: services, event bus, intents and attempts103has touched or plans to touch. Agents use it through MCP tools; g1t also
104acts on it without being asked.
105
Issues and pull requests replace intents and attempts106- **Before starting.** When an issue is opened, or an agent is about to
107 begin a task, g1t searches open issues and running pull requests for the same
Initial g1t: services, event bus, intents and attempts108 goal (by meaning, not wording) and for the same area of code. If a match
109 exists the agent is told who is on it and how far along, and chooses: join
110 as a deliberate racer, wait for the result, or drop the task. Duplicate
Issues and pull requests replace intents and attempts111 issues are offered for merging.
Initial g1t: services, event bus, intents and attempts112- **Finding out-of-scope work.** An agent that discovers something outside
Issues and pull requests replace intents and attempts113 its issue asks the registry who works there. If another pull request owns that
Initial g1t: services, event bus, intents and attempts114 area, it **hands off**: a note, the relevant excerpt of its session, and
115 optionally commits the receiver can take. If nobody does, it opens a child
Issues and pull requests replace intents and attempts116 issue instead of widening its own change.
117- **Asking.** An agent can put a question or a request to another pull request.
Initial g1t: services, event bus, intents and attempts118 The receiver gets it at its next turn.
Issues and pull requests replace intents and attempts119- **Waiting.** An agent that needs another pull request's result parks itself.
Initial g1t: services, event bus, intents and attempts120 Its sandbox sleeps, spend stops, and it resumes from the new state when
Issues and pull requests replace intents and attempts121 that pull request merges.
Initial g1t: services, event bus, intents and attempts122- **Agents that do not cooperate.** For pushes from tools that never call
Issues and pull requests replace intents and attempts123 these tools, g1t compares the pushed change against running pull requests and
Initial g1t: services, event bus, intents and attempts124 flags near-duplicates itself.
125
126Every handoff, question and wait has a state (offered, accepted, declined,
127done), appears in the timeline, and is visible to people. A handoff declined
128twice, or two agents passing work back and forth, goes to the "needs you"
129inbox.
130
131## Review at scale
132
133Cloudflare's brief asks "how do you review everything they produce?". With
134hundreds of agents, a person cannot read every diff, so review is by
135exception.
136
Issues and pull requests replace intents and attempts137- **Evidence, not diffs.** Every pull request carries a proof bundle: checks run
Initial g1t: services, event bus, intents and attempts138 and their output, a preview URL, a plain-language summary, and the
139 behaviour that changed.
Issues and pull requests replace intents and attempts140- **Two agent reviewers.** One reviews the change against the issue. A
Initial g1t: services, event bus, intents and attempts141 second is adversarial: it tries to break the change and reports what it
142 found.
143- **Risk tiers.** Each change is scored from what it touches, how large it
Issues and pull requests replace intents and attempts144 is, and how the reviewers ruled. Low risk merges on policy; high risk goes
Initial g1t: services, event bus, intents and attempts145 to a person with the evidence already assembled.
Issues and pull requests replace intents and attempts146- **Trust is earned.** An agent's record on a path (merged, reverted, caught
Initial g1t: services, event bus, intents and attempts147 by review) raises or lowers the tier its changes land in.
Issues and pull requests replace intents and attempts148- **Sampling.** A share of auto-merged changes is sent to a person anyway,
Initial g1t: services, event bus, intents and attempts149 to keep the policy honest.
150
151## Rethinking the git primitives
152
Issues and pull requests replace intents and attempts153- **No branches for agents.** A pull request is a fork; `main` is the only
Initial g1t: services, event bus, intents and attempts154 long-lived line. There is nothing to name, clean up or go stale.
Issues and pull requests replace intents and attempts155- **Projected main.** New pull requests start from `main` plus everything already
Initial g1t: services, event bus, intents and attempts156 in the landing queue, so they are built on the state they will land on.
157- **Structural merge.** The merge engine merges by syntax tree, not by line,
158 for supported languages. Two agents adding different functions to the same
159 file do not conflict.
160- **Forkable sessions.** A session can be forked at any turn: the code as it
161 was at that moment plus the conversation up to it, continued with a
162 different instruction. Branching applies to the reasoning as well as the
163 code.
Issues and pull requests replace intents and attempts164- **Provenance in history.** Every commit records its issue, session,
165 agent, model and cost, and is signed with a key issued to that pull request. The
Initial g1t: services, event bus, intents and attempts166 history can be audited by machine.
167
168## People in the loop
169
170### Code that arrives from outside
171
172People will keep pushing with plain git, their editor, or another tool. Every
173push goes through g1t's git front end, so none of it bypasses the model.
174
Issues and pull requests replace intents and attempts175- **A push to a branch becomes a pull request.** g1t adopts it with the pusher as
176 author. A reviewer agent writes the issue it appears to serve and offers
177 to attach it to an open issue it matches. From there it gets the same
178 checks, compare view and queue as agent work.
Initial g1t: services, event bus, intents and attempts179- **A push to `main` follows repo policy.** Protected: refused with a message
180 saying which ref to push to instead, so it enters the queue. Open: accepted
181 and treated as "`main` moved", which re-verifies the queue and triggers
Issues and pull requests replace intents and attempts182 resolve-on-move for every open pull request.
Initial g1t: services, event bus, intents and attempts183- **Context is an open format.** A commit trailer names the session that
184 produced it, so any tool can attach its transcript. Commits without one are
185 shown in why-blame as "pushed by a person, no session".
Issues and pull requests replace intents and attempts186- **Approval rules.** Per repo and per path: merge automatically, require a
Initial g1t: services, event bus, intents and attempts187 named person, or require a person when the change is large or the reviewer
188 agent is unsure.
189
190### Joining work that is already running
191
192- **Every session has a live page** that works on a phone: the transcript as
193 it streams, the current diff, check results.
194- **Steer.** Send a message, pause, or redirect. Hosted agents receive it
195 immediately; a person's own Claude Code receives it at its next turn
196 through the CLI hooks.
197- **Answer.** When an agent is blocked on a question, it appears in a "needs
198 you" inbox and as a notification. The answer resumes the agent.
Issues and pull requests replace intents and attempts199- **Take over and hand back.** Check out the pull request's fork, commit by hand,
Initial g1t: services, event bus, intents and attempts200 push, and let the agent continue from there.
201
202### Planning by writing
203
204- **Brief.** Write the outcome in prose on the site, or commit it as a
Issues and pull requests replace intents and attempts205 markdown file. A planner agent turns it into a project: issues, acceptance
Initial g1t: services, event bus, intents and attempts206 checks, dependencies. The person edits the graph before anything starts.
207- **Plan from their own agent.** The same operations are MCP tools, so a
208 person can plan in their own Claude Code session and create the project
209 from there.
210- **The brief stays the source of truth.** Editing it later re-plans: new
Issues and pull requests replace intents and attempts211 issues are added, obsolete ones are closed.
Initial g1t: services, event bus, intents and attempts212
213### Seeing what moved
214
Issues and pull requests replace intents and attempts215- **Project page.** The outcome, the issue graph coloured by state, and how
Initial g1t: services, event bus, intents and attempts216 many acceptance checks pass now compared with when the project started.
217- **Digest.** An agent-written summary per project and per person: what
Issues and pull requests replace intents and attempts218 merged, what is blocked on whom, which conflicts were resolved, what it
Initial g1t: services, event bus, intents and attempts219 cost.
Issues and pull requests replace intents and attempts220- **Timeline.** Every event (push, steer, check, conflict, merge) in order,
Initial g1t: services, event bus, intents and attempts221 each linked to the session and the person or agent behind it.
222
223## One session, any surface
224
225A session belongs to g1t, not to the device it started on. The browser, a
226phone and Claude Code are views of the same session.
227
228- **Browser and phone.** The site is a responsive, installable web app with
229 push notifications. Everything a person does (brief, steer, answer,
Issues and pull requests replace intents and attempts230 approve, merge) works there.
Initial g1t: services, event bus, intents and attempts231- **Claude Code.** Through `mcp.g1t.sh` and the CLI hooks, a local session is
232 a g1t session: its transcript syncs as it runs and it appears in mission
233 control like any other.
234- **Moving a session.** A local session can be sent to the cloud: a hosted
235 agent takes over the fork and the transcript and continues, so the laptop
236 can close. A hosted session can be pulled down: the CLI checks out the fork
237 and resumes it in local Claude Code with its history.
238- **Limit.** A session running only on a laptop stops when the laptop does.
239 It can be steered between turns but not continued until it is moved or the
240 laptop is back.
241
242## For people who do not write code
243
244- **Documents are first-class.** Specs, guides, policies and decisions live
245 in repos as markdown, shown in a Docs view: rendered pages, edited in the
246 browser like a document, with inline comments. "Suggest a change" is an
Issues and pull requests replace intents and attempts247 pull request and "publish" is merge, without git vocabulary.
248- **Document issues.** "Write the onboarding guide for the billing API" is
249 an issue. Its acceptance checks are a checklist judged by a reviewer agent
Initial g1t: services, event bus, intents and attempts250 instead of commands. Agents draft and revise; people comment and approve.
251- **Templates.** Product brief, RFC, decision record. A filled-in template is
252 a brief the planner can turn into a project.
253- **Explain.** Ask about any repo, project or change in plain language and
254 get an answer with links to the code and sessions behind it.
255- **Living documentation.** g1t generates "how this works" pages from the
Issues and pull requests replace intents and attempts256 code and keeps them current. When a merged change contradicts a document,
257 an issue opens to update it.
258- **See it, don't read it.** Every pull request on a deployable repo gets a
259 preview URL (Workers Builds from the pull request's fork), so an approver clicks
Initial g1t: services, event bus, intents and attempts260 through the result instead of reading a diff. Changes are also summarised
261 in plain language.
262- **Roles.** Viewer, commenter, planner, approver: a person can plan and
263 approve work without ever cloning a repo.
264
265## The macro view
266
267The hierarchy above a single repo:
268
269| Level | What it is |
270| --- | --- |
271| **Workspace** | A company or team: its people, repos, agents, budget and policies. |
272| **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 attempts273| **Project** | One deliverable inside an initiative: a brief and its graph of issues. |
274| **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 attempts275
276### Portfolio
277
278One page answers "where is the business" across every initiative:
279
280- **Health** per initiative: on track, at risk, or blocked, derived from
Issues and pull requests replace intents and attempts281 facts (checks passing, issues stalled, questions waiting on a person),
Initial g1t: services, event bus, intents and attempts282 not self-reported.
Issues and pull requests replace intents and attempts283- **Progress** as measurable results: acceptance checks passing, issues
284 merged out of planned, and the trend since the start.
Initial g1t: services, event bus, intents and attempts285- **Forecast** from actual throughput: at the current rate, when the
Issues and pull requests replace intents and attempts286 remaining issues land.
Initial g1t: services, event bus, intents and attempts287- **Spend** in tokens and dollars against a budget, per initiative.
288- **Waiting on people**: every decision or approval a person owes, by name.
289- **Roadmap**: initiatives laid out as now, next, later, with optional
290 time-boxed cycles for teams that work in sprints.
291
292### Status without asking
293
294- **Standup.** An agent writes a daily report per initiative and one for the
Issues and pull requests replace intents and attempts295 whole workspace: what merged, what changed direction, what is at risk and
Initial g1t: services, event bus, intents and attempts296 why, what needs a person. Delivered by email or webhook.
297- **Ask.** A question box over the full event log and all sessions: "what
298 happened on the billing migration since Monday?" answers with links to the
299 sessions and commits behind each claim.
300
301### Long-running agents
302
303Work that runs for days needs supervision that does not depend on someone
304watching.
305
Issues and pull requests replace intents and attempts306- **Checkpoints.** A long pull request reports milestones against its issue, so
307 progress is visible before anything merges.
308- **Stall and drift detection.** A pull request with no meaningful progress, or
309 whose changes have wandered away from its issue, is flagged and can be
Initial g1t: services, event bus, intents and attempts310 stopped or re-briefed automatically.
Issues and pull requests replace intents and attempts311- **Budgets.** Hard limits on spend and time per pull request, project and
Initial g1t: services, event bus, intents and attempts312 initiative.
313
314### Context hub
315
316Agents working across repos and days need context that outlives any one
317session and reaches beyond the code. The context hub is one place an agent
318asks, whatever the source.
319
320| Source | What it holds | How it gets there |
321| --- | --- | --- |
322| **Memory** | Decisions, conventions, gotchas, facts about systems | Written by agents and people in g1t |
323| **Code and sessions** | The repos, and the reasoning behind every change | Already in g1t |
324| **Connected sources** | Jira and Linear tickets, Notion and Confluence pages, Google Drive documents, Slack threads, Sentry issues | Connectors, authorised per workspace |
325
326How it behaves:
327
328- **One search.** An agent asks a question and gets ranked results across
329 all sources, each labelled with where it came from, who wrote it, and how
330 fresh it is.
331- **Connected sources stay where they are.** g1t indexes them for search and
332 fetches the current version when an agent opens one. The external system
Issues and pull requests replace intents and attempts333 remains the source of truth, and a link placed on an issue ("see
Initial g1t: services, event bus, intents and attempts334 JIRA-482", a Notion URL) is pulled into the agent's starting context.
335- **Permissions carry over.** A connector only exposes what the connecting
336 account can see, and a workspace admin chooses which spaces, projects or
337 channels are included.
338- **External content is untrusted.** A ticket or page can contain text meant
339 to manipulate an agent. It is marked as reference material, never treated
340 as instructions.
341- **Documentation is separate.** Context is what agents know; documentation
342 is what people read, and it is generated from context and code.
343
344Memory is the part of the hub that g1t owns and agents write to:
345
346- **Memory is written freely.** Any agent or person adds an entry with one
347 call: a decision, a convention, a gotcha, a fact about a system. No review
348 gate. Each entry records who wrote it, from which session, and when.
349- **It is still a repository.** Each workspace has a memory repo in
350 Artifacts, so every write is a commit: versioned, attributable, and
351 revertible.
352- **It is kept healthy by an agent.** A consolidation agent merges
353 duplicates, retires entries that newer ones contradict, and flags
354 conflicts it cannot settle. People can pin an entry (agents may not change
355 it), correct it, or retract it.
356- **Agents read it.** Every session starts with the context relevant to its
Issues and pull requests replace intents and attempts357 issue, found by search, and can query more through MCP.
Initial g1t: services, event bus, intents and attempts358- **Updates are events.** A memory write or a change in a connected source
359 is an event, so "when context changes, update the affected docs" is an
360 automation, on by default.
361- **It is scoped inside the workspace.** Some context applies to the whole
362 workspace, some to one initiative, project or repo, so an agent gets what
363 applies to its work.
364- **It never crosses workspaces.** A workspace is the isolation boundary: its
365 context, sessions and private repos are invisible to every other
366 workspace, and an agent's token is bound to one workspace.
367
368## Working in g1t
369
370- **Mission control.** The signed-in home page: every running session, every
Issues and pull requests replace intents and attempts371 issue waiting on a decision, and what merged, across all repos.
372- **Projects.** Group issues across repos toward one outcome and track how
373 many are open, racing, or merged.
374- **Steering.** Send a message to a running pull request, or to all pull requests on an
375 issue at once, without stopping them.
Initial g1t: services, event bus, intents and attempts376- **Automations.** Rules that start work without a person (next section).
377
378## Automations and integrations
379
380An automation is **when** an event happens, **if** conditions hold, **do**
381something. They are defined as files in the repo (`.g1t/automations/`), the
382way GitHub Actions workflows are, and can also be built in the UI.
383
384### Events that can trigger one
385
386| Source | Examples |
387| --- | --- |
Issues and pull requests replace intents and attempts388| Git | push, merge, check failed, `main` moved |
389| g1t | issue opened, pull request stalled, context updated, handoff declined, budget reached |
Initial g1t: services, event bus, intents and attempts390| Time | cron schedule |
391| Integrations | Sentry issue, PagerDuty incident, Linear or Jira ticket, Slack message or mention, GitHub issue, Stripe event |
392| Anything else | a signed generic webhook, or an email to a per-repo address |
393
Issues and pull requests replace intents and attempts394**Actions**: open an issue (optionally assigning N agents to it), message
395a running pull request, update documentation, notify, call a
Initial g1t: services, event bus, intents and attempts396webhook, write back to the source system.
397
398**Example: Sentry.** A new production error arrives. The automation opens an
Issues and pull requests replace intents and attempts399issue labelled `bug`, with the stack trace, release and frequency in its
400description. Why-blame
Initial g1t: services, event bus, intents and attempts401finds the session that wrote the failing line, so the fixing agent starts
Issues and pull requests replace intents and attempts402with the original reasoning. When the fix merges, g1t comments on the Sentry
Initial g1t: services, event bus, intents and attempts403issue and resolves it.
404
405### Rules every automation obeys
406
407- **Deduplication.** The same Sentry issue firing 500 times maps to one
Issues and pull requests replace intents and attempts408 issue.
Initial g1t: services, event bus, intents and attempts409- **Limits.** Concurrency and budget caps per automation.
410- **Loop protection.** Work started by an automation cannot retrigger the
411 same automation without a person in between.
412- **External input is untrusted.** A webhook payload can contain text written
413 by an attacker. Agents started by external events run with reduced
Issues and pull requests replace intents and attempts414 permissions and cannot merge without the repo's approval rule passing.
Initial g1t: services, event bus, intents and attempts415
416**Checks** are the other half of what GitHub Actions does: build and test
Issues and pull requests replace intents and attempts417commands declared in `.g1t/checks.yaml`, run in sandboxes on every pull request
Initial g1t: services, event bus, intents and attempts418and on every combined state in the landing queue.
419
420Agents can also reach integrations directly: an agent definition lists MCP
421servers (Sentry, Linear and so on) it may use while working.
422
423## Agents and models
424
425### Defining an agent
426
427An agent is a file (`.g1t/agents/<name>.md`, or in the workspace library):
428instructions, the harness and model to run, the tools and MCP servers it may
429use, its sandbox image, permissions and budget. Agents take roles: planner,
430implementer, reviewer, conflict resolver, documenter, memory consolidator.
431Each role has a default that a repo can replace.
432
433### Where it runs, and on whose model
434
435| Option | How it works | Fits |
436| --- | --- | --- |
437| Hosted, g1t's model | g1t runs the sandbox and bills usage | Getting started; no keys to manage |
438| Hosted, your API key | Same sandbox, your Anthropic, OpenAI or Google key | Teams with existing contracts |
439| 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 attempts440| 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 attempts441| Your own session | Local Claude Code, Cursor or any MCP client joins through `mcp.g1t.sh` | Individuals; subscription plans |
442
443Decisions behind this:
444
445- **g1t does not build its own agent loop.** It runs existing harnesses
446 (Claude Code first, through its headless mode) behind a small runner
447 contract: a container image, an entry command, and session events reported
448 through the CLI. Other harnesses plug in by meeting the contract.
449- **All hosted model traffic goes through Cloudflare AI Gateway.** That gives
450 one place for spend tracking, budgets, rate limits, fallback and logs,
451 whichever provider or endpoint is behind it.
452- **Subscriptions stay local.** A Claude subscription cannot be used by a
453 hosted sandbox; it needs an API key. People on subscriptions use their own
454 Claude Code session, which is a full participant.
455- **Keys are secrets.** Stored in Cloudflare Secrets Store, injected into the
Issues and pull requests replace intents and attempts456 sandbox for one pull request, never shown again.
Initial g1t: services, event bus, intents and attempts457
458### Choosing the right agent automatically
459
Issues and pull requests replace intents and attempts460Because several agents can work on the same issue, every issue with more
461than 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 attempts462agent's win rate, cost and time. That produces a leaderboard, and a routing
Issues and pull requests replace intents and attempts463policy: send each new issue to the agent that wins that kind most often,
Initial g1t: services, event bus, intents and attempts464start with the cheapest that is good enough, and escalate to a stronger one
465when checks fail.
466
467## What GitHub ships today, and where g1t differs
468
469GitHub's Agent HQ and Copilot app give each agent session its own git
470worktree and branch, list sessions in a mission-control view grouped by
471project, and let a task be assigned to several agents so their output can be
472compared. Underneath, the unit of work is still a branch and a pull request.
473
474| | GitHub | g1t |
475| --- | --- | --- |
476| 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 |
477| 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 attempts478| 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 attempts479| Collisions between agents | Found as merge conflicts at the end | Flagged during the work (overlap radar) |
Issues and pull requests replace intents and attempts480| 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 attempts481| Which agents | Those offered through a Copilot subscription | Any MCP client, plus hosted agents |
482
483## How agents connect
484
4851. **Bring your own agent.** A remote MCP server at `mcp.g1t.sh` lets Claude
Issues and pull requests replace intents and attempts486 Code (or any MCP client) list issues, claim one, get a clone URL and
Initial g1t: services, event bus, intents and attempts487 token, report progress and submit. Adding it is one command; sign-in is a
488 browser OAuth flow with no token to paste. The `g1t` CLI installs Claude
489 Code hooks that upload the session transcript as the agent works.
Issues and pull requests replace intents and attempts4902. **g1t agents.** Assign up to five of g1t's own agents to an issue. g1t
491 starts a sandbox for each (Cloudflare Containers), running a coding agent
492 headless against its own pull request and fork.
Initial g1t: services, event bus, intents and attempts4933. **API and CLI.** Everything above is available at `api.g1t.sh` and
494 through `g1t`.
495
496## Public surfaces
497
498| Host | What it serves |
499| --- | --- |
500| `g1t.sh` | The site, git over HTTPS, git over SSH |
Issues and pull requests replace intents and attempts501| `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 attempts502| `mcp.g1t.sh` | Remote MCP server over streamable HTTP |
503
504g1t is its own OAuth 2.1 authorization server: authorization code with PKCE,
OAuth 2.1 sign-in for MCP clients and other applications505dynamic client registration that stores nothing (a client id encodes its
506own registration, so the open endpoint cannot be used to fill a database),
507discovery metadata and rotating refresh tokens. Still to come: scopes
Issues and pull requests replace intents and attempts508per resource (`repo:read`, `repo:write`, `issue:write`, `pull:write`).
Initial g1t: services, event bus, intents and attempts509MCP clients, the CLI (device flow) and third-party apps all use it. Access
510tokens and SSH keys remain for git itself.
511
512## Architecture
513
514| Component | Language | Runs on | Responsibility |
515| --- | --- | --- | --- |
Issues and pull requests replace intents and attempts516| `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 applications517| `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 attempts518| `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. |
519| `services/work` | Rust | Worker + D1 | Issues, pull requests, comments, sessions; later a Durable Object per repo for the landing queue and live state |
520| `services/events` | TypeScript, moving to Rust | Worker + Queues + D1 | The event bus: durable log, and one queue per subscribing service |
521| `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 attempts522| `apps/web` | TypeScript | Worker | Server-rendered site. Holds no data; calls services over RPC. |
Issues and pull requests replace intents and attempts523| `apps/docs` | TypeScript | Worker (static) | Documentation and the API explorer |
524| `apps/api` | TypeScript, moving to Rust | Worker | REST API (`api.g1t.sh`) and MCP server (`mcp.g1t.sh`), both generated from one list of operations |
Initial g1t: services, event bus, intents and attempts525| `crates/sshd` | Rust | Container | Git over SSH, bridged to Artifacts |
526| `crates/merged` | Rust | Container | Trial merges, conflict matrix, landing merges (needs real git; the Artifacts binding is read-only) |
527| `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 attempts528| `crates/g1t` | Rust | user's machine | CLI: auth, SSH proxy, Claude Code hooks, issues and pull requests |
Initial g1t: services, event bus, intents and attempts529
Issues and pull requests replace intents and attempts530Storage: Artifacts for repositories (one fork per pull request), D1 for accounts
Initial g1t: services, event bus, intents and attempts531and metadata, R2 for session transcripts and logs, Durable Object SQLite for
532per-repo coordination state.
533
534How the services fit together:
535
536- **Each service is its own Worker with its own database.** It deploys,
537 scales and fails on its own. Callers reach it through a typed RPC binding
538 to the interface in `packages/contracts`.
539- **Expected failures are values.** Every call returns a `Result`, so "not
540 found" or "forbidden" crosses a service boundary as data.
541- **Side effects travel as events.** A service publishes what happened
Issues and pull requests replace intents and attempts542 (`git.push`, `issue.opened`, `pull.merged`, …) to the bus and does not
Initial g1t: services, event bus, intents and attempts543 call other services to react. Each subscriber consumes from its own queue.
544 Timelines, webhooks and automations read the same stream, which is what
545 lets something like GitHub Actions be built on top.
546- **Every read takes the viewer.** Authorization is decided inside the
547 service that owns the data, not by its callers.
548
549The Workers runtime scales request handling on its own, so the edge layer
550stays in TypeScript. Rust is used where there is real computation or a real
551protocol to implement.
552
API and MCP server, Rust identity service, registration, site redesign553## Languages
554
555The site is TypeScript. Everything behind it is Rust, compiled to
556WebAssembly for Workers and natively for containers and the CLI. Services
Issues and pull requests replace intents and attempts557are being ported one at a time; identity, repos and work are done, events
558and the API are next. Rust services speak a
API and MCP server, Rust identity service, registration, site redesign559small JSON protocol over service bindings (`POST /rpc/<method>`), with the
560types in `crates/contracts`.
561
562## Identifiers
563
564Every id is a [TypeID](https://github.com/jetify-com/typeid): a prefix naming
565the kind of thing, then a UUIDv7 in lowercase base32, such as
Issues and pull requests replace intents and attempts566`pr_01jb2k7x9hfq0b3zj0f5s2m8ra`.
API and MCP server, Rust identity service, registration, site redesign567
568- The prefix makes an id self-describing and stops ids of different kinds
569 being mixed up.
570- Ids sort by creation time as plain strings. In SQLite (D1 and Durable
571 Objects) that keeps inserts at the end of the primary-key index instead of
572 scattering them, and gives time-ordered paging for free.
573- The suffix decodes to a standard UUIDv7 for any system that wants one.
574- Ids are made by the service that creates the record, not by the database,
575 so they work across services and can be assigned before a write.
576
577## Events at scale, and audit
578
579The current event log is a single D1 database. That is fine for a
580prototype and wrong for the target: D1 is one writer and 10 GB. The design
581for volume splits storage by how the data is read.
582
583| Tier | Store | Holds | Read by |
584| --- | --- | --- | --- |
585| Hot | A Durable Object per repository, with SQLite | Recent events for that repo | Timelines, live pages over WebSocket |
586| Complete | Cloudflare Pipelines into R2 as Apache Iceberg | Every event, forever, partitioned by day and workspace | Analytics, standups, "ask", export |
587| Audit | The same R2 store, under object lock | Who did what, from where, with which credential | Compliance, investigation |
588
589- **No single hot database.** Each repository's recent events live with that
590 repository, so load spreads across as many objects as there are repos.
591- **The complete record is files, not rows.** Iceberg on R2 has no practical
592 size limit and is queried with SQL.
593- **Audit is a property of every event.** The envelope carries the actor
594 (person, agent, token or system), the credential used, the request id and
595 the source address. Audit entries for a workspace are hash-chained, so a
596 removed or altered entry is detectable, and are written under a retention
597 lock.
598- **Delivery is at least once.** Consumers are idempotent on the event id.
599
Initial g1t: services, event bus, intents and attempts600## Accounts and forge basics
601
602- Registration with email verification, sign-in, forgot password (Cloudflare
603 Email Sending), Turnstile on public forms.
604- GitHub sign-in, SSH keys, access tokens, active sessions.
605- Profiles, public and private repositories, repository search (D1 full-text).
606- Rendered README, syntax highlighting, commit history, diffs.
607
608## Built on Cloudflare
609
610| Need | Product |
611| --- | --- |
Issues and pull requests replace intents and attempts612| Repositories; a fork per pull request; data residency per workspace | Artifacts (forks, jurisdictions) |
Initial g1t: services, event bus, intents and attempts613| Reacting to pushes | Artifacts event subscriptions on Queues |
Issues and pull requests replace intents and attempts614| Preview URL per pull request; deploy on merge | Workers Builds and previews |
Initial g1t: services, event bus, intents and attempts615| Site, API, MCP, git front end | Workers |
616| Per-repo coordination, live updates | Durable Objects |
Issues and pull requests replace intents and attempts617| Pull request lifecycles, automations | Workflows, Cron Triggers |
Initial g1t: services, event bus, intents and attempts618| Agent sandboxes, SSH server, merge engine | Sandbox SDK and Containers |
619| Fast starts on large repos | ArtifactFS |
620| Model traffic, spend, budgets | AI Gateway |
621| Summaries, embeddings | Workers AI |
622| Context hub search | Vectorize |
623| Accounts and metadata | D1 |
624| Transcripts and logs | R2 |
625| Email, bot protection, keys | Email Sending, Turnstile, Secrets Store |
626
627## The submission
628
629- **g1t is built on g1t.** This repository is hosted on g1t.sh, its features
Issues and pull requests replace intents and attempts630 are opened as issues and built by racing agents, and it deploys from
Initial g1t: services, event bus, intents and attempts631 Artifacts through Workers Builds. The history is the proof.
Issues and pull requests replace intents and attempts632- **The demo follows one story.** A brief becomes a project; twelve issues
Initial g1t: services, event bus, intents and attempts633 fan out to dozens of agents; agents notice each other, hand off, and
634 resolve a conflict; reviewers triage; the queue lands everything on
635 `main`; why-blame explains a line; the portfolio shows where it all
636 stands. Then the same thing at a thousand agents.
637- **Judges can try it in a minute.** Open registration on g1t.sh, one-click
638 import of a GitHub repo, one command to connect Claude Code, a seeded demo
639 workspace, and a single deploy command for running their own copy.
640- **The formats are open.** The commit trailers, session format and runner
641 contract are published so other tools can interoperate.
642
643## Build order
644
Issues and pull requests replace intents and attempts645Done: site with marketing page; separate docs site with API explorer; git
646over HTTPS; accounts with registration, email verification, password reset
OAuth 2.1 sign-in for MCP clients and other applications647and device sign-in; an OAuth 2.1 server, so MCP clients sign in through the
648browser with no token to paste; workspaces with members; issues with labels, checks and
Issues and pull requests replace intents and attempts649comments; pull requests in forks with diffs and sessions, several per
650issue; merging with a behind check, which resolves the issue and supersedes
651the rest; g1t agents in sandboxes with a choice of model; REST API, OpenAPI
652and MCP server; event bus. Identity, repos and work are in Rust.
Initial g1t: services, event bus, intents and attempts653
Issues and pull requests replace intents and attempts6541. Pull requests from branches pushed to the repository.
OAuth 2.1 sign-in for MCP clients and other applications6552. Scopes on OAuth grants and access tokens.
Issues and pull requests replace intents and attempts6563. Port events and the API to Rust; event storage per the design above.
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).