Session tree

Sessions covers the day-to-day flags. This page goes one level down: how the tree is actually shaped, what each navigation command does to the leaf pointer, and how export, share, and resume read from it.

Every entry has a parent

A session file is append-only JSONL. Every non-header entry carries an id and a parentId — those pointers, not line order, define the conversation. The runtime tracks one extra piece of state per session: leafId, the entry that the next append will hang off. Appending always creates a child of the current leaf. Branching never rewrites old entries; it only moves the leaf before the next append.

That means a single file can hold several threads. The “active path” is whatever you get by walking parentId from the leaf back to the root. Everything else still lives in the file and stays visible to /tree.

root
├─ user: "Start task"
│  └─ assistant: "Plan"
│     ├─ • user: "Try approach A"   ← leaf
│     │  └─ • assistant: "A result"
│     └─ user: "Try approach B"
│        └─ assistant: "B result"

/tree — move the leaf in place

/tree opens the in-file navigator. It does not create a new file or touch history; it just repoints leafId.

Keys inside the selector:

• ↑/↓ move; ←/→ page.

• Type to fuzzy-search across rendered text, labels, roles, and tool snippets.

• Shift+L sets or clears a label on the highlighted entry. Labels persist as their own entries and become bookmarks.

• Ctrl+O cycles filters; Alt+D/T/U/L/A jumps to default, no-tools, user-only, labeled-only, or all.

What happens on Enter depends on the entry type:

• User or custom message — leaf moves to that entry’s parent, and the message text is copied into the editor for editing and resubmission. Selecting the very first user prompt resets the leaf to the root.

• Anything else (assistant, tool result, summary, bookkeeping) — leaf moves to the selected entry. Editor is not prefilled.

• Current leaf — no-op; the selector closes with “Already at this point”.

If branchSummary.enabled is on, you get a summary prompt before the move; the resulting branch_summary entry is appended at the new position, not at the abandoned tail.

/branch vs /fork

Both create a new leaf. They differ in whether a new file gets created.

/branch opens a user-message picker and starts a new thread in the same file from the selected prompt. The original branch is still reachable through /tree. Use it when you want one file to be the canonical record of an exploration.

/fork copies the entire current session into a brand-new JSONL, rewrites the header with a fresh id, sets parentSession to the old id, and switches the active session to the copy. The original file is untouched. Use it when the alternative might get abandoned and you don’t want it cluttering the parent’s /tree view. Artifact directories are copied alongside the file. /fork is blocked while a turn is streaming.ming and disabled under --no-session.

The parentSession field in the new header is the only lineage marker — it lets tools walk back to the source, but the fork is otherwise independent.

Resume picks a leaf

Resume operations all land on whatever the file’s leaf was when last written:

• omp -c (--continue) prefers a per-terminal breadcrumb, then falls back to the newest file by mtime in the cwd.

• omp -r <prefix> matches an id in the current project, then globally. A cross-project match prompts to fork into the current cwd rather than silently changing directories.

• omp --fork <id|path> always lands in a new file with parentSession set, skipping the prompt.

• --resume <path.jsonl> opens the file directly.

In-session, /resume lists sessions in the current cwd (Tab switches the picker to all-projects scope) and uses switchSession to swap state in place — model, thinking level, MCP selection, and todos are all rebuilt from the new file’s active path.

Export, dump, share

/dump renders the active root→leaf path, not the whole file — branches you abandoned with /tree won’t appear. /export and /share embed the whole file and open on the active path; the HTML viewer has its own tree navigator for the rest.

• /export [path] and omp --export <file> write a self-contained HTML rendering.

• /dump copies a plaintext transcript to the clipboard — system prompt, tools, messages, results.

• /share exports to a temp HTML and runs ~/.omp/agent/share.{ts,js,mjs} if present; otherwise uploads a secret gist via gh.

To share alternate branches, /tree to that leaf first, then export. To share everything in the file regardless of leaf, send the JSONL directly — the receiver can omp --resume ./file.jsonl and use /tree to walk it.

Related

• Sessions — resume, branch, share, and the day-to-day flags.

• Session format — the on-disk JSONL schema, including parentId and header fields.

• Handoff — structured wrap-up entry for passing a session to a teammate.\n