Session Management

Sessions are persisted as JSONL files in a project-aware directory:

~/.sharur/sessions/
  --Users-alice-Projects-myapp--/     ← sanitized CWD
    2026-04-23T07-06-54_{uuid}.jsonl  ← timestamped session file
    2026-04-23T09-12-11_{uuid}.jsonl

Session File Format

Each .jsonl file contains one JSON object per line:

• Line 0 (header): kind=header — session ID, parentId, model, timestamps, system prompt, compaction settings, dryRun flag
• Subsequent lines: kind=message — individual conversation messages with full payloads (role, content, thinking, tool calls, tool call ID)

Session Tree

Sessions form a linked tree via parentId. The session.Manager.BuildTree() method assembles all sessions from the project directory into a []*TreeNode tree. FlattenTree produces a depth-first flat list with structured layout metadata (gutters, connectors, indentation), which the TUI layer uses to render a clean Unicode box-drawing tree diagram.

flowchart TD
    A["Session A
(root)"] --> B["Session B
(/branch from A)"]
    A --> C["Session C
(/fork of A)"]
    B --> D["Session D
(/branch from B at msg 5)"]
    B --> E["Session E
(/rebase of B)"]
    B --> F["Session F
(/merge into B)"]

    style C stroke-dasharray: 5 5

/fork creates an independent copy (dashed border above) with no parentId link — it does not appear as a child in the tree visualization.

Branching, Rebasing & Merging

flowchart TD
    Q{"What do you need?"}

    Q -->|"Explore an alternate
path from this point"| Branch["/branch [idx]
Child session, same history up to idx"]
    Q -->|"Independent copy
no tree relationship"| Fork["/fork
Detached snapshot"]
    Q -->|"Clean up the conversation
keep only specific messages"| Rebase["/rebase
Interactively select messages
for a new session"]
    Q -->|"Combine two sessions
into one context"| Merge["/merge <id>
LLM-synthesized merge turn
appended to current session"]

The /tree modal (keyboard shortcut B, F, R on a selected session) exposes all of these without leaving the TUI.

Compaction & Context Management

To stay within LLM context windows, sharur implements an auto-compaction strategy:

1. Trigger: When tokens > ContextWindow - reserveTokens, compaction fires.
2. Summarization: The agent uses the LLM to generate a structured summary (<!-- sharur-summary -->) of the pruned messages.
3. File Tracking: The summary carries forward lists of files read and modified, so the assistant retains awareness of what it has already seen.
4. Split Turn Handling: If compaction cuts mid-turn, a “Turn Prefix Summary” is generated to preserve context for the remaining tool calls.
5. Session Tree Integration: Compaction events are stored as TypeCompaction records in the JSONL file, visible in /stats and preserved across restarts.

Compaction Configuration

// ~/.sharur/config.json or .sharur/config.json
{
  "compaction": {
    "enabled": true,
    "reserveTokens": 2048,
    "keepRecentTokens": 8192
  }
}

Trigger compaction manually at any time with /compact in the TUI or by calling the Compact RPC directly.

Export & Import

Sessions can be exported to and imported from JSONL files:

# Export from TUI
/export /path/to/session.jsonl

# Import into TUI (creates a new session from the file)
/import /path/to/session.jsonl

# Export from CLI without entering TUI
shr --export /path/to/session.html   # HTML snapshot

Exported JSONL files are self-contained: they include the session header and all messages. Imported sessions are assigned a new UUID and added to the current project’s session directory.