pig saves a conversation as a session. The active branch of that session supplies conversation history for the next model request. Use session commands to continue work, explore another branch, or reduce the amount of history sent to the model.

pig saves sessions automatically unless you start it with --no-session.

pig --continue
pig --resume

--continue opens the most recent session for the current working directory. --resume opens the session picker. In interactive mode, /resume opens the same picker and /new starts a new session.

Use /name or --name to assign a recognizable session name. Run /session to verify the current session file, ID, message count, token usage, and cost.

The session picker lets you search, rename, and delete sessions. Tab switches between this folder's sessions and all sessions, Ctrl+S cycles the sort (threaded, recent, fuzzy), Ctrl+N shows only named sessions, Ctrl+P shows paths, and Ctrl+R renames (in /resume only). Search matches words fuzzily; "exact phrase" matches a phrase and re:pattern a regular expression. Deleting asks for confirmation and refuses the current session. See Keybindings for its shortcuts.

pig also lists sessions pi wrote under ~/.pi/agent/sessions/, and appends to such a session when you open it. A session from another project picked in the selector continues in that project's directory, with that project's settings and trust; --session with another project's session offers to fork it into the current one instead. Resuming a session whose directory no longer exists asks whether to continue in the current one.

pig stores entries as a tree, so returning to an earlier point does not erase the branch you leave.

Action	Result	Use it when
/tree	Moves within the current session file	Related alternatives should stay together
/fork	Creates a new session from an earlier user message	The alternative should become separate work
/clone	Copies the active branch into a new session	You want a separate copy of the current state

In /tree, select a user message to put its text back in the editor. Edit and submit it to create another branch. Selecting an assistant response or another entry continues after that entry with an empty editor.

When you leave a branch, pig can summarize it and attach that summary to the branch you enter. This preserves relevant work from the abandoned path without including every message from it.

For the persisted tree and entry types, see Session Format.

The model receives the active branch, not every branch in the session file. pig combines that history with the system prompt, discovered context files, available tools, and loaded skill descriptions. How pig Works describes how those inputs are assembled.

The footer shows current context usage. When the active context approaches the model's limit, pig normally compacts older history automatically. Compaction adds a summary and keeps recent messages. It does not delete the original session entries.

Run /compact to compact manually. You can add instructions when the summary should preserve a particular topic or decision. Configure automatic compaction and retained history through Settings.

Compaction can fail if the provider is unavailable or cannot accept the summarization request. Correct the provider problem and run /compact again. Disabling automatic compaction does not disable the manual command.

See Compaction Reference for thresholds, retained boundaries, branch-summary behavior, and extension hooks.

By default, pig stores sessions under ~/.pig/agent/sessions/, grouped by working directory. Use --session-dir, PIG_CODING_AGENT_SESSION_DIR, or the sessionDir setting to choose another location. The CLI option has highest precedence.

Use --no-session for an ephemeral run. An ephemeral session still has an ID (set it with --session-id) but cannot be resumed after pig exits.

Use --session when you already know the session path or ID, and --session-id to open or create a session with an exact ID. Use --fork to create a new session from an existing session before interactive mode starts. /import <path> copies a JSONL session file into the current project's session directory and resumes it.

Use /export to write the current session as HTML or JSONL (/export md and /export pr write Markdown or a pull-request description). Use /share to upload it and get a viewer link: pig checks gh auth status, renders the session as HTML, and uploads it as a secret GitHub gist with gh gist create. The link is the gist ID appended to PIG_SHARE_VIEWER_URL (default https://pigagent.dev/session/). /share needs the GitHub CLI signed in.

Review exported or shared sessions first. They can contain prompts, model responses, tool arguments, command output, file contents, and extension messages.

Run /bug [description] to prepare a private report for the pig developers. You can include the session transcript, omit it, or ask the current model to summarize the problem. Review any transcript or generated summary because it can contain sensitive conversation data.

The report includes the pig version, operating system, PHP version, the current model and provider (without credential values), the last provider error, recent crashes, and /doctor's findings. Choose Upload to send it to https://pigagent.dev/api/bug-reports, or Export as Zip to write pig-bug-report-<id>.zip to the current directory (with report.md, plus session.jsonl or summary.md when included) to inspect and share yourself. Uploads need no login and are refused while PIG_OFFLINE is set. If an upload fails, pig offers to export the zip. Either way the session records a pig.bug-report entry.