Quickstart

Install

Local durable + local ephemeral:

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

GitHub durable + local ephemeral:

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

Cloudflare Artifacts durable + ephemeral:

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

CLI:

bun add -g gittrix

Local durable + local ephemeral

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')

const diff = await session.diff()
console.log(diff)

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

await gittrix.close()

session.forAgent() returns an AgentSession, so the agent can read, write, delete, list, diff, log, and commit inside the ephemeral session API. It cannot promote to durable storage.

Current core commit() returns a synthetic ephemeral-${Date.now()} ID. Git-backed ephemeral workspaces can still be used as normal local git directories by external tools.