Sessions

A session is a conversation between you and an AI backend. Sessions are the primary unit of interaction in simse: they hold the message history, pull in relevant context from your library, and track tool calls made during the conversation. Examples use TUI slash commands — for headless mode, see the commands reference.

Session lifecycle

Sessions follow a straightforward lifecycle:

1. Create — Launch simse to start a fresh session and connect to your configured backend.
2. Prompt — Each message you send is processed by the backend, which streams a response back.
3. Tool calls — If the backend invokes tools during a response, simse executes them and reports results back. You can see tool calls progress through in_progress and completed states.
4. End — The session closes when you exit. Its conversation state is saved automatically.

Session persistence

Sessions are saved automatically so you can resume them later. On the CLI, sessions are stored locally in ~/.config/simse/sessions/ (Linux) or ~/Library/Application Support/simse/sessions/ (macOS). When using cloud sync, sessions are stored remotely so you can access them from any machine.

You can list all saved sessions by running the simse resume CLI subcommand with no ID:

simse resume

And resume a previous session by ID with /resume in the TUI:

/resume <session-id>

Session forking

Forking creates a copy of an existing session with a new ID. The forked session inherits the full conversation history but diverges from the original from that point forward.

/fork

Forking is useful when you want to explore a different approach — try an alternative solution without losing the original conversation. Both sessions share the same library, so your persistent context remains available in either branch.

Structured compaction

As sessions grow long, simse can compact the conversation history to reduce token usage while preserving the key information. Compaction is triggered automatically when a session reaches a configurable length, or manually with:

/compact

The compaction process creates a structured summary covering:

1. Goal — What the session is trying to accomplish
2. Progress — What has been completed so far
3. Current State — Where things stand right now
4. Key Decisions — Important choices made during the session
5. Relevant Files — Files that were read, edited, or created
6. Next Steps — What remains to be done

The compacted summary replaces the detailed message history but preserves the full context needed to continue working effectively.

Session commands

Command	Description
/resume [id]	Resume a session by ID (run the simse resume CLI subcommand with no ID to list sessions)
/fork [at_message]	Fork the current session at a message index
/compact	Compact the current session

Context and the library

Sessions do not work in isolation. When a session starts, simse queries your library for entries relevant to the current context. As the session progresses, new context is written back to the library. When the next session begins, that context is available.

This means you do not need to paste previous context into each new session. simse surfaces what is relevant automatically, based on what you are working on.