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