SDKSessions

Sessions

A session is one conversation: its messages, the tool results, the files it has read and changed, and its cost so far. Each run of syntic starts a new session unless you pick an existing one.

Start, continue, resume and fork

NeedFlags
New session with a chosen id--session-id <id>
Continue the most recent session in this folder--continue
Resume a session by id--resume <id>
Start a new session from a copy of an old one--resume <id> --fork-session

A fork gets a new id and keeps the whole history of the original. The original transcript is not changed.

Resuming in print mode appends the new turn to the same session unless you add --fork-session.

Cost across a resume

Headless cost totals are stored with the session, so a resumed run continues the earlier total.

Limits

  • --resume takes a session id, a unique id prefix, or an exact session title (set with /rename or --name). When two sessions share the title, both are listed and nothing is resumed.
  • A session that ran in a session worktree resumes inside that worktree.
  • Resuming restores the model, effort and agent the session last ran with, unless a flag such as --model says otherwise. It never restores the permission mode.
  • A turn that was interrupted mid-run is not resumed automatically. Start a new turn with a prompt that says where to continue.
  • Old transcripts are deleted only when you set cleanupPeriodDays. See Session storage.

Where transcripts are stored is described in Session storage.