Gittrix

Ephemeral workspaces for AI coding agents.

Gittrix routes agent writes away from durable repo history and into isolated workspaces. Humans review the diff and promote only the accepted changes back to durable git storage.

Storage routing for AI coding agents.

Short example

import { GitTrix } from '@gittrix/core'
import { LocalDurableAdapter, LocalEphemeralAdapter } from '@gittrix/adapter-local'

const gittrix = new GitTrix({
  durable: new LocalDurableAdapter({ path: '/path/to/repo', branch: 'main' }),
  ephemeral: new LocalEphemeralAdapter({ sessionsRootDir: '/tmp/gittrix-sessions' }),
})

await gittrix.init()

const session = await gittrix.startSession({
  task: 'update docs',
  durablePath: '/path/to/repo',
  durableBranch: 'main',
})

const agent = session.forAgent()
await agent.write('README.md', new TextEncoder().encode('# Updated\n'))
await agent.commit('agent draft')

console.log(await session.diff())

await session.promote({
  selector: { mode: 'all' },
  message: 'docs: update readme',
})

await gittrix.close()

agent is an AgentSession. It has no promote() method. Durable writes stay on the user-facing UserSession.

What Gittrix gives you

Agent-safe by construction

Agents receive an AgentSession with no promote method. Durable writes are only available through the user-facing session.

Adapter-based storage routing

Use local git, GitHub, Cloudflare Artifacts, or any compatible durable/ephemeral adapter pair.

Baseline-aware promotion

Gittrix records the durable baseline at session start and refuses to overwrite overlapping durable changes during promotion.

Normal git workspaces

Git-backed ephemeral adapters expose local workspaces where tools can run normal git commands.

Adapter matrix

Local is fully implemented for durable and ephemeral workflows. GitHub is implemented as a durable adapter. Cloudflare Artifacts is implemented for both durable repositories and ephemeral session workspaces. Code Storage is scaffolded but unavailable pending early access.

Package	Version	Durable	Ephemeral	Status
@gittrix/core	0.1.4	n/a	n/a	current core router
@gittrix/adapter-local	0.1.4	yes	yes	implemented
@gittrix/adapter-github	0.2.0-alpha.2	yes	no	implemented
@gittrix/adapter-cloudflare-artifacts	0.2.0-alpha.2	yes	yes	implemented
@gittrix/adapter-codestorage	0.3.0-alpha.1	yes	yes	scaffold only; throws unavailable
@gittrix/cli	0.1.4	local only	local only	private package, root binary is gittrix

flowchart LR
  Human["Human-facing app\nUserSession"] --> Router["GitTrix router"]
  Agent["AI coding agent\nAgentSession"] --> Workspace["Ephemeral workspace\nthrowaway storage"]
  Router --> Durable["Durable git storage\nsource of truth"]
  Router --> Workspace
  Workspace --> Diff["Diff review"]
  Diff --> Human
  Human --> Promote["promote selected files"]
  Promote --> Durable

  classDef durable fill:#e8f7ee,stroke:#1f7a47,color:#0f3d25,stroke-width:1px
  classDef eph fill:#eef4ff,stroke:#2855a6,color:#10284f,stroke-width:1px
  classDef user fill:#fff7ed,stroke:#9a3412,color:#7c2d12,stroke-width:1px
  class Durable durable
  class Workspace,Agent eph
  class Human,Promote,Diff user

Install

bun add @gittrix/core @gittrix/adapter-local

bun add @gittrix/core @gittrix/adapter-github @gittrix/adapter-local

bun add @gittrix/core @gittrix/adapter-cloudflare-artifacts

CLI:

bun add -g gittrix