tine fork

Fork a run from any step to create a new execution branch. This is the killer feature of opentine — when something goes wrong at step N, you don't re-run the N-1 good steps. You fork from the last good step and try a different approach. No wasted tokens, no wasted time.

Usage

Terminal
tine fork <run_id> --from-step <index> [--save <path>]

Arguments

  • <run_id> — The run to fork from. Accepts a run ID prefix or a .tine file path.
  • --from-step <index> — The step index to fork from. The new run includes all ancestor steps up to (but not including) this index.
  • --save <path> — Optional. Where to save the forked run. Defaults to .tine_runs/{run.id}.tine.

Basic Example

Terminal
# Fork from step 5 of a run, saving to default location
tine fork a3f8c1d2 --from-step 5

# Fork and save to a specific file
tine fork a3f8c1d2 --from-step 5 --save experiments/v2.tine

Example output:

Terminal
Forking run_a3f8c1d2 from step 5...
Created new run: run_b7e2f4a1
Ancestors: steps 0-4 preserved
Saved to .tine_runs/run_b7e2f4a1.tine

The Fork Workflow

Forking is most powerful as part of an iterative debugging and experimentation workflow. Here's a typical session:

Terminal
# 1. Run your agent
tine run research.py

# 2. Inspect the run tree
tine show a3f8c1d2

# 3. Step 8 went wrong — fork from step 7
tine fork a3f8c1d2 --from-step 7

# 4. Resume the forked run with a modified agent
tine resume b7e2f4a1

# 5. Compare the original and forked runs
tine diff a3f8c1d2 b7e2f4a1

This pattern lets you treat agent runs like git branches. Run, inspect, fork from the point of failure, and try again — all without repeating expensive model calls.

Programmatic Forking

You can also fork runs in Python code, which gives you full control over the forked run before resuming it:

fork_experiment.py
1from opentine import Run
2
3# Load the original run
4run = Run.load(".tine_runs/run_a3f8c1d2.tine")
5
6# Fork from step 7
7forked = run.fork(from_step=7)
8
9# The forked run has steps 0-6 from the original
10# Now resume with a different strategy
11forked.save("experiments/v2.tine")

How It Works

When you fork a run, opentine creates a new Run object whose step list contains all the ancestor steps from the original run, up to the fork point. The new run gets a fresh ID and is marked as paused. From there, you can resume it with tine resume or load it in Python to continue execution with a modified agent.

Because steps are content-addressed, the forked run shares the exact same step data as the original — no duplication on disk, no redundant computation.