Core API reference

GitTrix options

interface GitTrixOptions {
  durable: DurableAdapter
  ephemeral: EphemeralAdapter
  storeDir?: string
  defaultEviction?: Partial<EvictionPolicy>
  evictionSweepIntervalMs?: number
}

durable.capabilities().git must be true.

Session interfaces

interface AgentSession {
  read(path: string): Promise<Uint8Array>
  write(path: string, bytes: Uint8Array): Promise<void>
  delete(path: string): Promise<void>
  commit(message: string): Promise<string>
  writeAndCommit(opts: { files: Record<string, Uint8Array>; message: string }): Promise<string>
  list(path?: string): Promise<ListEntry[]>
  diff(): Promise<string>
  log(): Promise<CommitEntry[]>
}

interface UserSession extends AgentSession {
  promote(opts: PromoteOpts): Promise<PromoteResult>
  discard(): Promise<void>
  extend(ttlMs: number): Promise<void>
  forAgent(): AgentSession
}

Promotion types

type PromoteSelector =
  | { mode: 'all' }
  | { mode: 'files'; files: string[] }

type PromoteStrategy = 'auto' | 'commit' | 'branch' | 'pr' | 'patch'

Core currently passes selected files to durable.applyCommit() on the durable branch. Branch, PR, and patch strategies are not implemented as distinct session.promote() behavior yet.

Adapter capabilities

interface AdapterCapabilities {
  git: boolean
  push: boolean
  fetch: boolean
  history: boolean
  ttl: boolean
  maxBlobSize?: number
  latencyClass: 'local' | 'edge' | 'regional'
}

Ephemeral workspace info

interface EphemeralWorkspaceInfo {
  localPath?: string
  ephemeralRef?: string
  isGitBacked: boolean
  supportsShellCwd: boolean
  supportsGitCommands: boolean
  supportsPromote: boolean
  workspaceKind: 'worktree' | 'clone' | 'copy' | 'remote'
}

Ref types

type Ref =
  | { type: 'local'; path: string; branch?: string }
  | { type: 'github'; owner: string; repo: string; branch?: string }
  | { type: 'codestorage'; namespace: string; repo: string; branch?: string }
  | { type: 'cloudflare'; namespace: string; key: string }
  | { type: 'gitfork'; slug: string }

Ref URI formats

local:///abs/path#branch
github://owner/repo#branch
codestorage://namespace/repo#branch
cloudflare://namespace/key
gitfork://slug

Windows local paths are normalized to:

local:///C:/path/to/repo#main

Events

gittrix.on('session.start', ({ sessionId }) => {})
gittrix.on('session.write', ({ sessionId, path, op }) => {})
gittrix.on('session.commit', ({ sessionId, sha }) => {})
gittrix.on('session.promote', ({ sessionId, result }) => {})
gittrix.on('session.evict', ({ sessionId }) => {})

Error codes

ADAPTER_UNAVAILABLE
AUTH_FAILED
CAPABILITY_MISSING
SESSION_NOT_FOUND
SESSION_EXPIRED
BASELINE_CONFLICT
PROMOTE_FAILED
WRITE_REJECTED
EVICTION_RACE
METADATA_VERSION_UNSUPPORTED