What is Gin?
Gin is a Rust source-state engine for agent workspaces. It gives each agent a cheap, isolated workspace, lets workspaces stack on each other's unpublished work, and records what happened to the source in a form machines can query.
Its core operations are:
- savepoint and checkpoint: make private work durable, then immutable;
- publish: expose one exact checkpoint on a channel, whole or not at all;
- preview and advance: compose new parents with your own work, inspect the result and conflicts, then switch atomically;
- conflict inspection and resolution as first-class data;
- evidence: execution receipts and CI results bound to exact source trees;
- Git interoperability at the edge.
Built for agents, not humans
This is Gin's guiding principle (accepted 2026-11-06, see Architecture decisions).
Many of Git's features exist for people maintaining code by hand: commit messages, authors, porcelain conventions, a linear story of history. Gin does not copy them. Instead it carries what agents and machines need:
- checkpoints, with exact parent sets;
- the DAG of dependent work;
- structured metadata;
- provenance;
- evidence;
- comments (annotations).
When an agent needs intent or context, Gin extends its own metadata and comments rather than adopting a Git equivalent. Gin is measured against Git on agent workloads: many parallel workspaces, dependent changes, restacking and integration.
"Parity with Git" means cost, not features. Gin does no extra work by default that Git does not do; stronger guarantees (for example, full device flushes on every acknowledgement) are options, off by default.
What Gin is not
Not a Git replacement
Git stays the external source-control and delivery system. People review, merge and ship through Git and their forge. Gin touches Git only when the two are synchronised.
Gin also is not:
- A build or test runner. Gin never builds or executes repository code. It serves pinned snapshots to executors and stores the evidence they report.
- A sandbox. Gin versions what lands in a workspace; it does not contain the processes that write there. A command an agent runs has that agent's operating-system privileges. Containment belongs to the executor or the agent harness.
- An orchestrator. Gin exposes source-state and evidence operations. It does not schedule tasks, run reviews or decide what lands.
- A filesystem harness. Ordinary "edit files in a directory and commit" compatibility is not provided. Agents edit through the CLI, MCP or API, or a harness explicitly materialises a pinned tree and captures edits through conditional saves.
How Gin relates to Git
Gin's history is its own. It records many checkpoints, forks and joins that Git never sees, and it does not mirror Git's history or walk Git ancestry.
- Git commits are not Gin nodes.
- Gin stores no Git commit messages, authors or committer dates.
- A sync between the two is one diff and one checkpoint, however many commits Git gained in between.
- Git object names never become Gin identities. Gin uses its own typed, domain-separated BLAKE3 identities.
See Git interoperability for the current import and export surface.
How Gin relates to Toki
Toki is the build and test system. The boundary is simple: Gin is source control plus metadata; Toki builds and tests.
| Concern | Owner |
|---|---|
| Source states, workspaces, checkpoints, publication, composition, conflicts | Gin |
| Pinned snapshots and their leases, verified content reads | Gin |
Materialising a snapshot onto disk (gin view), stable checkouts and source times | Gin |
| Evidence envelope, trust, applicability and reuse verdicts | Gin |
| Build closure analysis (for example Cargo inputs), command execution, output caches | Toki |
| Execution receipt payload schema | Toki (Gin validates and stores it under its evidence envelope) |
Toki talks to Gin through the installed gin binary and its versioned JSON interfaces rather than by linking Gin's crates, so the two can release separately. Toki pins the exact snapshot it builds, reads or materialises it, and reports the result as a receipt. Gin records the receipt against that exact tree.
Who owns what else
Gin works with no orchestrator present, speaks only its own types (repository, workspace, epoch, checkpoint, channel, change set, conflict, evidence, lease), and never parses an orchestrator's labels. An orchestrator can pass opaque labels, such as a task key for a change set's origin, which Gin stores as bytes. Final landing authority and required checks stay with the forge.
Next steps
- Getting started: build Gin and run a first session.
- Concepts: the vocabulary used throughout these docs.
- Agent workflow: the end-to-end coordinator recipe.