| 1 | # g1t |
| 2 | |
| 3 | **Git tracks changes. g1t coordinates change.** |
| 4 | |
| 5 | g1t is a git platform built for teams whose code is written by people and |
| 6 | their coding agents at the same time. You keep your own harness (Claude |
| 7 | Code, Codex, Cursor, Copilot or anything that speaks MCP); g1t is the |
| 8 | place they all work through. It hosts the repositories, shows who and what |
| 9 | is working on each project right now, keeps parallel work from colliding, |
| 10 | tests changes together before they land, deploys them, and remembers why |
| 11 | each change was made. |
| 12 | |
| 13 | g1t is MIT-licensed and in alpha. Use it on [g1t.sh](https://g1t.sh) (anyone |
| 14 | can sign up), or run it yourself. It runs on Cloudflare Workers, with |
| 15 | repositories in Cloudflare Artifacts, and the core runs in Docker. |
| 16 | |
| 17 | - Site: <https://g1t.sh> |
| 18 | - Docs: <https://docs.g1t.sh> |
| 19 | - API: <https://api.g1t.sh> · MCP: <https://mcp.g1t.sh> |
| 20 | - Limits you can hit today: [docs.g1t.sh/about/limitations](https://docs.g1t.sh/about/limitations/) |
| 21 | |
| 22 | ## Try it |
| 23 | |
| 24 | ```sh |
| 25 | # 1. Sign up and make a workspace at https://g1t.sh/register. |
| 26 | |
| 27 | # 2. Install the g1t CLI (Windows: irm https://g1t.sh/install.ps1 | iex). |
| 28 | curl -fsSL https://g1t.sh/install | sh |
| 29 | g1t auth login |
| 30 | |
| 31 | # 3. Install g1t's Claude Code plugin. It adds g1t's MCP server and records |
| 32 | # your sessions; run /mcp in Claude Code and sign plugin:g1t:g1t in. |
| 33 | claude plugin marketplace add https://g1t.sh/flagon-io/g1t.git |
| 34 | claude plugin install g1t@g1t |
| 35 | ``` |
| 36 | |
| 37 | Then work as you always do in a g1t repository: the session shows on the |
| 38 | project's page as it runs. [Getting started](https://docs.g1t.sh/quickstart/) |
| 39 | walks through it in full, and [Connect a coding agent](https://docs.g1t.sh/guides/bring-your-own-agent/) |
| 40 | sets up other harnesses. An assistant can do it for you from |
| 41 | <https://g1t.sh/llms.txt>. |
| 42 | |
| 43 | ## What's in it |
| 44 | |
| 45 | ### Coordinating agents |
| 46 | |
| 47 | - **Sessions.** Every run of a coding agent is recorded as it works: its |
| 48 | prompts, tool calls, subagents, branches, commits and pull requests. Work |
| 49 | that is not an issue yet is a session titled by what it is for. The |
| 50 | [Claude Code plugin](https://docs.g1t.sh/guides/claude-code-plugin/) does |
| 51 | it with no setup; any harness can with the CLI or MCP. |
| 52 | - **Live now.** A project's page shows who is working on it right now and |
| 53 | with which harness, grouped by issue, pull request or branch. |
| 54 | - **Claims.** Advisory, expiring claims on issues, so two agents don't do the |
| 55 | same work, with hand-offs between sessions and coordination events |
| 56 | (`g1t work events --follow`, or over MCP) when work overlaps. |
| 57 | - **Integration.** The merge queue tests changes together before they land, |
| 58 | finds which change broke a combination by bisecting, and sends the failure |
| 59 | to the session responsible. |
| 60 | - **Why-blame and decisions.** `g1t why file:line` answers why code is as it |
| 61 | is: its commit, pull request, issue, the decisions recorded along the way, |
| 62 | and the sessions behind it. |
| 63 | - **Ask g1t.** Ask about your work from any page, or by messaging @g1t. It |
| 64 | answers with your workspace's own AI provider and reads g1t as you. |
| 65 | |
| 66 | ### Code |
| 67 | |
| 68 | - Public and private repositories, git over HTTPS, creating a repository by |
| 69 | pushing to it, GitHub import (every branch and tag, and issues). |
| 70 | - Issues, milestones, labels, pull requests, line comments and reviews. |
| 71 | - Required checks, rulesets, CODEOWNERS and the merge queue. |
| 72 | - Workflows from `.g1t/workflows` in GitHub Actions syntax, on g1t's Linux |
| 73 | runners or self-hosted ones on Linux, macOS and Windows, with caches, |
| 74 | secrets and variables. |
| 75 | - Packages: npm, Cargo, Composer, Maven, NuGet, RubyGems, Go modules and |
| 76 | container images. |
| 77 | - Secret push protection, history scanning and dependency update pull |
| 78 | requests. |
| 79 | |
| 80 | ### Deployments and observability |
| 81 | |
| 82 | - A preview of every pull request on `g1t.page`, production on merge, custom |
| 83 | domains. Static sites, Workers and containers, chosen from the project. |
| 84 | - Logs, traces, metrics and errors from your apps over OpenTelemetry. |
| 85 | |
| 86 | ### The workspace |
| 87 | |
| 88 | - Chat: channels, direct messages and threads, live. |
| 89 | - Artifacts: docs written together, live, with comments, suggestions and |
| 90 | history. |
| 91 | - Home, notifications with browser push, people and teams, roles, invites. |
| 92 | - A desktop app for Windows and Linux that can also be a runner for your |
| 93 | workspace, and an Android app in testing ([g1t.sh/download](https://g1t.sh/download)). |
| 94 | |
| 95 | ### Extend |
| 96 | |
| 97 | - REST API, OpenAPI, an MCP server, webhooks and the `g1t` CLI, all from one |
| 98 | set of operations. |
| 99 | - Integrations: your own AI providers, Sentry, Datadog and webhook alerts, |
| 100 | Jira and Linear. |
| 101 | - Usage billing with no seats and a public price book. |
| 102 | |
| 103 | ## Layout |
| 104 | |
| 105 | | Path | What it is | Language | |
| 106 | | --- | --- | --- | |
| 107 | | `apps/web` | The site: server-rendered React on a Worker. Holds no data. | TypeScript | |
| 108 | | `apps/docs` | The documentation site, with the API explorer. | TypeScript | |
| 109 | | `apps/api` | REST API and MCP server. | Rust | |
| 110 | | `apps/desktop` | The desktop app (Tauri), with a runner inside. | Rust, TypeScript | |
| 111 | | `apps/mobile` | The phone app (Expo). | TypeScript | |
| 112 | | `apps/status` | The status page at `status.g1t.sh`. | TypeScript | |
| 113 | | `apps/sudo` | g1t's own staff console. | TypeScript | |
| 114 | | `services/identity` | Accounts, workspaces, sessions, keys, tokens and invites. | Rust | |
| 115 | | `services/repos` | Repository registry, contents, forks, diffs, landing, git over HTTPS. | Rust | |
| 116 | | `services/work` | Issues, pull requests, reviews, check runs, agent sessions, claims and the merge queue. | Rust | |
| 117 | | `services/events` | The event bus and its log. | Rust | |
| 118 | | `services/search` | Site-wide search and Explore. | Rust | |
| 119 | | `services/billing` | Usage, the price book, limits, invoices and payments. | Rust | |
| 120 | | `services/actions` | Workflows, runs, caches and self-hosted runners. | Rust | |
| 121 | | `services/security` | Push protection findings, history scanning and dependency updates. | Rust | |
| 122 | | `services/integrations` | AI providers, Ask, alerts, trackers and the GitHub App. | Rust | |
| 123 | | `services/webhooks` | Webhook deliveries. | Rust | |
| 124 | | `services/packages` | The package registries and container images. | Rust | |
| 125 | | `services/runner` | Starts sandboxes for workflow jobs, builds and the merge queue. | TypeScript | |
| 126 | | `services/projects` | Projects: what a workspace builds and runs, and where its code lives. | TypeScript | |
| 127 | | `services/deployments` | Builds, previews and production on `g1t.page`. | TypeScript | |
| 128 | | `services/pages` | Serves every app deployed on `g1t.page`, and custom domains. | TypeScript | |
| 129 | | `services/telemetry` | Observability: OpenTelemetry ingest, logs, traces, metrics and errors. | TypeScript | |
| 130 | | `services/chat` | Channels, direct messages, threads and their live sockets. | TypeScript | |
| 131 | | `services/artifacts` | Docs: their spaces, sharing and live editing. | TypeScript | |
| 132 | | `services/notify` | Notifications: each person's feed, live counts and browser push. | TypeScript | |
| 133 | | `services/og` | Social cards at `og.g1t.sh`: a PNG per page, showing only what anyone may see. | TypeScript | |
| 134 | | `crates/g1t` | The `g1t` command line. | Rust | |
| 135 | | `crates/runner` | The program inside a sandbox, and the self-hosted runner: runs a workflow job or a build and reports back. | Rust | |
| 136 | | `crates/contracts` | Types and service interfaces for the Rust services. | Rust | |
| 137 | | `crates/kit` | Plumbing shared by Rust services on Workers. | Rust | |
| 138 | | `crates/rules` | The rules engine for rulesets on branches and tags. | Rust | |
| 139 | | `crates/blobstore` | Object storage: R2 on Cloudflare, any S3-compatible store self-hosted. | Rust | |
| 140 | | `crates/actions` | Reads workflows and evaluates their expressions. | Rust | |
| 141 | | `crates/scan` | Secret and lockfile scanning, shared by services. | Rust | |
| 142 | | `crates/secrets` | Secrets at rest and signatures. | Rust | |
| 143 | | `crates/sshd` | Git over SSH, bridged to Cloudflare Artifacts. Not deployed. | Rust | |
| 144 | | `packages/contracts` | The same interfaces for TypeScript callers. | TypeScript | |
| 145 | | `packages/theme` | Design tokens and the logo, shared by the site and the docs. | CSS | |
| 146 | | `plugins/claude-code` | g1t's Claude Code plugin: hooks, skills and commands. | JavaScript | |
| 147 | | `plugins/other-harnesses` | The AGENTS.md snippet for Codex, Cursor and other harnesses. | Markdown | |
| 148 | | `deploy` | `stack.jsonc`, every deployable part and its resources; `self-host`, the Docker Compose version. | JSON, Docker Compose | |
| 149 | |
| 150 | Each service is its own Worker, and each one that keeps data has its own |
| 151 | database. They call each other through service bindings and react to each |
| 152 | other through events. The core services are written in Rust; the web apps |
| 153 | and the rest of the Workers in TypeScript. |
| 154 | |
| 155 | ## Run your own |
| 156 | |
| 157 | ### On your own machine |
| 158 | |
| 159 | The core forge runs in Docker, with no Cloudflare account: |
| 160 | |
| 161 | ```sh |
| 162 | docker compose -f deploy/self-host/docker-compose.yml up --build |
| 163 | ``` |
| 164 | |
| 165 | Then open <http://localhost:8787> and sign up. The confirmation mail is in |
| 166 | Mailpit at <http://localhost:8025>. Repositories, push and clone, issues, |
| 167 | pull requests, code browsing, search, webhooks and observability work, and |
| 168 | the API and MCP server answer at <http://localhost:8789>; packages and |
| 169 | container images are kept in the bundled S3-compatible store, RustFS. |
| 170 | Deployments and billing are off, and the merge queue can't test or land |
| 171 | pull requests without g1t's runner. |
| 172 | [Run g1t yourself](https://docs.g1t.sh/guides/self-hosting/) says what works, |
| 173 | and [how a self-hosted g1t runs](https://docs.g1t.sh/guides/self-hosting-architecture/) |
| 174 | what runs inside it. |
| 175 | |
| 176 | ### On Cloudflare |
| 177 | |
| 178 | You need a Cloudflare account on the Workers Paid plan (Cloudflare |
| 179 | Artifacts, where repositories are stored, requires it), Node 24 (`.nvmrc`, |
| 180 | and `engines` in `package.json`), Rust with the `wasm32-unknown-unknown` |
| 181 | target, and Docker to build the sandbox image. |
| 182 | |
| 183 | ```sh |
| 184 | npm install |
| 185 | npx wrangler login |
| 186 | ``` |
| 187 | |
| 188 | Then, once: |
| 189 | |
| 190 | 1. Create the resources each part needs: D1 databases, queues, KV |
| 191 | namespaces, R2 buckets and the Cloudflare Artifacts namespace (`npx wrangler d1 |
| 192 | create <name>`, `npx wrangler queues create <name>`, and so on), and set |
| 193 | each part's secrets. `deploy/stack.jsonc` lists them all. |
| 194 | 2. Put your own `account_id`, database ids and hostnames in each |
| 195 | `wrangler.jsonc`. |
| 196 | 3. For [Deployments](https://docs.g1t.sh/guides/deployments/), which needs |
| 197 | the Workers for Platforms add-on and a zone for apps: |
| 198 | `scripts/setup-deployments.sh`. |
| 199 | |
| 200 | Deploy everything, migrations first, in dependency order: |
| 201 | |
| 202 | ```sh |
| 203 | scripts/deploy.sh |
| 204 | ``` |
| 205 | |
| 206 | Or only what changed, still in order: `scripts/deploy.sh billing web`. |
| 207 | Both use your `wrangler login`, not a token in `.env`. |
| 208 | |
| 209 | Create the first account by registering on your site, or with |
| 210 | `node services/identity/scripts/create-user.mjs <username>`. |
| 211 | [Deploy g1t to Cloudflare](https://docs.g1t.sh/guides/deploy-to-cloudflare/) |
| 212 | covers the deploy tool, the workflow and first-time setup in full. |
| 213 | |
| 214 | ## License |
| 215 | |
| 216 | [MIT](LICENSE) |