Sessions

A session is one conversation with the agent in one workspace. Under the hood it is an append-only log of typed events. Everything Cusp shows you, in any surface, is rendered from that log.

The event logCopy Anchor Link

Each event has a sequence number (seq) that only goes up. A typical turn writes events like these:

Because the log is the source of truth, a few things follow naturally:

• Reconnecting is cheap. A client that drops its connection resubscribes from the last seq it saw and receives only what it missed.
• Every surface sees the same thing. The CLI and the desktop app can watch the same session at once.
• History is inspectable. The REST API returns events by page, filtered by type.

Session identityCopy Anchor Link

Every session has:

• An id, like ses_01JC…, which is what you pass to cusp --resume.
• A title. Cusp generates one from your first message with the small model; rename it with /rename or cusp -n "title".
• A short handle, like api-tests, which other agents use to address it with SendMessage.
• A model, an effort level and a permission mode, each of which you can change mid-session.
• An origin: started by you, by a subagent, by the CLI, by a schedule, or by a Crew member.

ResumeCopy Anchor Link

Sessions persist across restarts. Pick up where you left off:

cusp --continue          # the most recent session in this folder
cusp --resume            # choose from a list
cusp --resume ses_01JC…  # a specific session

Inside the CLI, /resume opens the same list. /clear starts a new session; the old one stays resumable.

ForkCopy Anchor Link

A fork copies a session's log into a new, independent session. Use it to try a different approach without losing the current one, or to branch off a long investigation.

cusp --continue --fork-session

In the CLI, /fork continues in a copy of the current session. Forks can also start from an earlier point: the API takes a seq and copies only the events up to it.

RewindCopy Anchor Link

Rewind takes the conversation back to just before one of your earlier prompts, and by default restores your files to how they were at that moment.

• In the CLI, press Esc twice on an empty prompt, or run /rewind, and pick the prompt to go back to.
• The rewound prompt is put back in the composer so you can edit and resend it.

Rewinding truncates the log after that point. Sequence numbers are never reused, so clients can't confuse old and new events. Rewind is refused while a turn is running; interrupt first.

CheckpointsCopy Anchor Link

Before any tool modifies files, Cusp snapshots the files it is about to change into a content-addressed blob store. Rewinding to a point restores, for each path, the content it had at that point. A file that didn't exist then is removed.

WorktreesCopy Anchor Link

A session can run in its own git worktree, so its changes stay apart from your working copy and from other sessions. This is how you run several agents on the same repository at once without them stepping on each other.

• Worktrees live under the Cusp data directory (~/.cusp/worktrees/<workspace>/ by default), never inside your repository.
• The session's working directory mirrors your position in the repository. If you started in packages/api, the session starts in packages/api inside the worktree.
• When you delete the session, Cusp can remove its worktree too.

Subagents can also request worktree isolation (isolation: worktree in their definition).

InterruptingCopy Anchor Link

Press Esc in the CLI, or the stop button in the desktop app, to interrupt the running turn. The model stream is cancelled, running tools are stopped, and any partial assistant message is closed as aborted. The session returns to idle and you can continue.

Messages you send while the agent is working are queued and delivered when the current step finishes.

CompactionCopy Anchor Link

Long sessions eventually fill the model's context window. Cusp compacts in stages: it first trims large old tool outputs, then summarizes the conversation into a structured handoff that keeps the task list, files touched and decisions. The compaction event records what happened. You can compact by hand with /compact [instructions].

ExportCopy Anchor Link

/export [file] writes the conversation to a text file. Programs can read the raw event log through the daemon's REST API.

Where sessions are storedCopy Anchor Link

The daemon keeps sessions in a SQLite database in its data directory, next to the checkpoint blobs and worktrees.