Skip to main content
Fabro checkpoints every workflow run using Git. After each node completes, Fabro commits the file changes and execution state so that interrupted runs can be resumed exactly where they left off. This happens automatically — no configuration required beyond running inside a Git repository.

​
Two branches, two purposes

Each run creates two Git branches that work in tandem:
BranchRef formatContains
Run branchfabro/run/{run_id}File changes made by agents and commands — the actual work product
Metadata branchrefs/fabro/{run_id}Checkpoint JSON, the workflow graph, a run manifest, and offloaded artifacts
The run branch is a regular Git branch that grows one commit per completed node. The metadata branch is an orphan branch (no shared history with your code) that stores structured data using Git’s object database directly — no working tree needed.

​
Run branch commits

After each node finishes, Fabro stages file changes and creates a commit on the run branch. Files matching [checkpoint] exclude_globs patterns (configured in run.toml or server.toml) are excluded from staging: 
fabro(01JKXYZ...): plan (success)

Fabro-Run: 01JKXYZ...
Fabro-Completed: 2
Fabro-Checkpoint: a1b2c3d4...
The commit message follows a structured format:
PartDescription
Subject linefabro({run_id}): {node_id} ({status})
Fabro-Run trailerThe run ID
Fabro-Completed trailerNumber of completed nodes so far
Fabro-Checkpoint trailerSHA of the corresponding commit on the metadata branch
The Fabro-Checkpoint trailer links each run branch commit to its metadata branch commit, so you can navigate from file changes to the full execution state and back.

​
Metadata branch

The metadata branch (refs/fabro/{run_id}) is an orphan branch that stores structured run data using Git’s object storage directly (via git2). It is initialized at run start with:
  • manifest.json — Run metadata: run ID, graph name, node/edge counts, base SHA, and branch name
  • graph.fabro — The workflow DOT source as it was parsed
After each node, the metadata branch is updated with:
  • checkpoint.json — Full execution state (see below)
  • artifacts/*.json — Any offloaded artifact data (large context values over 100KB)
  • nodes/{node_id}/ — Per-node execution trace files (prompts, responses, status, diffs — files under 512KB from an allowlist)

​
What’s in a checkpoint

The checkpoint.json captures everything needed to resume a run:
FieldDescription
timestampWhen the checkpoint was created
current_nodeThe node that just completed
next_node_idThe next node the engine would execute
completed_nodesOrdered list of all completed node IDs
node_retriesHow many retry attempts each node has used
node_outcomesFull outcome (status, context updates, usage) for each completed node
context_valuesSnapshot of the entire run context
logsInternal log entries
git_commit_shaSHA of the run branch commit at this checkpoint
loop_failure_signaturesFailure signature counts for loop detection
restart_failure_signaturesFailure signature counts across loop-restart edges
The checkpoint is also saved to checkpoint.json in the run directory for quick local access.

​
Worktrees

Fabro uses Git worktrees to isolate workflow runs from your working directory. When a run starts in a clean Git repository:
  1. Fabro records the current HEAD as the base SHA
  2. Creates a new branch fabro/run/{run_id} at that SHA
  3. Adds a worktree at {run_dir}/worktree on that branch
  4. Changes into the worktree directory for the duration of the run
This means your original working directory stays untouched while the agent makes changes in the worktree. When the run completes, Fabro removes the worktree and restores your original directory.
If the working directory has uncommitted changes, Fabro skips worktree setup and runs in place, logging a warning. Git checkpointing is disabled in this case.
For Daytona sandboxes, the worktree is created inside the remote sandbox instead. The metadata branch is still written to the host repository so that runs can be resumed locally. Both the run branch and the metadata branch are pushed to origin after each checkpoint — the run branch is pushed from the sandbox, while the metadata branch is pushed from the host using a GitHub App installation token. On the remote, the metadata branch appears at fabro/meta/{run_id} (rather than the local refs/fabro/{run_id} custom ref, since GitHub disallows branch names starting with refs/).

​
Resuming a run

There are two ways to resume an interrupted run:

​
From a checkpoint file

Resume from a checkpoint.json saved in the run directory: 
fabro run workflow.fabro --resume path/to/logs/checkpoint.json
Fabro loads the checkpoint, restores the context and execution state, and continues from the next node after the checkpoint.

​
From a run branch

Resume from the Git branches created during a previous run: 
fabro run --run-branch fabro/run/01JKXYZ...
This reads the checkpoint, manifest, and graph DOT from the metadata branch (refs/fabro/01JKXYZ...), re-attaches a worktree to the existing run branch, and resumes execution. No workflow file argument is needed — everything is recovered from Git.
  1. Fabro reads checkpoint.json from the metadata branch
  2. Reads manifest.json and graph.fabro to reconstruct the workflow
  3. Creates a fresh worktree attached to the existing run branch
  4. Restores the full context, completed node list, retry counts, and failure signatures
  5. If the checkpointed node used full fidelity, downgrades the first resumed node to summary:high (since the original conversation thread no longer exists in memory)
  6. Continues execution from next_node_id

​
The checkpoint cycle

Here’s the full sequence that runs after every node completes:
  1. Save checkpoint to disk — Write checkpoint.json to the run directory
  2. Write metadata branch — Serialize the checkpoint and any new artifacts to the metadata branch (shadow commit)
  3. Commit to run branch — Stage all file changes, commit with structured trailers linking to the shadow commit SHA
  4. Update checkpoint — Re-save checkpoint.json with the git_commit_sha field set
Steps 2-4 are best-effort — if any Git operation fails, the run continues and logs a warning. The disk checkpoint from step 1 is always available as a fallback.

​
Inspecting run history

Because checkpoints are plain Git commits, you can inspect them with standard Git tools: 
# View the commit log for a run
git log fabro/run/01JKXYZ... --oneline

# See what an agent changed at a specific node
git show fabro/run/01JKXYZ...

# Diff the full run against the starting point
git diff main..fabro/run/01JKXYZ...

# Read checkpoint data from the metadata branch (local)
git show refs/fabro/01JKXYZ...:checkpoint.json | jq .current_node

# Read checkpoint data from the remote (Daytona runs)
git show origin/fabro/meta/01JKXYZ...:checkpoint.json | jq .current_node

​
When checkpointing is active

Git checkpointing activates automatically when:
  • The working directory is a clean Git repository (local and Docker sandboxes)
  • The sandbox is Daytona (metadata branch on the host, commits inside the sandbox)
It is skipped when:
  • The working directory has uncommitted changes
  • The working directory is not a Git repository
  • The run uses --dry-run