Quickstart

This guide captures a native opentine run, saves it as a .tineartifact, verifies the checksum, and branches from the saved graph.

1. Install opentine

Python 3.11+ is required. Install the core package plus the provider SDK you plan to use.

Terminal
pip install "opentine[anthropic]"

2. Set Your API Key

Export the provider credential outside your code. Saved artifacts redact common secret-bearing keys before writing.

Terminal
export ANTHROPIC_API_KEY="sk-ant-..."

3. Write and Save a Run

Agent.run_sync() returns a Run. Saving the run writes a v1 graph artifact with graph.steps, graph.order, transcript, manifest, policies, cache, and integrity metadata.

research.py
1from opentine import Agent
2from opentine.models.anthropic import Anthropic
3from opentine.tools.search import search
4from opentine.tools.web import fetch
5
6agent = Agent(
7    model=Anthropic("claude-sonnet-4-20250514"),
8    tools=[search, fetch],
9    system="Search the web, synthesize findings, and cite useful sources.",
10    max_steps=30,
11)
12
13run = agent.run_sync("Research the current state of solid-state batteries")
14run.save("battery_research.tine")
15
16print(f"Run: {run.id[:12]}")
17print(f"Status: {run.status.value}")
18print(f"Steps: {len(run.steps)}")
19print(f"Cost: {run.total_cost:.4f}")

4. Inspect and Verify

tine show renders the graph. tine verify recomputes the artifact body checksum stored in metadata.integrity.

Terminal
tine show battery_research.tine
tine verify battery_research.tine
Terminal
# fe3a767307a4  model=claude-sonnet-4-20250514  steps=5  cost=$0.0341  completed
|-- + 9e4b8c2a19dd done   "I will compare recent solid-state battery claims..."
|-- > 81bf0f67bb12 tool   search(query="solid-state battery 2026")
|-- + 6d4a0b270a5f done   "The strongest evidence points to..."

OK battery_research.tine sha256:7d42b8a91c0f

5. Fork, Replay, and Diff

Forking copies the ancestor graph up to the selected step and records fork metadata. Cached replay reuses recorded steps; rerun replay requires a native agent API or explicit harness.

Terminal
# Fork from a step index, full ID, or unique ID prefix.
tine fork battery_research.tine --from-step 2 --save battery_retry.tine

# Cached replay writes a new artifact reusing recorded steps.
tine replay battery_research.tine --mode cache --save battery_replayed.tine

# Compare graph shape and divergence.
tine diff battery_research.tine battery_retry.tine

Native Resume

Native agents can resume from saved transcript state with agent.resume_sync(). External harness resume is only available when the run manifest declares support.

resume_native.py
1from opentine import Agent, Run
2from opentine.models.anthropic import Anthropic
3
4run = Run.load("battery_research.tine")
5agent = Agent(model=Anthropic("claude-sonnet-4-20250514"))
6
7resumed = agent.resume_sync(
8    run,
9    from_step=run.refs["main"],
10    prompt="Re-check the strongest claims and produce a shorter summary.",
11)
12resumed.save("battery_resumed.tine")

External Harnesses

opentine can also wrap observable CLI agents. Use --harness-login-envonly when an authenticated CLI needs access to its normal login/config environment.

Terminal
tine run --harness codex --prompt "Inspect this repository" --save codex_run.tine
tine run --harness kimi-code --prompt "Summarize README.md" --harness-login-env
tine run --harness generic --harness-command "your-agent run" --prompt "Fix the tests" --cwd .

Next Steps

  • Read Serialization for the v1 .tine format.
  • Review tine run for native and harness execution options.
  • Learn how Forking preserves graph ancestry.