flagon-io/g1t

public

644 lines34,131 bytesCode Blame

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 attempts5d ago	1	# g1t plan
	2
	3	g1t is a git forge for agents, built on Cloudflare Workers and Artifacts for
	4	the "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
	14	A pull request assumes one author and one change. g1t assumes many agents
	15	working at once, in two shapes: several agents racing on the same goal, and
	16	many different goals in flight that all have to land on `main`.
	17
	18	\| Concept \| What it is \|
	19	\| --- \| --- \|
Rust repos service with shipping; pull requests kept in the model5d ago	20	\| Intent \| A goal stated against a repo, with acceptance checks (commands that must pass). The issue, and the home of every pull request made for it. \|
Initial g1t: services, event bus, intents and attempts5d ago	21	\| Attempt \| One agent's run at an intent, in its own Artifacts fork. Any number run in parallel. \|
	22	\| Session \| The agent's full context for an attempt: prompt, messages, tool calls, cost. Stored with the attempt and linked from every commit it produced. \|
	23	\| Arena \| The compare view for an intent: every attempt side by side with diff, check results, conflicts against main and against each other, and a reviewer agent's summary. \|
	24	\| Ship \| A person or a policy picks an attempt. A per-repo merge queue lands it; the other attempts are rebased by their agents or closed. \|
	25
	26	Features that fall out of the model:
	27
	28	- Why-blame. Click a line and see the prompt and reasoning that produced
	29	it, not only the commit.
	30	- Overlap radar. Attempts that touch the same files are flagged while the
	31	agents are still working, and the agents are told.
	32	- Live lanes. Watch every attempt progress in real time.
	33
Rust repos service with shipping; pull requests kept in the model5d ago	34	## Pull requests are not removed
	35
	36	g1t is ordinary git, and the pull request stays. The model extends it rather
	37	than replacing it, so an engineer's habits keep working and the agent
	38	features are there when wanted.
	39
	40	- An attempt is a pull request. It has a source (a fork, or a branch
	41	pushed to the repo), a diff, review comments, checks and a merge button.
	42	It is reachable as a pull request, with that name, in the UI and API.
	43	- An intent is the goal above it. Opening a pull request the familiar way
	44	creates its intent from the title and description, so nobody has to learn
	45	the word to use the product.
	46	- The developer path is unchanged. Push a branch, open a pull request,
	47	get review, merge.
	48	- The agent path adds to it. State the intent first, let several
	49	attempts run, compare them, ship one.
	50	- Both paths meet at `main`. The same landing rules apply to a person's
	51	pull request and an agent's attempt.
	52
