# g1t plan
g1t is a git forge for agents, built on Cloudflare Workers and Artifacts for
the "Build the Next-Gen Git Platform on Cloudflare" competition.
- Submission closes **October 14, 2026, 11:59 PM PDT**: a 5–10 minute demo
video, this repository (MIT) and run instructions.
- Judging: 50% originality and quality of the prototype for agent-oriented
collaboration; 25% multi-agent concurrency, coordination, context
preservation, review and conflict handling; 25% ease of use.
## The point
**GitHub is where people keep code. g1t is where a team of agents ships it.**
Hosting git is table stakes, and g1t does it the way GitHub does: issues,
branches, pull requests, review, protected branches, people working by hand.
None of that is the selling point. The selling point is the layer above it,
which no forge has: **you hand g1t an outcome, and a fleet of agents converges
it onto `main`, coordinating with each other and with you, with every decision
on the record.**
Three things only g1t does, and every feature should serve one of them:
1. **Outcomes, not pull requests.** The unit people work in is "make onboarding
work offline", not branch #4012. A brief becomes a plan of issues with
dependencies; agents take them as they unblock; people steer the outcome
and see it converge. GitHub, Origin and Entire all stop at the pull request.
2. **Agents that work as a team.** Agents know what the others are doing, file
what they find instead of widening their change, ask and answer each other
through the forge, and defer to people. Many agents on one codebase without
a human refereeing collisions.
3. **`main` that only ever moves forward.** Every change lands through checks
in the combination it will live in (the merge queue), failures go back to the
agent that wrote them, and any line can answer "why is this here?"
### Against the others
| | GitHub | Cursor Origin | Entire | g1t |
| --- | --- | --- | --- | --- |
| Core idea | Code hosting with Copilot bolted on | A forge for Cursor's cloud agents | Store every agent session with the code | Agents converge an outcome onto `main` |
| Unit of work | Pull request | Pull request, stacked | Commit plus session | Outcome → plan → issues → pull requests |
| Agent context | In the Copilot app | In Cursor | In the repo, per commit | Per commit, plus why-blame on any line and what agents told each other |
| Many agents at once | Compare outputs by hand | Agents can review agents | Not the focus | Plan with dependencies, overlap awareness, coordination tools, queue |
| Landing | Merge queue (paid) | Stacks | Not the focus | Speculative queue testing combinations; failures return to their agent |
| Which agents | Copilot, some others | Cursor's | Any (CLI) | Hosted agents plus any MCP client |
Entire's insight, that the session belongs with the code, is one g1t shares
and already ships (sessions, why-blame). Origin's, that agents should live in
the forge, too. Neither coordinates a team of agents towards an outcome; that
is the gap g1t is built for.
## Product model
g1t keeps the two things every engineer already knows, issues and pull
requests, and changes the assumption underneath them. A forge built for
people expects a few changes in flight, each watched by its author. g1t
expects dozens of agents working at once across a project, each on its own
issue, all of which have to land on `main`. A person assigns an issue to
the g1t agent and chooses nothing else: not how many agents, and not which
model. An issue can still collect more than one pull request (a second
attempt, or someone's own agent alongside g1t's), and when it does the
issue records which one was taken.
| Concept | What it is |
| --- | --- |
| **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. |
| **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. |
| **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. |
| **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. |
| **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. |
Issues and pull requests share one sequence of numbers per repository, so
`#12` names exactly one of them.
Features that fall out of the model:
- **Why-blame.** Click a line and see the prompt and reasoning that produced
it, not only the commit.
- **Overlap radar.** Pull requests that touch the same files are flagged
while the agents are still working, and the agents are told.
- **Live lanes.** Watch every pull request progress in real time.
## Why issues and pull requests, not something new
An earlier version of this plan merged the two into one new object, an
"issue" holding "pull requests". That was wrong, for three reasons.
- **Issues come from everywhere.** People file them, agents file them, and
Sentry files them. Most are never worked on by whoever opened them. They
need their own life: labels, triage, discussion, closing as not planned.
- **"Which change did we take?" needs two objects.** When five agents each
propose a change, the answer has to be recorded somewhere other than the
five proposals. On g1t it is on the issue: `resolved by #14`.
- **Nobody should have to learn a word to use the product.** An engineer who
has used any forge can use g1t on the first day, and finds the agent
features where they would look for them.
What g1t adds to the familiar pair:
- **Several pull requests per issue is supported**, not an accident. It
is the exception, for a second attempt or a competing one, but when it
happens the issue's page lists them with their state, and merging one
closes the issue with that pull request recorded and the others marked
superseded.
- **A pull request can be part of the work.** Merging with "keep the issue
open" leaves the issue and its other pull requests alone.
- **Every pull request has a fork and a session.** See
[forks and branches](https://docs.g1t.sh/concepts/forks/).
- **Labels need no setup.** A repository starts with `bug`, `feature`,
`docs`, `chore` and `question`; any other name becomes a label the first
time it is used, so an integration can tag what it files.
- **The developer path is unchanged.** Push a branch, open a pull request
from it, get review, merge. Agents get a fork per pull request instead.
- **Both paths meet at `main`.** The same landing rules apply to a person's
pull request and an agent's.
## Converging on main
Twelve issues started together will finish at different times and touch
overlapping code. Getting them all into `main` without a person refereeing
is the hard part, and it is handled in four places.
1. **Before work starts: plan the overlap away.** A project is a graph of
issues. A planner agent can split a large goal into issues, predict
which files each will touch, and add a dependency where two would collide,
so one starts from the other's result instead of from `main`.
2. **While agents work: overlap radar.** Each pull request's changed files and
symbols are tracked as it pushes. When two pull requests from different issues
enter the same area, both agents are told what the other is doing there.
3. **When `main` moves: the author resolves.** Every open pull request is
trial-merged against the new `main`. A clean merge updates the pull request
silently. A conflict resumes that pull request's agent with its original
session and the incoming change, so the conflict is resolved by the agent
that wrote the code and still knows why.
4. **At landing: a speculative queue.** Approved pull requests enter the
repo's queue. g1t builds the combined states (`main`+A, `main`+A+B, …) and runs
their checks in parallel. Pull requests land in order as their combined state
passes; one that fails is ejected back to its agent and the states behind
it are rebuilt. `main` only ever receives a state that passed.
Landing can be fully automatic: a repo policy such as "checks pass and the
reviewer agent approves" merges without a person.
## Agents aware of each other
Each repo keeps a live **work registry**: for every running pull request, its
issue, a running summary of what it has done, and the files and symbols it
has touched or plans to touch. Agents use it through MCP tools; g1t also
acts on it without being asked.
- **Before starting.** When an issue is opened, or an agent is about to
begin a task, g1t searches open issues and running pull requests for the same
goal (by meaning, not wording) and for the same area of code. If a match
exists the agent is told who is on it and how far along, and chooses: join
as a deliberate racer, wait for the result, or drop the task. Duplicate
issues are offered for merging.
- **Finding out-of-scope work.** An agent that discovers something outside
its issue asks the registry who works there. If another pull request owns that
area, it **hands off**: a note, the relevant excerpt of its session, and
optionally commits the receiver can take. If nobody does, it opens a child
issue instead of widening its own change.
- **Asking.** An agent can put a question or a request to another pull request.
The receiver gets it at its next turn.
- **Waiting.** An agent that needs another pull request's result parks itself.
Its sandbox sleeps, spend stops, and it resumes from the new state when
that pull request merges.
- **Agents that do not cooperate.** For pushes from tools that never call
these tools, g1t compares the pushed change against running pull requests and
flags near-duplicates itself.
Every handoff, question and wait has a state (offered, accepted, declined,
done), appears in the timeline, and is visible to people. A handoff declined
twice, or two agents passing work back and forth, goes to the "needs you"
inbox.
## Review at scale
Cloudflare's brief asks "how do you review everything they produce?". With
hundreds of agents, a person cannot read every diff, so review is by
exception.
- **Evidence, not diffs.** Every pull request carries a proof bundle: checks run
and their output, a preview URL, a plain-language summary, and the
behaviour that changed.
- **Two agent reviewers.** One reviews the change against the issue. A
second is adversarial: it tries to break the change and reports what it
found.
- **Risk tiers.** Each change is scored from what it touches, how large it
is, and how the reviewers ruled. Low risk merges on policy; high risk goes
to a person with the evidence already assembled.
- **Trust is earned.** An agent's record on a path (merged, reverted, caught
by review) raises or lowers the tier its changes land in.
- **Sampling.** A share of auto-merged changes is sent to a person anyway,
to keep the policy honest.
## Rethinking the git primitives
- **No branches for agents.** A pull request is a fork; `main` is the only
long-lived line. There is nothing to name, clean up or go stale.
- **Projected main.** New pull requests start from `main` plus everything already
in the landing queue, so they are built on the state they will land on.
- **Structural merge.** The merge engine merges by syntax tree, not by line,
for supported languages. Two agents adding different functions to the same
file do not conflict.
- **Forkable sessions.** A session can be forked at any turn: the code as it
was at that moment plus the conversation up to it, continued with a
different instruction. Branching applies to the reasoning as well as the
code.
- **Provenance in history.** Every commit records its issue, session,
agent, model and cost, and is signed with a key issued to that pull request. The
history can be audited by machine.
## People in the loop
### Code that arrives from outside
People will keep pushing with plain git, their editor, or another tool. Every
push goes through g1t's git front end, so none of it bypasses the model.
- **A push to a branch becomes a pull request.** g1t adopts it with the pusher as
author. A reviewer agent writes the issue it appears to serve and offers
to attach it to an open issue it matches. From there it gets the same
checks, compare view and queue as agent work.
- **A push to `main` follows repo policy.** Protected: refused with a message
saying which ref to push to instead, so it enters the queue. Open: accepted
and treated as "`main` moved", which re-verifies the queue and triggers
resolve-on-move for every open pull request.
- **Context is an open format.** A commit trailer names the session that
produced it, so any tool can attach its transcript. Commits without one are
shown in why-blame as "pushed by a person, no session".
- **Approval rules.** Per repo and per path: merge automatically, require a
named person, or require a person when the change is large or the reviewer
agent is unsure.
### Joining work that is already running
- **Every session has a live page** that works on a phone: the transcript as
it streams, the current diff, check results.
- **Steer.** Send a message, pause, or redirect. Hosted agents receive it
immediately; a person's own Claude Code receives it at its next turn
through the CLI hooks.
- **Answer.** When an agent is blocked on a question, it appears in a "needs
you" inbox and as a notification. The answer resumes the agent.
- **Take over and hand back.** Check out the pull request's fork, commit by hand,
push, and let the agent continue from there.
### Planning by writing
- **Brief.** Write the outcome in prose on the site, or commit it as a
markdown file. A planner agent turns it into a project: issues, acceptance
checks, dependencies. The person edits the graph before anything starts.
- **Plan from their own agent.** The same operations are MCP tools, so a
person can plan in their own Claude Code session and create the project
from there.
- **The brief stays the source of truth.** Editing it later re-plans: new
issues are added, obsolete ones are closed.
### Seeing what moved
- **Project page.** The outcome, the issue graph coloured by state, and how
many acceptance checks pass now compared with when the project started.
- **Digest.** An agent-written summary per project and per person: what
merged, what is blocked on whom, which conflicts were resolved, what it
cost.
- **Timeline.** Every event (push, steer, check, conflict, merge) in order,
each linked to the session and the person or agent behind it.
## One session, any surface
A session belongs to g1t, not to the device it started on. The browser, a
phone and Claude Code are views of the same session.
- **Browser and phone.** The site is a responsive, installable web app with
push notifications. Everything a person does (brief, steer, answer,
approve, merge) works there.
- **Claude Code.** Through `mcp.g1t.sh` and the CLI hooks, a local session is
a g1t session: its transcript syncs as it runs and it appears in mission
control like any other.
- **Moving a session.** A local session can be sent to the cloud: a hosted
agent takes over the fork and the transcript and continues, so the laptop
can close. A hosted session can be pulled down: the CLI checks out the fork
and resumes it in local Claude Code with its history.
- **Limit.** A session running only on a laptop stops when the laptop does.
It can be steered between turns but not continued until it is moved or the
laptop is back.
## For people who do not write code
- **Documents are first-class.** Specs, guides, policies and decisions live
in repos as markdown, shown in a Docs view: rendered pages, edited in the
browser like a document, with inline comments. "Suggest a change" is an
pull request and "publish" is merge, without git vocabulary.
- **Document issues.** "Write the onboarding guide for the billing API" is
an issue. Its acceptance checks are a checklist judged by a reviewer agent
instead of commands. Agents draft and revise; people comment and approve.
- **Templates.** Product brief, RFC, decision record. A filled-in template is
a brief the planner can turn into a project.
- **Explain.** Ask about any repo, project or change in plain language and
get an answer with links to the code and sessions behind it.
- **Living documentation.** g1t generates "how this works" pages from the
code and keeps them current. When a merged change contradicts a document,
an issue opens to update it.
- **See it, don't read it.** Every pull request on a deployable repo gets a
preview URL (Workers Builds from the pull request's fork), so an approver clicks
through the result instead of reading a diff. Changes are also summarised
in plain language.
- **Roles.** Viewer, commenter, planner, approver: a person can plan and
approve work without ever cloning a repo.
## The macro view
The hierarchy above a single repo:
| Level | What it is |
| --- | --- |
| **Workspace** | A company or team: its people, repos, agents, budget and policies. |
| **Initiative** | A business outcome with an owner and measurable results, e.g. "move billing to usage-based pricing". Spans any number of repos. |
| **Outcome** | One deliverable inside an initiative: a brief and its graph of issues (shown as **Plan**). Called "project" before 2026-10-04; that name now means what [Projects](#projects) describes. |
| **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. |
How it feeds up, and what is built:
- **A workspace is the unit everything belongs to.** Repositories, people,
access tokens, and later projects, budgets and policies are the
workspace's, never a person's. An account owns nothing; its first step
after confirming its email is creating a workspace, and the site sends it
there from wherever it was going.
- **One namespace.** Usernames and workspaces share one set of names, as on
Docker Hub and npm. A username is reserved for its owner's workspace, so
`g1t.sh/<name>` never means two things.
- **The workspace page is the roll-up.** `g1t.sh/<workspace>` shows its
repositories with their open issues and pull requests, and the pull
requests in progress across all of them. Projects and initiatives will
roll up to the same page. Its own pages live under `/<workspace>/-/`
(people, access tokens, settings), which no repository can be named.
- **Workspace access tokens instead of service accounts.** A workspace has
tokens of its own, in the same table and code path as personal ones. One
acts as the workspace, with a member's rights in that workspace only,
records who made it and when it was last used, and keeps working when
that person leaves. CI, integrations and automations use these.
### Portfolio
One page answers "where is the business" across every initiative:
- **Health** per initiative: on track, at risk, or blocked, derived from
facts (checks passing, issues stalled, questions waiting on a person),
not self-reported.
- **Progress** as measurable results: acceptance checks passing, issues
merged out of planned, and the trend since the start.
- **Forecast** from actual throughput: at the current rate, when the
remaining issues land.
- **Spend** in tokens and dollars against a budget, per initiative.
- **Waiting on people**: every decision or approval a person owes, by name.
- **Roadmap**: initiatives laid out as now, next, later, with optional
time-boxed cycles for teams that work in sprints.
### Status without asking
- **Standup.** An agent writes a daily report per initiative and one for the
whole workspace: what merged, what changed direction, what is at risk and
why, what needs a person. Delivered by email or webhook.
- **Ask.** A question box over the full event log and all sessions: "what
happened on the billing migration since Monday?" answers with links to the
sessions and commits behind each claim.
### Long-running agents
Work that runs for days needs supervision that does not depend on someone
watching.
- **Checkpoints.** A long pull request reports milestones against its issue, so
progress is visible before anything merges.
- **Stall and drift detection.** A pull request with no meaningful progress, or
whose changes have wandered away from its issue, is flagged and can be
stopped or re-briefed automatically.
- **Budgets.** Hard limits on spend and time per pull request, project and
initiative.
### Context hub
Agents working across repos and days need context that outlives any one
session and reaches beyond the code. The context hub is one place an agent
asks, whatever the source.
| Source | What it holds | How it gets there |
| --- | --- | --- |
| **Memory** | Decisions, conventions, gotchas, facts about systems | Written by agents and people in g1t |
| **Code and sessions** | The repos, and the reasoning behind every change | Already in g1t |
| **Connected sources** | Jira and Linear tickets, Notion and Confluence pages, Google Drive documents, Slack threads, Sentry issues | Connectors, authorised per workspace |
How it behaves:
- **One search.** An agent asks a question and gets ranked results across
all sources, each labelled with where it came from, who wrote it, and how
fresh it is.
- **Connected sources stay where they are.** g1t indexes them for search and
fetches the current version when an agent opens one. The external system
remains the source of truth, and a link placed on an issue ("see
JIRA-482", a Notion URL) is pulled into the agent's starting context.
- **Permissions carry over.** A connector only exposes what the connecting
account can see, and a workspace admin chooses which spaces, projects or
channels are included.
- **External content is untrusted.** A ticket or page can contain text meant
to manipulate an agent. It is marked as reference material, never treated
as instructions.
- **Documentation is separate.** Context is what agents know; documentation
is what people read, and it is generated from context and code.
Memory is the part of the hub that g1t owns and agents write to:
- **Memory is written freely.** Any agent or person adds an entry with one
call: a decision, a convention, a gotcha, a fact about a system. No review
gate. Each entry records who wrote it, from which session, and when.
- **It is still a repository.** Each workspace has a memory repo in
Artifacts, so every write is a commit: versioned, attributable, and
revertible.
- **It is kept healthy by an agent.** A consolidation agent merges
duplicates, retires entries that newer ones contradict, and flags
conflicts it cannot settle. People can pin an entry (agents may not change
it), correct it, or retract it.
- **Agents read it.** Every session starts with the context relevant to its
issue, found by search, and can query more through MCP.
- **Updates are events.** A memory write or a change in a connected source
is an event, so "when context changes, update the affected docs" is an
automation, on by default.
- **It is scoped inside the workspace.** Some context applies to the whole
workspace, some to one initiative, project or repo, so an agent gets what
applies to its work.
- **It never crosses workspaces.** A workspace is the isolation boundary: its
context, sessions and private repos are invisible to every other
workspace, and an agent's token is bound to one workspace.
## Working in g1t
- **Mission control.** The signed-in home page: every running session, every
issue waiting on a decision, and what merged, across all repos.
- **Outcomes.** Group issues across repos toward one result and track how
many are open, racing, or merged. (What [Projects](#projects) means is
below.)
- **Steering.** Send a message to a running pull request, or to all pull requests on an
issue at once, without stopping them.
- **Automations.** Rules that start work without a person (next section).
## Automations and integrations
> **2026-10-03:** g1t's own `.g1t/automations` format was built and then set
> aside at the user's request ("let's just copy GitHub Actions on that for the
> time being"). Automation on g1t is GitHub Actions workflows in
> `.g1t/workflows/`; the format below is kept for later.
An automation is **when** an event happens, **if** conditions hold, **do**
something. They are defined as files in the repo (`.g1t/automations/`), the
way GitHub Actions workflows are, and can also be built in the UI.
### Events that can trigger one
| Source | Examples |
| --- | --- |
| Git | push, merge, check failed, `main` moved |
| g1t | issue opened, pull request stalled, context updated, handoff declined, budget reached |
| Time | cron schedule |
| Integrations | Sentry issue, PagerDuty incident, Linear or Jira ticket, Slack message or mention, GitHub issue, Stripe event |
| Anything else | a signed generic webhook, or an email to a per-repo address |
**Actions**: open an issue (optionally assigning N agents to it), message
a running pull request, update documentation, notify, call a
webhook, write back to the source system.
**Example: Sentry.** A new production error arrives. The automation opens an
issue labelled `bug`, with the stack trace, release and frequency in its
description. Why-blame
finds the session that wrote the failing line, so the fixing agent starts
with the original reasoning. When the fix merges, g1t comments on the Sentry
issue and resolves it.
### Rules every automation obeys
- **Deduplication.** The same Sentry issue firing 500 times maps to one
issue.
- **Limits.** Concurrency and budget caps per automation.
- **Loop protection.** Work started by an automation cannot retrigger the
same automation without a person in between.
- **External input is untrusted.** A webhook payload can contain text written
by an attacker. Agents started by external events run with reduced
permissions and cannot merge without the repo's approval rule passing.
**Checks** are the other half of what GitHub Actions does: build and test
commands declared in `.g1t/checks.yaml`, run in sandboxes on every pull request
and on every combined state in the landing queue.
Agents can also reach integrations directly: an agent definition lists MCP
servers (Sentry, Linear and so on) it may use while working.
## A repository that maintains itself
> **2026-10-04:** the user asked for Dependabot, GitHub Advanced Security and
> Vercel-style deployments, "so you're not having to maintain shit and you're
> just pushing up agents that are delivering work consistently".
GitHub reports problems and leaves the fix to you. In g1t, an agent opens an
issue for each problem, writes the fix, runs its checks, links a preview and
lands it through the queue. People only decide.
### Upkeep agents
- **Dependency updates.** A scheduled scan reads the lockfiles (npm, Cargo,
Go, pip), finds outdated and vulnerable packages and opens one issue per
update or group, assigned to g1t-agent. The agent upgrades the package,
fixes what the upgrade broke and lands it through the queue. A repository
sets how often it scans, which packages it groups and what lands without
review (`.g1t/upkeep.yml`, shaped like `dependabot.yml`).
- **Secret scanning.** Pushes are scanned for known token formats. A push
that adds a secret is refused with the file and line; one already in
history opens an issue to rotate it and remove it.
- **Vulnerability alerts.** Dependencies are matched against the OSV
database. Every alert links to the issue and pull request fixing it.
- **Code scanning.** A reviewer agent reads each pull request's diff for
security problems and leaves findings as review comments with a
suggested fix. Findings on `main` open issues.
- **A security page per repository** lists alerts, secrets and findings,
with the agent work on each, like GitHub's Security tab.
All of these are event sources for the existing issue → agent → checks →
queue pipeline; they need no new kind of work.
### Deployments
- **A preview for every pull request**, at
`<pr>--<repo>--<owner>.g1t.page`, linked on the pull request and updated
on each push. `main` deploys to `<repo>--<owner>.g1t.page`, and a
repository can add its own domain.
- **On g1t.page, not g1t.sh,** so customer code never shares cookies or an
origin with the site people sign in to.
- **Built on Workers for Platforms.** Each deployment is a user Worker in a
dispatch namespace; one dispatch Worker on `*.g1t.page` routes to it. The
build runs in the same runners as Actions. Static sites and Workers apps
first; container apps and databases later.
- **Agents use the preview.** The reviewer agent opens the preview in a
browser, takes screenshots of what changed and attaches them to its
review, so an approver sees the result without reading the diff.
- **Environments.** Preview, production and their secrets; deploy history
and one-click rollback.
- **Scale to zero.** An idle branch costs neither g1t nor the customer
anything: a Worker runs, and is billed, only while it answers a request.
A preview is deleted when its pull request closes or merges, and after
a set number of idle days. Container apps, later, sleep when idle.
- **Billed to the customer, never free.** The user (2026-10-04): "we
should not be giving any of this available for free". Every deployment
is metered per workspace (requests, CPU time, deployed apps, stored
data), priced at Cloudflare's cost + 20% like agent usage, and drawn
from prepaid credit. `FREE_WHILE_BUILDING` and the free model allowance
do not cover deployments: a workspace without credit cannot deploy, and
turning deployments on says so first.
- **Turning them on is a paid plan, the way Cloudflare's is.** "Including
things like them even enabling the feature should have that pay like
Cloudflare does." Enabling deployments for a workspace starts a monthly
fee that includes an allowance of requests, CPU time and deployed apps;
usage past it is billed per unit, as Workers for Platforms bills g1t.
The fee and allowance are the user's to set.
- **Recommended, off in one click.** Because enabling costs money, it is
never switched on without the workspace agreeing: new repositories
recommend it prominently. A repository can turn it off, keep only production, or
deploy somewhere else from its own workflows. Apps built for Cloudflare
(Workers, static assets, D1, KV, R2) deploy without configuration.
Later, toward GitLab's DevOps breadth: environment protection rules,
package and container registries, releases, container hosting.
## Projects
> **2026-10-04:** the user: "an extra dimension of Projects so it's not
> just repositories … where a lot of things can live", "very Vercel
> like", with dependencies across projects "the Platform Engineering /
> Port route", and "the repository is *part* of a project: you could be
> mirroring it from GitHub/GitLab/Bitbucket, or you could let us host it
> for you", with room for Mercurial or anything else later.
**A project is the thing you are building and running; a repository is
where some of its code lives.** Everything that is about running software
(deployments, environments, domains, secrets, dependencies, owners,
health, upkeep) belongs to the project. What is about the code itself
(branches, pull requests, review, merge rules) stays with the repository.
That split is what lets the code live anywhere.
### The model
| | What it is | Like |
| --- | --- | --- |
| **Workspace** | The company or team. Members, billing, plans, shared secrets. | Vercel team, GitLab group, GitHub org |
| **Group** | An optional named set of projects, one level: "Payments", "Mobile". For browsing, ownership and shared settings. | GitLab subgroup, Backstage system, Port domain |
| **Project** | One deployable thing: a site, an API, a worker, a library. Has exactly one **source**. | Vercel project, Port service, Backstage component |
| **Source** | Where its code is: a repository and a **root directory** in it. | Vercel's connected repo + root directory |
| **Dependency** | Project A uses project B: calls its API, consumes its package, reads its queue. | Port relations, Backstage `dependsOn` |
- **One project, one source; one repository, any number of projects.** A
project builds from exactly one place, which keeps it as simple as
Vercel's. A monorepo is several projects on one repository, each with
its own root directory (`apps/web`, `services/api`), and a push builds
only the projects whose root it touched. The common case stays 1:1, and
every existing repository gets a project of its own name when this
ships, so nobody has to set anything up.
- **Groups are for people; dependencies are for software.** Groups decide
where a project shows up and who owns it. Dependencies decide what
happens when one changes. Neither replaces the other, and a dependency
can cross groups.
### Sources: where the code lives
A source is an adapter behind one interface (`SourcePort`: clone URL,
branches, commits, pushes as events, pull requests if it has them):
| Source | Code lives | g1t gets pushes by | Pull requests |
| --- | --- | --- | --- |
| **Hosted on g1t** (today) | Artifacts | its own events | g1t's, with agents, the queue, review |
| **Mirrored** from GitHub, GitLab or Bitbucket | Both; g1t keeps a copy | the provider's webhook, then fetch | The provider's, read into g1t; agents open theirs there |
| **Connected, not copied** | The provider only | webhook | The provider's |
| **Later:** Mercurial, Perforce, a tarball upload | Behind the same port | per adapter | per adapter |
A mirrored or connected project still gets everything that is the
project's: previews on its pull requests (a status and a comment on
GitHub's), production on its default branch, secrets, dependencies,
upkeep agents. That is the on-ramp: a team keeps GitHub and gets g1t's
deployments and agents first, and moves the code later or never.
Bring-your-own-git is also why the project, not the repository, holds the
URL `g1t.sh/<workspace>/<project>`.
### What lives on a project
| | Today it is on | Moves to the project |
| --- | --- | --- |
| Deployments: production, previews, build settings, root directory, framework | The repository | Yes |
| Environments: production, preview, and custom ones (`staging`) with protection rules (required approvers, branch limits) | Nowhere yet | New, on the project |
| Domains: `<project>--<workspace>.g1t.page`, and custom domains | The repository's name | Yes |
| Secrets and variables | The repository | Yes. Workspace rows link to projects instead of repositories. A repository's workflows read the rows of its project (with several projects on one repository, the one marked as the repository's default). |
| Dependencies | Nowhere | New |
| Owners, on-call, links (docs, dashboards, runbooks) | Nowhere | New: the catalog's metadata |
| Health: scorecards (has an owner, CI passes, dependencies current, no open security alerts, deploys within N days) | Nowhere | New |
| Upkeep agents: dependency updates, security alerts | The plan | Scoped per project |
| Logs and analytics of the running app | Nowhere | New: requests, errors and CPU per environment, from Workers analytics |
| Branches, pull requests, review, merge rules, the queue, webhooks | The repository | Stay |
### Dependencies: why this gets powerful
Declared in the UI, or in the source as `.g1t/project.yml` (which wins
when present, as `catalog-info.yaml` does in Backstage):
```yaml
name: web
root: apps/web
dependsOn:
- project: api # calls its HTTP API
as: API_URL # its URL, per environment, as a variable
- project: ui-kit # consumes its package
```
What g1t does with them:
1. **Reference variables.** `API_URL` above resolves to `api`'s production
URL in production and to the matching preview in a preview, the way
Railway's `${{ api.URL }}` references work. No hard-coded URLs.
2. **Preview stacks.** A pull request on `api` gets its own preview, and
**Preview with dependents** builds `web`'s preview pointed at it, so a
reviewer clicks through the whole change across projects. A change that
spans repositories (one issue, one fork per repository) gets one stack.
3. **Release order.** Production deploys go out in dependency order; a
change set across projects lands through the queue together or not at
all.
4. **Impact on every pull request.** "Changes `api`; `web` and `mobile`
depend on it." Agents get the graph in their context: an agent
changing an API opens follow-up issues on the projects that call it,
and reviewers see what else could break.
5. **Upkeep across the graph.** A vulnerable package in `ui-kit` opens
issues, assigned to agents, on every project that consumes it.
6. **Scorecards turn into work.** A project failing a scorecard check
("no owner", "dependencies 90 days old") gets an issue an agent can fix.
That is the Port idea with the work done for you.
7. **The map.** A workspace's projects as a graph, coloured by health and
by what is deploying now.
### Pages
- `g1t.sh/<workspace>`: projects first (grouped, with health and
production status), then repositories.
- `g1t.sh/<workspace>/<project>`: overview (production, latest previews,
health, owners, dependencies both ways), **Deployments**,
**Environments**, **Secrets and variables**, **Logs**, **Settings**
(source, root directory, build, domains, groups, owners).
- A hosted repository keeps its code pages; from a project they are its
**Code** tab. A repository page lists the projects built from it.
### Services
- `services/projects` (new): projects, groups, sources, dependencies,
owners, scorecards. Events `project.created`, `project.updated`,
`dependency.changed`.
- `services/deployments`: keyed by project instead of repository.
- Secrets and variables: the scope becomes workspace → project.
- Sources: the hosted adapter wraps `services/repos`; a mirror adapter
per provider in `services/integrations`, which already holds those
connections.
### Build order
1. **Projects as the home of deployments and secrets**, 1:1 with every
existing repository: the service, the pages, deployments and secrets
moved to the project, `<project>--<workspace>.g1t.page`.
2. **Dependencies:** declared in the UI and `.g1t/project.yml`, reference
variables, impact on pull requests and in agents' context, the map.
3. **Preview stacks** and cross-project change sets.
4. **Monorepos:** several projects on one repository, each with a root
directory, building only what a push touched.
5. **Mirrored sources:** GitHub first, then GitLab and Bitbucket.
6. **Groups, owners, scorecards** feeding the upkeep agents.
7. **Environments** with protection rules; custom domains; logs.
**Step 1 shipped 2026-10-04:** `services/projects`; every repository a
project of its own name; the site projects-first (workspace page of
project cards, the project overview at `g1t.sh/<workspace>/<project>`, code
under `/code`, the sidebar and the New project flow); deployments keyed by
project and branch at `<project>-<workspace>.g1t.page` and
`<project>-git-<branch>-<workspace>.g1t.page`; secrets and variables owned
by the project.
### People and search
> **2026-10-04:** "pull up user profiles, using a /u/username prefix kinda
> like DockerHub … search for users if you search that explicitly, how
> GitHub has the aside for searching against filters … a significantly
> stronger implementation."
- **Profiles at `g1t.sh/u/<username>`**, apart from workspaces at
`g1t.sh/<workspace>`: who they are, their workspaces, recent work,
agents' sessions they steered.
- **Search with a filter sidebar:** Projects, Code, Issues, Pull requests,
Users, Workspaces, each with its count; filters by workspace, language,
state, author, agent, label, date; qualifiers in the query
(`user:`, `is:open`, `agent:g1t-agent`) as on GitHub. Typing `u/name`
searches people directly, as Docker Hub does.
1 and 2 serve the competition directly (multi-agent coordination across
projects is 25% of the score); 3 is the demo's best moment if time allows.
## Billing model
> **2026-10-04:** "Some things just require you to have a card on file …
> some things will be something you give us an initial amount of money
> per month just to activate, tons of things additionally will be usage
> based, some things will just be usage based only … at minimum a
> breakeven with Cloudflare costs, or in some cases a value add." Stripe
> moves to Flagon, Inc. (g1t.sh is its product). Proposed below; the
> prices are the user's to confirm.
### Four kinds of charge
Every feature is exactly one of these, and the Billing page says which:
| Kind | What the workspace does | Example |
| --- | --- | --- |
| **Free** | Nothing | Hosting code, issues, pull requests, review, the merge queue, bringing your own agent over MCP |
| **Card on file** | Adds a card; pays only for what it uses | Previews, g1t's agents, workflow minutes past the free ones |
| **Activation** | Turns a feature on for a monthly fee that includes an allowance; usage past it is metered | Production deployments, Security and quality |
| **Usage only** | Nothing up front; every unit is metered | Model tokens, build minutes, storage past the free amount |
A card is needed before anything that can cost money starts. Nothing is
ever switched on without the workspace choosing it.
### Postpaid, with spend limits
- **One Stripe customer and one subscription per workspace**, on Flagon,
Inc.'s account. Activations are licensed line items; every usage
dimension is a metered price backed by a Stripe Meter. Stripe invoices
monthly in arrears and charges the card on file; failed payments go
through Stripe's retries and emails, and g1t hears of them by webhook.
- **Spend limits instead of prepaid credit.** A workspace sets a monthly
limit overall and per feature (Vercel's spend management). g1t counts
usage as it happens and stops starting new paid work at the limit,
with a warning at 50%, 80% and 100%. Prepaid top-ups go away; promotions
(the free model allowance) become Stripe credit on the customer.
- **Usage reaches Stripe from billing alone.** Every service reports
usage to the billing service as it happens (it already records agent
runs and builds); billing batches them into Stripe meter events every
few minutes, idempotently by g1t's own ids, and keeps the ledger g1t's
pages show. Nothing else talks to Stripe.
### Scope: workspace, then projects
- A feature is turned on for the **workspace** (by an owner, with the
activation if it has one), then allowed for **all projects** or
**selected projects**.
- Every **project** can opt out on its own page. A project with nothing
to deploy (no Workers config, no build script, no `index.html`) is
detected, says so on its Deployments page, and never builds or costs
anything.
- Agents and workflows are allowed per project the same way, so a
workspace can keep spend to the projects that matter.
### Prices: what it costs us, passed through
> **2026-10-04, decided:** postpaid with spend limits, as Vercel and
> Cloudflare do; no per-seat price, ever ("fuck per-seat pricing").
> "If they're barely using them great, but if they're using the shit out
> of them that will cost me a ton, so that cost needs to move onto them."
**Every Cloudflare cost a workspace causes is metered to it.** Light use
fits in a small free allowance; past it, each unit is charged at
Cloudflare's price times a margin of at least 1.5, which pays for Stripe
(about 3%), shared overhead (the site, the API, D1) and g1t itself.
Cloudflare's prices (October 2026), and the cost per unit g1t meters:
| What g1t meters | Cloudflare's price | Cost to g1t per unit |
| --- | --- | --- |
| **Sandbox minute** (agents, checks, merge queue, workflow jobs, deploy builds), standard-1: ½ vCPU, 4 GiB, 8 GB | CPU $0.00002 / vCPU-s while busy; memory $0.0000025 / GiB-s and disk $0.00000007 / GB-s while running | ≤ $0.0012 / minute (CPU counted as busy throughout, since g1t cannot see it per sandbox) |
| **App request** (deployments) | Workers for Platforms: $0.30 / million past 20M | $0.30 / million |
| **App CPU** | $0.02 / million CPU-ms past 60M | $0.02 / million ms |
| **App** (a deployed script) | $0.02 / script-month past 1,000 | $0.02 / app-month |
| **Storage** (repositories, artifacts, caches) | Artifacts $0.50 / GB-month (billing starts 2026-10-14); KV $0.50 / GB-month | $0.50 / GB-month |
| **Git operation** (clone, fetch, push) | Artifacts $0.15 / 1,000 past 10,000 | $0.15 / 1,000 |
| **Model tokens** | The provider's price | As charged |
| Container egress, emails, the site's own requests | Small and shared | In the margin |
What a workspace pays:
| Meter | Free each month | Then | Margin | For comparison |
| --- | --- | --- | --- | --- |
| Sandbox minutes | 500 | $0.003 / minute | 2.5× | GitHub Actions $0.008 / minute (Linux 2-core); Vercel builds $0.0035 / CPU-minute |
| App requests | 1 million with Deployments | $0.50 / million | 1.7× | Vercel $0.60 / million invocations |
| App CPU | 3 million ms with Deployments | $0.04 / million ms | 2× | Vercel active CPU about $0.036 / million ms |
| Apps | 10 with Deployments | $0.05 / app-month | 2.5× | |
| Storage | 1 GB | $1.00 / GB-month | 2× | GitHub LFS $0.07 / GB, but repositories are free there |
| Git operations | 10,000 | $0.30 / 1,000 | 2× | |
| g1t's models | | Cost + 20% | 1.2× | The provider's own price |
| Your own model provider | | $0.10 / run, plus its sandbox minutes | | |
| **Deployments** activation | | $5 / month, with the allowances above | covers Workers for Platforms' $25 / month across workspaces | Vercel Pro $20 per seat |
| **Security and quality** activation (later) | | $10 / month; fixes as agent usage | | GitHub Advanced Security $49 per committer |
A workspace that uses g1t lightly (a few agent runs, a small site)
pays nothing or its activation; a workspace running agents all day pays
for the sandboxes and models those agents use, with g1t's margin on
each. Nothing in a workspace's bill is subsidised by another's.
### Build order
1. Stripe customer per workspace and card on file (Checkout in setup
mode), webhooks (invoice paid and failed, subscription changes,
payment method changes), the Billing page rebuilt around the four
kinds.
2. One subscription per workspace with activations as items; Deployments
moves onto it.
3. Meters for each usage dimension above, fed from billing's ledger:
every sandbox reports how long it ran when it stops (agents, checks,
the queue, workflow jobs and deploy builds alike); deployments report
requests, CPU and apps; repos report storage and git operations. Spend
limits and their warnings; prepaid credit retired.
4. Per-workspace allow-lists of projects for each feature, and per-project
opt-out; "nothing to deploy" detection.
5. Turn off FREE_WHILE_BUILDING when the user says so. **Done 2026-10-05.**
Shipped by 2026-10-05: sandbox seconds for every sandbox; the price book
and its keeper (runs settled to AI Gateway's price every 15 minutes;
Container and Workers costs checked against Cloudflare's billable usage
and container analytics daily, with a public change log on
g1t.sh/pricing); usage limits by trust with automatic payment near the
limit; app traffic counted toward limits as it happens; billing accounts,
terms and enterprises; free mode off, syntaqx comped.
Still to build, in order: Stripe card-on-file without a payment (setup
mode) and webhooks; month-end invoices for postpaid usage (and one
invoice per enterprise); the subscription with activations as items;
storage and git-operation meters; limit warnings by email at 50/80/100%;
self-serve enterprise management for enterprise owners.
### Accounts, terms and enterprises
Every workspace is paid for by a billing account: its own (`ws_<slug>`)
or an enterprise's (`ent_…`), which pays for several workspaces with one
limit, one set of terms and, once invoices exist, one bill, as GitHub
Enterprise does. Terms are standard, comped (nothing charged, usage still
recorded at cost, paid features on) or custom (a discount, its own
ceiling, an end date). g1t staff manage them in **sudo.g1t.sh**, a
separate Worker behind Cloudflare Access that also verifies the Access
token itself and allows only listed staff emails; every change is kept
with who made it and why.
### Limits: stop non-payers, never payers
The limit is on usage not yet paid for, counted at cost to g1t or charge,
whichever is more: $3 before any live payment, then twice what has been
paid ($25 to $1,000), or what staff set. A workspace with a card on file
is charged automatically near its limit, which both pays what it owes and
raises the limit, so paying users are never stopped. A declined card
stops work until paid. The owner's own spend limit always means stop.
Test-mode payments never lower exposure or raise trust.
## Agents and models
### Defining an agent
An agent is a file (`.g1t/agents/<name>.md`, or in the workspace library):
instructions, the harness and model to run, the tools and MCP servers it may
use, its sandbox image, permissions and budget. Agents take roles: planner,
implementer, reviewer, conflict resolver, documenter, memory consolidator.
Each role has a default that a repo can replace.
### Where it runs, and on whose model
| Option | How it works | Fits |
| --- | --- | --- |
| Hosted, g1t's model | g1t runs the sandbox and bills usage | Getting started; no keys to manage |
| Hosted, your API key | Same sandbox, your Anthropic, OpenAI or Google key | Teams with existing contracts |
| Hosted, your endpoint | Any OpenAI-compatible URL: Bedrock, Vertex, Azure, a self-hosted model | Private or fine-tuned models |
| Your runner | A g1t runner daemon on your own machines picks up pull requests | Code or models that may not leave your network |
| Your own session | Local Claude Code, Cursor or any MCP client joins through `mcp.g1t.sh` | Individuals; subscription plans |
Decisions behind this:
- **g1t does not build its own agent loop.** It runs existing harnesses
(Claude Code first, through its headless mode) behind a small runner
contract: a container image, an entry command, and session events reported
through the CLI. Other harnesses plug in by meeting the contract.
- **All hosted model traffic goes through Cloudflare AI Gateway.** That gives
one place for spend tracking, budgets, rate limits, fallback and logs,
whichever provider or endpoint is behind it.
- **Nobody picks a model.** A person assigns work to `g1t-agent`, as they
would assign an issue to Copilot, and g1t routes it. Today the kind of
work decides (implementing, reviewing, catching up), from one setting on
the runner, and each request is tagged at the gateway with that kind, the
repository and the pull request. The session records which model ran.
The gateway's own dynamic routes cannot make the choice yet: they work
only on its OpenAI-compatible endpoint, and the harness speaks
Anthropic's.
- **Subscriptions stay local.** A Claude subscription cannot be used by a
hosted sandbox; it needs an API key. People on subscriptions use their own
Claude Code session, which is a full participant.
- **The workspace pays.** A workspace buys credit by card and each agent
run deducts what the model cost plus a margin. The billing service asks
nothing of the others: the runner asks it before starting a sandbox and
is refused when there is no credit, and the sandbox reports what its run
cost with a token only it holds. Where no card processor is configured
nothing is charged and agents stay limited to listed accounts.
- **Keys are secrets.** Stored in Cloudflare Secrets Store, injected into the
sandbox for one pull request, never shown again.
### Seeing a pull request through
Assigning an issue is the only thing a person does until there is something
to merge. A pull request made by a g1t agent goes through checks, a review
by another agent, revision when either finds something, and catching up
when `main` moves, without anyone pressing a button. It ends as ready to
merge, or as "needs you" with the reason: the checks still fail after two
revisions, a review could not be written, or a conflict could not be
resolved.
The work service decides the next step from the pull request's state and
claims it in one statement, so a step is taken once. The runner asks on
every event that could change the answer (ready, pushed, checks finished,
review finished, `main` moved), and on a five-minute sweep for anything
missed, and carries the step out in a sandbox.
A pull request does not have to be up to date with `main` to merge,
unless the repository's settings require it, as on GitHub. Merging one that
is behind brings it up to date first (a clean merge needs no model; an
agent resolves a conflict) and lands it when that push arrives. With the
requirement on, catching up is a step of its own and the checks run again
on the result.
Each repository sets its own rules, on one settings page: whether its
default branch takes pushes at all, how many approvals a merge needs and
whether an agent's counts, whether failed checks can be overridden, whether
a second agent reviews, and how often an agent is sent back before a person
is asked. A g1t agent's pull request follows the same rules as anyone's.
Pushes to a protected branch are refused in the git front end, with the
reason shown by git beside the branch.
Merging is a person's decision unless the repository says otherwise. With
"merge automatically when ready" turned on in its settings, a ready pull
request lands by itself, attributed to `g1t`. That is the whole path from
an assigned issue to a commit on `main` with nobody in between. Required
human approval per path, and risk tiers, are still to come.
### Choosing the right agent automatically
Because several agents can work on the same issue, every issue with more
than one pull request is an evaluation on real work. g1t records, per repo and per kind of issue, each
agent's win rate, cost and time. That produces a leaderboard, and a routing
policy: send each new issue to the agent that wins that kind most often,
start with the cheapest that is good enough, and escalate to a stronger one
when checks fail.
## What GitHub ships today, and where g1t differs
GitHub's Agent HQ and Copilot app give each agent session its own git
worktree and branch, list sessions in a mission-control view grouped by
project, and let a task be assigned to several agents so their output can be
compared. Underneath, the unit of work is still a branch and a pull request.
| | GitHub | g1t |
| --- | --- | --- |
| 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 |
| Agent context | Lives in the app's session view | Stored with the repository and linked from each commit (why-blame) |
| 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 |
| Collisions between agents | Found as merge conflicts at the end | Flagged during the work (overlap radar) |
| Landing changes | One pull request at a time | A merge queue that lands the chosen one and closes the rest as superseded |
| Which agents | Those offered through a Copilot subscription | Any MCP client, plus hosted agents |
## How agents connect
1. **Bring your own agent.** A remote MCP server at `mcp.g1t.sh` lets Claude
Code (or any MCP client) list issues, claim one, get a clone URL and
token, report progress and submit. Adding it is one command; sign-in is a
browser OAuth flow with no token to paste. The `g1t` CLI installs Claude
Code hooks that upload the session transcript as the agent works.
2. **g1t agents.** Assign an issue to g1t's own agent, or many issues at
once, each to an agent of its own. g1t starts a sandbox for each
(Cloudflare Containers), running a coding agent headless against its
own pull request and fork.
3. **API and CLI.** Everything above is available at `api.g1t.sh` and
through `g1t`.
## Public surfaces
| Host | What it serves |
| --- | --- |
| `g1t.sh` | The site, git over HTTPS, git over SSH |
| `api.g1t.sh` | REST API, with no version in its paths, 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 |
| `mcp.g1t.sh` | Remote MCP server over streamable HTTP |
g1t is its own OAuth 2.1 authorization server: authorization code with PKCE,
dynamic client registration that stores nothing (a client id encodes its
own registration, so the open endpoint cannot be used to fill a database),
discovery metadata and rotating refresh tokens. Still to come: scopes
per resource (`repo:read`, `repo:write`, `issue:write`, `pull:write`).
MCP clients, the CLI (device flow) and third-party apps all use it. Access
tokens and SSH keys remain for git itself.
## Architecture
| Component | Language | Runs on | Responsibility |
| --- | --- | --- | --- |
| `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. |
| `services/identity` | Rust | Worker + D1 | Accounts, workspaces and memberships, sessions, SSH keys, access tokens, device sign-in, OAuth codes and grants |
| `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. |
| `services/work` | Rust | Worker + D1 | Issues, pull requests, comments, sessions; later a Durable Object per repo for the landing queue and live state |
| `services/billing` | Rust | Worker + D1 + Stripe | Each workspace's agent credit: payments, the ledger of every run, and the gate on starting one |
| `services/events` | Rust | Worker + Queues + D1 | The event bus: durable log, and one queue per subscribing service |
| `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 |
| `apps/web` | TypeScript | Worker | Server-rendered site. Holds no data; calls services over RPC. |
| `apps/docs` | TypeScript | Worker (static) | Documentation and the API explorer |
| `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 |
| `crates/sshd` | Rust | Container | Git over SSH, bridged to Artifacts |
| `crates/merged` | Rust | Container | Trial merges, conflict matrix, landing merges (needs real git; the Artifacts binding is read-only) |
| `crates/core` | Rust | native and WASM | pkt-line, packfile and diff code shared by the above and by the Worker |
| `crates/g1t` | Rust | user's machine | CLI: auth, SSH proxy, Claude Code hooks, issues and pull requests |
Storage: Artifacts for repositories (one fork per pull request), D1 for accounts
and metadata, R2 for session transcripts and logs, Durable Object SQLite for
per-repo coordination state.
How the services fit together:
- **Each service is its own Worker with its own database.** It deploys,
scales and fails on its own. Callers reach it through a typed RPC binding
to the interface in `packages/contracts`.
- **Expected failures are values.** Every call returns a `Result`, so "not
found" or "forbidden" crosses a service boundary as data.
- **Side effects travel as events.** A service publishes what happened
(`git.push`, `issue.opened`, `pull.merged`, …) to the bus and does not
call other services to react. Each subscriber consumes from its own queue.
Timelines, webhooks and automations read the same stream, which is what
lets something like GitHub Actions be built on top.
- **Every read takes the viewer.** Authorization is decided inside the
service that owns the data, not by its callers.
The Workers runtime scales request handling on its own, so the edge layer
stays in TypeScript. Rust is used where there is real computation or a real
protocol to implement.
## Languages
The site is TypeScript. Everything behind it is Rust, compiled to
WebAssembly for Workers and natively for containers and the CLI. Identity, repos, work, events and the API are all Rust. The one exception
is the Worker that starts sandboxes, because Cloudflare's Containers
library is TypeScript. Rust services speak a
small JSON protocol over service bindings (`POST /rpc/<method>`), with the
types in `crates/contracts`.
## Identifiers
Every id is a [TypeID](https://github.com/jetify-com/typeid): a prefix naming
the kind of thing, then a UUIDv7 in lowercase base32, such as
`pr_01jb2k7x9hfq0b3zj0f5s2m8ra`.
- The prefix makes an id self-describing and stops ids of different kinds
being mixed up.
- Ids sort by creation time as plain strings. In SQLite (D1 and Durable
Objects) that keeps inserts at the end of the primary-key index instead of
scattering them, and gives time-ordered paging for free.
- The suffix decodes to a standard UUIDv7 for any system that wants one.
- Ids are made by the service that creates the record, not by the database,
so they work across services and can be assigned before a write.
## Events at scale, and audit
The current event log is a single D1 database. That is fine for a
prototype and wrong for the target: D1 is one writer and 10 GB. The design
for volume splits storage by how the data is read.
| Tier | Store | Holds | Read by |
| --- | --- | --- | --- |
| Hot | A Durable Object per repository, with SQLite | Recent events for that repo | Timelines, live pages over WebSocket |
| Complete | Cloudflare Pipelines into R2 as Apache Iceberg | Every event, forever, partitioned by day and workspace | Analytics, standups, "ask", export |
| Audit | The same R2 store, under object lock | Who did what, from where, with which credential | Compliance, investigation |
- **No single hot database.** Each repository's recent events live with that
repository, so load spreads across as many objects as there are repos.
- **The complete record is files, not rows.** Iceberg on R2 has no practical
size limit and is queried with SQL.
- **Audit is a property of every event.** The envelope carries the actor
(person, agent, token or system), the credential used, the request id and
the source address. Audit entries for a workspace are hash-chained, so a
removed or altered entry is detectable, and are written under a retention
lock.
- **Delivery is at least once.** Consumers are idempotent on the event id.
## Accounts and forge basics
- Registration with email verification, sign-in, forgot password (Cloudflare
Email Sending), Turnstile on public forms.
- GitHub sign-in, SSH keys, access tokens, active sessions.
- Profiles, public and private repositories, repository search (D1 full-text).
- Rendered README, syntax highlighting, commit history, diffs.
## Built on Cloudflare
| Need | Product |
| --- | --- |
| Repositories; a fork per pull request; data residency per workspace | Artifacts (forks, jurisdictions) |
| Reacting to pushes | Artifacts event subscriptions on Queues |
| Preview URL per pull request; deploy on merge | Workers for Platforms on `g1t.page` |
| Site, API, MCP, git front end | Workers |
| Per-repo coordination, live updates | Durable Objects |
| Pull request lifecycles, automations | Workflows, Cron Triggers |
| Agent sandboxes, SSH server, merge engine | Sandbox SDK and Containers |
| Fast starts on large repos | ArtifactFS |
| Model traffic, spend, budgets | AI Gateway |
| Summaries, embeddings | Workers AI |
| Context hub search | Vectorize |
| Accounts and metadata | D1 |
| Transcripts and logs | R2 |
| Email, bot protection, keys | Email Sending, Turnstile, Secrets Store |
## The submission
- **g1t is built on g1t.** This repository is hosted on g1t.sh, its features
are opened as issues and built by racing agents, and it deploys from
Artifacts through Workers Builds. The history is the proof.
- **The demo follows one story.** A brief becomes a project; twelve issues
fan out to dozens of agents; agents notice each other, hand off, and
resolve a conflict; reviewers triage; the queue lands everything on
`main`; why-blame explains a line; the portfolio shows where it all
stands. Then the same thing at a thousand agents.
- **Judges can try it in a minute.** Open registration on g1t.sh, one-click
import of a GitHub repo, one command to connect Claude Code, a seeded demo
workspace, and a single deploy command for running their own copy.
- **The formats are open.** The commit trailers, session format and runner
contract are published so other tools can interoperate.
## Build order
What is left is ordered by how much it shows the point above, not by forge
parity. Forge basics are done well enough; each item below should make the
demo's story stronger.
Done from this list: the outcome page (a plan's issues as a live graph with
cost and a feed of what happened), coordination you can see (agents' issues
and comments stand out in the feed; agents hold g1t's tools through a token
scoped to one repository), steering a running agent (messages delivered
between steps, and at the end), and recording sessions from anyone's own
Claude Code (`curl -fsSL https://g1t.sh/install/claude.sh | sh`). Integrations are
in: a workspace's own model provider (Anthropic or any Anthropic-compatible
endpoint, reached through a model proxy so no sandbox holds a key, for a
flat orchestration fee), alerts from Sentry, Datadog and signed webhooks
that open one issue per problem and can start an agent, and Jira and Linear
tickets that agents read, people import, and that hear back. Racing a
set number of agents on one issue is dropped: choosing how many agents to
use is not something people should have to do.
1. ~~**Handoffs and questions between agents** as states on the outcome
page.~~ Done: questions and handoffs show as waiting, read, answered,
taken on or declined; since 2026-10-03 an agent asked while it is not at
work is woken to answer, where before the question waited forever.
2. **Upkeep agents** (above): dependency updates, secret scanning,
vulnerability alerts, code scanning, the security page. No new
infrastructure.
3. **Deployments on `g1t.page`** (above): previews per pull request,
production on merge, the reviewer agent checking the preview.
4. **The large run, building 2 and 3.** About 20–30 issues on g1t itself,
built by agents and landed through the queue, for the video: g1t built
on g1t.
5. **Polish for judges trying it in a minute:** a seeded demo workspace, the
empty states, and the first-run path from sign-up to an outcome landing.
Earlier items still open, after those:
1. Deleting a branch once its pull request merges; approval rules per
path; risk tiers.
2. Scopes on OAuth grants and access tokens.
3. Event storage per the design above: per-repo hot log, Iceberg on R2,
hash-chained audit.
4. CLI with Claude Code hooks to record sessions automatically.
5. Reviewing and catching up automatically, by policy; required reviews;
risk tiers.
6. Compare view, proof bundles; handoff between agents.
7. Projects, mission control, steering; why-blame, digest, timeline.
8. Context hub, portfolio; automations and integrations (Sentry first).
9. SSH; bot protection; own keys, endpoints and runners.
10. Large run (100+ agents across many issues), hardening, demo.
Later: code search, mirroring to GitHub, passkeys, SSH
on port 22 without the CLI proxy (needs the Workers inbound TCP private
beta).