CLI Sessions

The epi CLI automatically saves conversations as session files. You can continue previous sessions, use specific session files, or run without persistence.

Default Behavior

By default, each invocation of epi creates a new session file in a project-specific directory:

~/.pi/agent/sessions/<sanitized-cwd>/session-YYYY-MM-DD-HH-mm-ss.jsonl

The working directory path is sanitized and used to organize sessions by project.

Session Options

Continue previous session

Resume the most recent session for the current directory:

epi --continue
epi -c

# Continue and add a new prompt
epi -c "What were we working on?"

When continuing, the previous messages are restored and available to the agent. It picks up right where you left off.

Specific session file

Open a specific session file:

epi --session ./my-session.jsonl
epi --session ~/.pi/agent/sessions/my-project/session-2025-01-15-10-30-00.jsonl

Custom session directory

Override the default session storage location:

epi --session-dir ./my-sessions

Ephemeral sessions

Run without saving the session:

epi --no-session
epi --no-session -p "Quick question, no need to save"

Ephemeral sessions use an in-memory session manager. The conversation is lost when the CLI exits.

Session File Format

Sessions use the JSONL format (one JSON object per line). The first line is a header, followed by entries:

{"type":"session","version":1,"id":"abc123","timestamp":"2025-01-15T10:30:00Z","cwd":"/home/user/project"}
{"type":"message","id":"msg1","parentId":null,"timestamp":"...","message":{"role":"user","content":"Hello"}}
{"type":"message","id":"msg2","parentId":"msg1","timestamp":"...","message":{"role":"assistant","content":"Hi!"}}
{"type":"message","id":"msg3","parentId":"msg2","timestamp":"...","message":{"role":"user","content":"Read src/index.ts"}}

Entry Types

Type	Description
`session`	Header with metadata (version, ID, timestamp, working directory).
`message`	A conversation message (user, assistant, tool).
`compaction`	Summary of older messages that were compressed.
`branch_summary`	Summary of an abandoned conversation branch.
`model_change`	Records when the model was switched.

Session Directory Structure

~/.pi/agent/sessions/
├── home-user-project-a/
│   ├── session-2025-01-14-09-00-00.jsonl
│   └── session-2025-01-15-10-30-00.jsonl
├── home-user-project-b/
│   └── session-2025-01-15-14-00-00.jsonl
└── tmp-quick-test/
    └── session-2025-01-15-16-45-00.jsonl

Sessions are organized by the sanitized working directory path. This keeps project-related conversations grouped together.

Session Lifecycle

Creation — A new session file is created when epi starts (unless using --continue, --session, or --no-session)
Appending — Each message exchange is appended as a new line in the JSONL file
Compaction — When the context grows too large, older messages are summarized and a compaction entry is written
Continuation — On resume, the session is read and the message history is restored