Initial g1t: services, event bus, intents and attempts5d ago	53	## Converging on main
	54
	55	Twelve intents started together will finish at different times and touch
	56	overlapping code. Getting them all into `main` without a person refereeing
	57	is the hard part, and it is handled in four places.
	58
	59	1. Before work starts: plan the overlap away. A project is a graph of
	60	intents. A planner agent can split a large goal into intents, predict
	61	which files each will touch, and add a dependency where two would collide,
	62	so one starts from the other's result instead of from `main`.
	63	2. While agents work: overlap radar. Each attempt's changed files and
	64	symbols are tracked as it pushes. When two attempts from different intents
	65	enter the same area, both agents are told what the other is doing there.
	66	3. When `main` moves: the author resolves. Every open attempt is
	67	trial-merged against the new `main`. A clean merge updates the attempt
	68	silently. A conflict resumes that attempt's agent with its original
	69	session and the incoming change, so the conflict is resolved by the agent
	70	that wrote the code and still knows why.
	71	4. At landing: a speculative queue. Shipped attempts enter the repo's
	72	queue. g1t builds the combined states (`main`+A, `main`+A+B, …) and runs
	73	their checks in parallel. Attempts land in order as their combined state
	74	passes; one that fails is ejected back to its agent and the states behind
	75	it are rebuilt. `main` only ever receives a state that passed.
	76
	77	Landing can be fully automatic: a repo policy such as "checks pass and the
	78	reviewer agent approves" ships without a person.
	79
	80	## Agents aware of each other
	81
	82	Each repo keeps a live work registry: for every running attempt, its
	83	intent, a running summary of what it has done, and the files and symbols it
	84	has touched or plans to touch. Agents use it through MCP tools; g1t also
	85	acts on it without being asked.
	86
	87	- Before starting. When an intent is opened, or an agent is about to
	88	begin a task, g1t searches open intents and running attempts for the same
	89	goal (by meaning, not wording) and for the same area of code. If a match
	90	exists the agent is told who is on it and how far along, and chooses: join
	91	as a deliberate racer, wait for the result, or drop the task. Duplicate
	92	intents are offered for merging.
	93	- Finding out-of-scope work. An agent that discovers something outside
	94	its intent asks the registry who works there. If another attempt owns that
	95	area, it hands off: a note, the relevant excerpt of its session, and
	96	optionally commits the receiver can take. If nobody does, it opens a child
	97	intent instead of widening its own change.
	98	- Asking. An agent can put a question or a request to another attempt.
	99	The receiver gets it at its next turn.
	100	- Waiting. An agent that needs another attempt's result parks itself.
	101	Its sandbox sleeps, spend stops, and it resumes from the new state when
	102	that attempt ships.
	103	- Agents that do not cooperate. For pushes from tools that never call
	104	these tools, g1t compares the pushed change against running attempts and
	105	flags near-duplicates itself.
	106
	107	Every handoff, question and wait has a state (offered, accepted, declined,
	108	done), appears in the timeline, and is visible to people. A handoff declined
	109	twice, or two agents passing work back and forth, goes to the "needs you"
	110	inbox.
	111
	112	## Review at scale
	113
	114	Cloudflare's brief asks "how do you review everything they produce?". With
	115	hundreds of agents, a person cannot read every diff, so review is by
	116	exception.
	117
	118	- Evidence, not diffs. Every attempt carries a proof bundle: checks run
	119	and their output, a preview URL, a plain-language summary, and the
	120	behaviour that changed.
	121	- Two agent reviewers. One reviews the change against the intent. A
	122	second is adversarial: it tries to break the change and reports what it
	123	found.
	124	- Risk tiers. Each change is scored from what it touches, how large it
	125	is, and how the reviewers ruled. Low risk ships on policy; high risk goes
	126	to a person with the evidence already assembled.
	127	- Trust is earned. An agent's record on a path (shipped, reverted, caught
	128	by review) raises or lowers the tier its changes land in.
	129	- Sampling. A share of auto-shipped changes is sent to a person anyway,
	130	to keep the policy honest.
	131
	132	## Rethinking the git primitives
	133
	134	- No branches for agents. An attempt is a fork; `main` is the only
	135	long-lived line. There is nothing to name, clean up or go stale.
	136	- Projected main. New attempts start from `main` plus everything already
	137	in the landing queue, so they are built on the state they will land on.
	138	- Structural merge. The merge engine merges by syntax tree, not by line,
	139	for supported languages. Two agents adding different functions to the same
	140	file do not conflict.
	141	- Forkable sessions. A session can be forked at any turn: the code as it
	142	was at that moment plus the conversation up to it, continued with a
	143	different instruction. Branching applies to the reasoning as well as the
	144	code.
	145	- Provenance in history. Every commit records its intent, session,
	146	agent, model and cost, and is signed with a key issued to that attempt. The
	147	history can be audited by machine.
	148
	149	## People in the loop
	150
	151	### Code that arrives from outside
	152
	153	People will keep pushing with plain git, their editor, or another tool. Every
	154	push goes through g1t's git front end, so none of it bypasses the model.
	155
	156	- A push to a branch becomes an attempt. g1t adopts it with the pusher as
	157	author. A reviewer agent writes the intent it appears to serve and offers
	158	to attach it to an open intent it matches. From there it gets the same
	159	checks, arena and queue as agent work.
	160	- A push to `main` follows repo policy. Protected: refused with a message
	161	saying which ref to push to instead, so it enters the queue. Open: accepted
	162	and treated as "`main` moved", which re-verifies the queue and triggers
	163	resolve-on-move for every open attempt.
	164	- Context is an open format. A commit trailer names the session that
	165	produced it, so any tool can attach its transcript. Commits without one are
	166	shown in why-blame as "pushed by a person, no session".
	167	- Approval rules. Per repo and per path: ship automatically, require a
	168	named person, or require a person when the change is large or the reviewer
	169	agent is unsure.
	170
	171	### Joining work that is already running
	172
	173	- Every session has a live page that works on a phone: the transcript as
	174	it streams, the current diff, check results.
	175	- Steer. Send a message, pause, or redirect. Hosted agents receive it
	176	immediately; a person's own Claude Code receives it at its next turn
	177	through the CLI hooks.
	178	- Answer. When an agent is blocked on a question, it appears in a "needs
	179	you" inbox and as a notification. The answer resumes the agent.
	180	- Take over and hand back. Check out the attempt's fork, commit by hand,
	181	push, and let the agent continue from there.
	182
	183	### Planning by writing
	184
	185	- Brief. Write the outcome in prose on the site, or commit it as a
	186	markdown file. A planner agent turns it into a project: intents, acceptance
	187	checks, dependencies. The person edits the graph before anything starts.
	188	- Plan from their own agent. The same operations are MCP tools, so a
	189	person can plan in their own Claude Code session and create the project
	190	from there.
	191	- The brief stays the source of truth. Editing it later re-plans: new
	192	intents are added, obsolete ones are closed.
	193
	194	### Seeing what moved
	195
	196	- Project page. The outcome, the intent graph coloured by state, and how
	197	many acceptance checks pass now compared with when the project started.
	198	- Digest. An agent-written summary per project and per person: what
	199	shipped, what is blocked on whom, which conflicts were resolved, what it
	200	cost.
	201	- Timeline. Every event (push, steer, check, conflict, ship) in order,
	202	each linked to the session and the person or agent behind it.
	203
	204	## One session, any surface
	205
	206	A session belongs to g1t, not to the device it started on. The browser, a
	207	phone and Claude Code are views of the same session.
	208
	209	- Browser and phone. The site is a responsive, installable web app with
	210	push notifications. Everything a person does (brief, steer, answer,
	211	approve, ship) works there.
	212	- Claude Code. Through `mcp.g1t.sh` and the CLI hooks, a local session is
	213	a g1t session: its transcript syncs as it runs and it appears in mission
	214	control like any other.
	215	- Moving a session. A local session can be sent to the cloud: a hosted
	216	agent takes over the fork and the transcript and continues, so the laptop
	217	can close. A hosted session can be pulled down: the CLI checks out the fork
	218	and resumes it in local Claude Code with its history.
	219	- Limit. A session running only on a laptop stops when the laptop does.
	220	It can be steered between turns but not continued until it is moved or the
	221	laptop is back.
	222
	223	## For people who do not write code
	224
	225	- Documents are first-class. Specs, guides, policies and decisions live
	226	in repos as markdown, shown in a Docs view: rendered pages, edited in the
	227	browser like a document, with inline comments. "Suggest a change" is an
	228	attempt and "publish" is ship, without git vocabulary.
	229	- Document intents. "Write the onboarding guide for the billing API" is
	230	an intent. Its acceptance checks are a checklist judged by a reviewer agent
	231	instead of commands. Agents draft and revise; people comment and approve.
	232	- Templates. Product brief, RFC, decision record. A filled-in template is
	233	a brief the planner can turn into a project.
	234	- Explain. Ask about any repo, project or change in plain language and
	235	get an answer with links to the code and sessions behind it.
	236	- Living documentation. g1t generates "how this works" pages from the
	237	code and keeps them current. When a shipped change contradicts a document,
	238	an intent opens to update it.
	239	- See it, don't read it. Every attempt on a deployable repo gets a
	240	preview URL (Workers Builds from the attempt's fork), so an approver clicks
	241	through the result instead of reading a diff. Changes are also summarised
	242	in plain language.
	243	- Roles. Viewer, commenter, planner, approver: a person can plan and
	244	approve work without ever cloning a repo.
	245
	246	## The macro view
	247
	248	The hierarchy above a single repo:
	249
	250	\| Level \| What it is \|
	251	\| --- \| --- \|
	252	\| Workspace \| A company or team: its people, repos, agents, budget and policies. \|
	253	\| Initiative \| A business outcome with an owner and measurable results, e.g. "move billing to usage-based pricing". Spans any number of repos. \|
	254	\| Project \| One deliverable inside an initiative: a brief and its graph of intents. \|
	255	\| Intent / Attempt \| As above. An intent may touch several repos; its attempt then holds one fork per repo and they land together. \|
	256
	257	### Portfolio
	258
	259	One page answers "where is the business" across every initiative:
	260
	261	- Health per initiative: on track, at risk, or blocked, derived from
	262	facts (checks passing, intents stalled, questions waiting on a person),
	263	not self-reported.
	264	- Progress as measurable results: acceptance checks passing, intents
	265	shipped out of planned, and the trend since the start.
	266	- Forecast from actual throughput: at the current rate, when the
	267	remaining intents land.
	268	- Spend in tokens and dollars against a budget, per initiative.
	269	- Waiting on people: every decision or approval a person owes, by name.
	270	- Roadmap: initiatives laid out as now, next, later, with optional
	271	time-boxed cycles for teams that work in sprints.
	272
	273	### Status without asking
	274
	275	- Standup. An agent writes a daily report per initiative and one for the
	276	whole workspace: what shipped, what changed direction, what is at risk and
	277	why, what needs a person. Delivered by email or webhook.
	278	- Ask. A question box over the full event log and all sessions: "what
	279	happened on the billing migration since Monday?" answers with links to the
	280	sessions and commits behind each claim.
	281
	282	### Long-running agents
	283
	284	Work that runs for days needs supervision that does not depend on someone
	285	watching.
	286
	287	- Checkpoints. A long attempt reports milestones against its intent, so
	288	progress is visible before anything ships.
	289	- Stall and drift detection. An attempt with no meaningful progress, or
	290	whose changes have wandered away from its intent, is flagged and can be
	291	stopped or re-briefed automatically.
	292	- Budgets. Hard limits on spend and time per attempt, project and
	293	initiative.
	294
	295	### Context hub
	296
	297	Agents working across repos and days need context that outlives any one
	298	session and reaches beyond the code. The context hub is one place an agent
	299	asks, whatever the source.
	300
	301	\| Source \| What it holds \| How it gets there \|
	302	\| --- \| --- \| --- \|
	303	\| Memory \| Decisions, conventions, gotchas, facts about systems \| Written by agents and people in g1t \|
	304	\| Code and sessions \| The repos, and the reasoning behind every change \| Already in g1t \|
	305	\| Connected sources \| Jira and Linear tickets, Notion and Confluence pages, Google Drive documents, Slack threads, Sentry issues \| Connectors, authorised per workspace \|
	306
	307	How it behaves:
	308
	309	- One search. An agent asks a question and gets ranked results across
	310	all sources, each labelled with where it came from, who wrote it, and how
	311	fresh it is.
	312	- Connected sources stay where they are. g1t indexes them for search and
	313	fetches the current version when an agent opens one. The external system
	314	remains the source of truth, and a link placed on an intent ("see
	315	JIRA-482", a Notion URL) is pulled into the agent's starting context.
	316	- Permissions carry over. A connector only exposes what the connecting
	317	account can see, and a workspace admin chooses which spaces, projects or
	318	channels are included.
	319	- External content is untrusted. A ticket or page can contain text meant
	320	to manipulate an agent. It is marked as reference material, never treated
	321	as instructions.
	322	- Documentation is separate. Context is what agents know; documentation
	323	is what people read, and it is generated from context and code.
	324
	325	Memory is the part of the hub that g1t owns and agents write to:
	326
	327	- Memory is written freely. Any agent or person adds an entry with one
	328	call: a decision, a convention, a gotcha, a fact about a system. No review
	329	gate. Each entry records who wrote it, from which session, and when.
	330	- It is still a repository. Each workspace has a memory repo in
	331	Artifacts, so every write is a commit: versioned, attributable, and
	332	revertible.
	333	- It is kept healthy by an agent. A consolidation agent merges
	334	duplicates, retires entries that newer ones contradict, and flags
	335	conflicts it cannot settle. People can pin an entry (agents may not change
	336	it), correct it, or retract it.
	337	- Agents read it. Every session starts with the context relevant to its
	338	intent, found by search, and can query more through MCP.
	339	- Updates are events. A memory write or a change in a connected source
	340	is an event, so "when context changes, update the affected docs" is an
	341	automation, on by default.
	342	- It is scoped inside the workspace. Some context applies to the whole
	343	workspace, some to one initiative, project or repo, so an agent gets what
	344	applies to its work.
	345	- It never crosses workspaces. A workspace is the isolation boundary: its
	346	context, sessions and private repos are invisible to every other
	347	workspace, and an agent's token is bound to one workspace.
	348
	349	## Working in g1t
	350
	351	- Mission control. The signed-in home page: every running session, every
	352	intent waiting on a decision, and what shipped, across all repos.
	353	- Projects. Group intents across repos toward one outcome and track how
	354	many are open, racing, or shipped.
	355	- Steering. Send a message to a running attempt, or to all attempts on an
	356	intent at once, without stopping them.
	357	- Automations. Rules that start work without a person (next section).
	358
	359	## Automations and integrations
	360
	361	An automation is when an event happens, if conditions hold, do
	362	something. They are defined as files in the repo (`.g1t/automations/`), the
	363	way GitHub Actions workflows are, and can also be built in the UI.
	364
	365	### Events that can trigger one
	366
	367	\| Source \| Examples \|
	368	\| --- \| --- \|
	369	\| Git \| push, ship, check failed, `main` moved \|
	370	\| g1t \| intent opened, attempt stalled, context updated, handoff declined, budget reached \|
	371	\| Time \| cron schedule \|
	372	\| Integrations \| Sentry issue, PagerDuty incident, Linear or Jira ticket, Slack message or mention, GitHub issue, Stripe event \|
	373	\| Anything else \| a signed generic webhook, or an email to a per-repo address \|
	374
	375	Actions: open an intent (optionally racing N attempts with a named
	376	agent), message a running attempt, update documentation, notify, call a
	377	webhook, write back to the source system.
	378
	379	Example: Sentry. A new production error arrives. The automation opens an
	380	intent with the stack trace, release and frequency as its brief. Why-blame
	381	finds the session that wrote the failing line, so the fixing agent starts
	382	with the original reasoning. When the fix ships, g1t comments on the Sentry
	383	issue and resolves it.
	384
	385	### Rules every automation obeys
	386
	387	- Deduplication. The same Sentry issue firing 500 times maps to one
	388	intent.
	389	- Limits. Concurrency and budget caps per automation.
	390	- Loop protection. Work started by an automation cannot retrigger the
	391	same automation without a person in between.
	392	- External input is untrusted. A webhook payload can contain text written
	393	by an attacker. Agents started by external events run with reduced
	394	permissions and cannot ship without the repo's approval rule passing.
	395
	396	Checks are the other half of what GitHub Actions does: build and test
	397	commands declared in `.g1t/checks.yaml`, run in sandboxes on every attempt
	398	and on every combined state in the landing queue.
	399
	400	Agents can also reach integrations directly: an agent definition lists MCP
	401	servers (Sentry, Linear and so on) it may use while working.
	402
	403	## Agents and models
	404
	405	### Defining an agent
	406
	407	An agent is a file (`.g1t/agents/<name>.md`, or in the workspace library):
	408	instructions, the harness and model to run, the tools and MCP servers it may
	409	use, its sandbox image, permissions and budget. Agents take roles: planner,
	410	implementer, reviewer, conflict resolver, documenter, memory consolidator.
	411	Each role has a default that a repo can replace.
	412
	413	### Where it runs, and on whose model
	414
	415	\| Option \| How it works \| Fits \|
	416	\| --- \| --- \| --- \|
	417	\| Hosted, g1t's model \| g1t runs the sandbox and bills usage \| Getting started; no keys to manage \|
	418	\| Hosted, your API key \| Same sandbox, your Anthropic, OpenAI or Google key \| Teams with existing contracts \|
	419	\| Hosted, your endpoint \| Any OpenAI-compatible URL: Bedrock, Vertex, Azure, a self-hosted model \| Private or fine-tuned models \|
	420	\| Your runner \| A g1t runner daemon on your own machines picks up attempts \| Code or models that may not leave your network \|
	421	\| Your own session \| Local Claude Code, Cursor or any MCP client joins through `mcp.g1t.sh` \| Individuals; subscription plans \|
	422
	423	Decisions behind this:
	424
	425	- g1t does not build its own agent loop. It runs existing harnesses
	426	(Claude Code first, through its headless mode) behind a small runner
	427	contract: a container image, an entry command, and session events reported
	428	through the CLI. Other harnesses plug in by meeting the contract.
	429	- All hosted model traffic goes through Cloudflare AI Gateway. That gives
	430	one place for spend tracking, budgets, rate limits, fallback and logs,
	431	whichever provider or endpoint is behind it.
	432	- Subscriptions stay local. A Claude subscription cannot be used by a
	433	hosted sandbox; it needs an API key. People on subscriptions use their own
	434	Claude Code session, which is a full participant.
	435	- Keys are secrets. Stored in Cloudflare Secrets Store, injected into the
	436	sandbox for one attempt, never shown again.
	437
	438	### Choosing the right agent automatically
	439
	440	Because several agents can race on the same intent, every arena is an
	441	evaluation on real work. g1t records, per repo and per kind of intent, each
	442	agent's win rate, cost and time. That produces a leaderboard, and a routing
	443	policy: send each new intent to the agent that wins that kind most often,
	444	start with the cheapest that is good enough, and escalate to a stronger one
	445	when checks fail.
	446
	447	## What GitHub ships today, and where g1t differs
	448
	449	GitHub's Agent HQ and Copilot app give each agent session its own git
	450	worktree and branch, list sessions in a mission-control view grouped by
	451	project, and let a task be assigned to several agents so their output can be
	452	compared. Underneath, the unit of work is still a branch and a pull request.
	453
	454	\| \| GitHub \| g1t \|
	455	\| --- \| --- \| --- \|
	456	\| 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 \|
	457	\| Agent context \| Lives in the app's session view \| Stored with the repository and linked from each commit (why-blame) \|
	458	\| Several agents on one task \| Separate pull requests to compare by hand \| One intent, one arena, ranked attempts \|
	459	\| Collisions between agents \| Found as merge conflicts at the end \| Flagged during the work (overlap radar) \|
	460	\| Landing changes \| One pull request at a time \| A merge queue that ships the winner and rebases or closes the rest \|
	461	\| Which agents \| Those offered through a Copilot subscription \| Any MCP client, plus hosted agents \|
	462
	463	## How agents connect
	464
	465	1. Bring your own agent. A remote MCP server at `mcp.g1t.sh` lets Claude
	466	Code (or any MCP client) list intents, claim one, get a clone URL and
	467	token, report progress and submit. Adding it is one command; sign-in is a
	468	browser OAuth flow with no token to paste. The `g1t` CLI installs Claude
	469	Code hooks that upload the session transcript as the agent works.
	470	2. Hosted agents. Press "Run 10 attempts" on an intent. g1t starts
	471	sandboxes (Cloudflare Sandbox SDK), each running a coding agent headless
	472	against its own fork.
	473	3. API and CLI. Everything above is available at `api.g1t.sh` and
	474	through `g1t`.
	475
	476	## Public surfaces
	477
	478	\| Host \| What it serves \|
	479	\| --- \| --- \|
	480	\| `g1t.sh` \| The site, git over HTTPS, git over SSH \|
	481	\| `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 attempt state, and signed webhooks \|
	482	\| `mcp.g1t.sh` \| Remote MCP server over streamable HTTP \|
	483
	484	g1t is its own OAuth 2.1 authorization server: authorization code with PKCE,
	485	dynamic client registration, discovery metadata, refresh tokens, and scopes
	486	per resource (`repo:read`, `repo:write`, `intent:write`, `attempt:write`).
	487	MCP clients, the CLI (device flow) and third-party apps all use it. Access
	488	tokens and SSH keys remain for git itself.
	489
	490	## Architecture
	491
	492	\| Component \| Language \| Runs on \| Responsibility \|
	493	\| --- \| --- \| --- \| --- \|
	494	\| `packages/contracts` \| TypeScript \| — \| The interface of every service, the event catalogue, shared types. Services and clients depend on this, never on each other's code. \|
	495	\| `services/identity` \| TypeScript \| Worker + D1 \| Accounts, sessions, SSH keys, access tokens; later the OAuth server \|
	496	\| `services/repos` \| TypeScript \| Worker + D1 + Artifacts \| Repository registry, contents, forks, git over HTTPS. Storage sits behind a `GitStore` port with an Artifacts adapter. \|
	497	\| `services/events` \| TypeScript \| Worker + Queues + D1 \| The event bus: durable log, and one queue per subscribing service \|
	498	\| `services/work` \| TypeScript \| Worker + D1 \| Intents, attempts, sessions; later a Durable Object per repo for the landing queue and live state \|
	499	\| `apps/web` \| TypeScript \| Worker \| Server-rendered site. Holds no data; calls services over RPC. \|
	500	\| `apps/api` (next) \| TypeScript \| Worker \| REST API (`api.g1t.sh`) and MCP server (`mcp.g1t.sh`) over the same services \|
	501	\| `crates/sshd` \| Rust \| Container \| Git over SSH, bridged to Artifacts \|
	502	\| `crates/merged` \| Rust \| Container \| Trial merges, conflict matrix, landing merges (needs real git; the Artifacts binding is read-only) \|
	503	\| `crates/core` \| Rust \| native and WASM \| pkt-line, packfile and diff code shared by the above and by the Worker \|
	504	\| `crates/g1t` \| Rust \| user's machine \| CLI: auth, SSH proxy, Claude Code hooks, intents and attempts \|
	505	\| runner image \| — \| Sandbox \| Hosted agent environment \|
	506
	507	Storage: Artifacts for repositories (one fork per attempt), D1 for accounts
	508	and metadata, R2 for session transcripts and logs, Durable Object SQLite for
	509	per-repo coordination state.
	510
	511	How the services fit together:
	512
	513	- Each service is its own Worker with its own database. It deploys,
	514	scales and fails on its own. Callers reach it through a typed RPC binding
	515	to the interface in `packages/contracts`.
	516	- Expected failures are values. Every call returns a `Result`, so "not
	517	found" or "forbidden" crosses a service boundary as data.
	518	- Side effects travel as events. A service publishes what happened
	519	(`git.push`, `intent.opened`, `attempt.started`, …) to the bus and does not
	520	call other services to react. Each subscriber consumes from its own queue.
	521	Timelines, webhooks and automations read the same stream, which is what
	522	lets something like GitHub Actions be built on top.
	523	- Every read takes the viewer. Authorization is decided inside the
	524	service that owns the data, not by its callers.
	525
	526	The Workers runtime scales request handling on its own, so the edge layer
	527	stays in TypeScript. Rust is used where there is real computation or a real
	528	protocol to implement.
	529
API and MCP server, Rust identity service, registration, site redesign5d ago	530	## Languages
	531
	532	The site is TypeScript. Everything behind it is Rust, compiled to
	533	WebAssembly for Workers and natively for containers and the CLI. Services
	534	are being ported one at a time; identity is done. Rust services speak a
	535	small JSON protocol over service bindings (`POST /rpc/<method>`), with the
	536	types in `crates/contracts`.
	537
	538	## Identifiers
	539
	540	Every id is a [TypeID](https://github.com/jetify-com/typeid): a prefix naming
	541	the kind of thing, then a UUIDv7 in lowercase base32, such as
	542	`att_01jb2k7x9hfq0b3zj0f5s2m8ra`.
	543
	544	- The prefix makes an id self-describing and stops ids of different kinds
	545	being mixed up.
	546	- Ids sort by creation time as plain strings. In SQLite (D1 and Durable
	547	Objects) that keeps inserts at the end of the primary-key index instead of
	548	scattering them, and gives time-ordered paging for free.
	549	- The suffix decodes to a standard UUIDv7 for any system that wants one.
	550	- Ids are made by the service that creates the record, not by the database,
	551	so they work across services and can be assigned before a write.
	552
	553	## Events at scale, and audit
	554
	555	The current event log is a single D1 database. That is fine for a
	556	prototype and wrong for the target: D1 is one writer and 10 GB. The design
	557	for volume splits storage by how the data is read.
	558
	559	\| Tier \| Store \| Holds \| Read by \|
	560	\| --- \| --- \| --- \| --- \|
	561	\| Hot \| A Durable Object per repository, with SQLite \| Recent events for that repo \| Timelines, live pages over WebSocket \|
	562	\| Complete \| Cloudflare Pipelines into R2 as Apache Iceberg \| Every event, forever, partitioned by day and workspace \| Analytics, standups, "ask", export \|
	563	\| Audit \| The same R2 store, under object lock \| Who did what, from where, with which credential \| Compliance, investigation \|
	564
	565	- No single hot database. Each repository's recent events live with that
	566	repository, so load spreads across as many objects as there are repos.
	567	- The complete record is files, not rows. Iceberg on R2 has no practical
	568	size limit and is queried with SQL.
	569	- Audit is a property of every event. The envelope carries the actor
	570	(person, agent, token or system), the credential used, the request id and
	571	the source address. Audit entries for a workspace are hash-chained, so a
	572	removed or altered entry is detectable, and are written under a retention
	573	lock.
	574	- Delivery is at least once. Consumers are idempotent on the event id.
	575
Initial g1t: services, event bus, intents and attempts5d ago	576	## Accounts and forge basics
	577
	578	- Registration with email verification, sign-in, forgot password (Cloudflare
	579	Email Sending), Turnstile on public forms.
	580	- GitHub sign-in, SSH keys, access tokens, active sessions.
	581	- Profiles, public and private repositories, repository search (D1 full-text).
	582	- Rendered README, syntax highlighting, commit history, diffs.
	583
	584	## Built on Cloudflare
	585
	586	\| Need \| Product \|
	587	\| --- \| --- \|
	588	\| Repositories; a fork per attempt; data residency per workspace \| Artifacts (forks, jurisdictions) \|
	589	\| Reacting to pushes \| Artifacts event subscriptions on Queues \|
	590	\| Preview URL per attempt; deploy on ship \| Workers Builds and previews \|
	591	\| Site, API, MCP, git front end \| Workers \|
	592	\| Per-repo coordination, live updates \| Durable Objects \|
	593	\| Attempt lifecycles, automations \| Workflows, Cron Triggers \|
	594	\| Agent sandboxes, SSH server, merge engine \| Sandbox SDK and Containers \|
	595	\| Fast starts on large repos \| ArtifactFS \|
	596	\| Model traffic, spend, budgets \| AI Gateway \|
	597	\| Summaries, embeddings \| Workers AI \|
	598	\| Context hub search \| Vectorize \|
	599	\| Accounts and metadata \| D1 \|
	600	\| Transcripts and logs \| R2 \|
	601	\| Email, bot protection, keys \| Email Sending, Turnstile, Secrets Store \|
	602
	603	## The submission
	604
	605	- g1t is built on g1t. This repository is hosted on g1t.sh, its features
	606	are opened as intents and built by racing agents, and it deploys from
	607	Artifacts through Workers Builds. The history is the proof.
	608	- The demo follows one story. A brief becomes a project; twelve intents
	609	fan out to dozens of agents; agents notice each other, hand off, and
	610	resolve a conflict; reviewers triage; the queue lands everything on
	611	`main`; why-blame explains a line; the portfolio shows where it all
	612	stands. Then the same thing at a thousand agents.
	613	- Judges can try it in a minute. Open registration on g1t.sh, one-click
	614	import of a GitHub repo, one command to connect Claude Code, a seeded demo
	615	workspace, and a single deploy command for running their own copy.
	616	- The formats are open. The commit trailers, session format and runner
	617	contract are published so other tools can interoperate.
	618
	619	## Build order
	620
Rust repos service with shipping; pull requests kept in the model5d ago	621	Done: site with marketing page and docs; git over HTTPS; accounts with
	622	registration, email verification and password reset; intents, attempts and
	623	sessions; REST API and MCP server; event bus; shipping an attempt to `main`
	624	with a behind check. Identity and repos are in Rust.
Initial g1t: services, event bus, intents and attempts5d ago	625
Rust repos service with shipping; pull requests kept in the model5d ago	626	1. Diffs and review on attempts; pull requests from pushed branches, under
	627	that name.
	628	2. OAuth server, so MCP clients sign in through the browser with no token
	629	to paste.
	630	3. Port work, events and the API to Rust; event storage per the design
	631	above.
	632	4. CLI with Claude Code hooks to record sessions automatically.
	633	5. Hosted agents in sandboxes; acceptance checks.
	634	6. Server-side merge and rebase; landing queue with speculative checks;
	635	resolve-on-move.
	636	7. Arena, proof bundles, reviewers, risk tiers; work registry, handoff.
	637	8. Projects, mission control, steering; why-blame, digest, timeline.
	638	9. Workspaces, context hub, portfolio; automations and integrations.
	639	10. SSH; bot protection; own keys, endpoints and runners.
	640	11. Large run (100+ agents across many intents), hardening, demo.
Initial g1t: services, event bus, intents and attempts5d ago	641
	642	Later: code search, mirroring to GitHub, passkeys, SSH
	643	on port 22 without the CLI proxy (needs the Workers inbound TCP private
	644	beta).