Sessions

A session is a saved conversation with its working-directory and model state. Interactive work is persisted so you can return to it after leaving the agent. The harness uses local PostgreSQL-backed storage; a saved session is not an off-machine backup of your project.

Resume previous work

Inside the agent:

/resume

This opens the session picker in a terminal. If you already have an identifier:

agent-cli --resume SESSION_ID

Use /session to print the current identifier or /copy-session to copy it. /search <query> searches previous conversations and lets you resume a match. /home returns to the session picker.

Give a session a useful title

A descriptive title makes the picker useful when several conversations concern the same repository.

/rename Project name validation

/rename --auto restores automatic naming. The title model is independent of the coding model: /title-model selects it and /title-model --auto restores automatic selection. On supported Macs, automatic naming uses on-device Apple Intelligence when available and falls back when it cannot be used.

/title is an alias for /rename. A manual title may contain at most 100 characters; use a short distinguishing description rather than pasting the task specification.

Example: return to an unfinished task

1. Run /rename Project name validation, then /session. Save the displayed identifier somewhere private.
2. Ask: Summarize the current findings and remaining checks. Do not make further changes.
3. Exit with /quit. Later run agent-cli --resume SESSION_ID in your shell, replacing the placeholder with the saved identifier.
4. Run /session again and confirm it matches before continuing.

Expected result: the saved conversation is available in the resumed session. Inspect the current files before relying on an earlier test result: other tools or people may have changed the checkout while you were away. If you lost the identifier, use /resume and look for the title rather than starting over with /delete.

Start over without confusing the operations

Do not use /delete when you merely want to leave a session; use /quit. These are conversation operations, not a general undo for filesystem changes.

Rewind safely, or permanently delete

Run /rewind (alias /undo) to select an earlier user prompt. The conversation is restored to immediately before that prompt, later turns are removed, and the chosen prompt becomes an editable draft. It is not sent automatically. The confirmation defaults to cancel. Files are unchanged. Inspect /diff before resubmitting: repeating an edit or an external mutation can duplicate work.

For example, rewind an overly broad request, narrow the returned draft to one file, inspect existing changes, then send it. If you only want to reuse wording, choose /history or /edit-prompt instead of discarding turns.

/delete asks for confirmation and defaults to cancellation. Confirming permanently removes the current transcript and session-local artifacts, then starts a new session. Export anything you need before confirming. This is not an archive or a reversible way to close a tab. It does not revert project files or undo actions at external services.

When resuming does not work

Use agent-cli sessions list to check the identifier and the account's local session store. Do not substitute a title for an identifier. If a managed checkout was collected, resuming can restore it; if the original shared repository or registry is missing, restore those from your backups rather than creating an unrelated repository at the same path. An existing directory blocks restoration to prevent overwriting it. See worktree recovery.

Keep a session in tmux

/afk starts a detached local tmux session using the current agent executable. It waits for the original session to release its run lock before resuming. Install tmux first; use the exact tmux attach -t NAME command printed on success to reconnect.

/afk build-host:/absolute/path/to/project

Remote handoff requires working SSH access, tar, remote agent-cli, and remote tmux. The destination project directory must already exist and contain the files needed for the task. Handoff transfers the conversation and session artifacts, not the project checkout or provider credentials. Authorize the remote agent separately. The destination is HOST:PATH, not a URL.

Session artifacts can contain private data. Use only a trusted destination. After success, use the printed SSH/tmux attach command. If upload, import, or tmux startup fails, read the reported stage, inspect whether a remote session already exists, and reconnect rather than blindly repeating the transfer. Handoff is multi-step, not an atomic migration; a failed attempt may leave staged artifacts or an imported session on the host.

Manage long conversations

/context shows context-window usage and estimates. /compact summarizes history to free model context:

/compact Preserve the API decisions, modified files, and remaining test failures.

Compaction behavior depends on the provider. Custom portable models need a configured context-window limit so the harness can bound the summary request; it does not guess this limit. A summary can omit details, so keep durable requirements in project files rather than only in a long conversation.

Browse and search saved conversations

/resume without an ID and /home (alias /welcome) open the same session browser. Opening it does not itself start a fresh conversation or clear saved history. Cancel to keep the current session; selecting the already-active ID reports that you are already on it. A failed load or rejected organization-identity boundary leaves you in the current conversation. Copy important unsent draft text before deliberately switching sessions rather than treating drafts as exported history.

/search parser regression

This searches indexed conversation turns within the current local/organization boundary, rather than searching repository files. Select the desired result to resume it, then inspect /session-info before continuing. The query requests up to 100 search results; it is not an unbounded export. No matches reports no conversations matched and keeps the current session. Use /find instead to search only the active saved transcript.

Interpret session information

/context reports the active model, used tokens, known window and free space, plus an estimated breakdown for instructions, messages, tool schemas and other overhead. A line such as Used: 12000 tokens (estimated) is an illustrative local estimate, not a provider bill. The label provider reported is used only while that occupancy snapshot still matches committed history; otherwise the serialized request is estimated again. Breakdown entries remain estimates even when the headline is provider-reported. An unknown model window yields unknown capacity/free-space fields rather than an invented limit.

/session-info, /status and /info report the session ID, persistence state, optional title, provider, connection, model, dialect, effort, working directory, shell mode, token usage and registered tool names. pending means an ID is reserved but persistence is not yet active; active means the session has a persisted handle; not_persisted means persistence is disabled. Check connection as well as provider before sending confidential work: the transport name alone does not identify the endpoint.

/clear retains this identity but records a transcript-reset marker and resets the current provider conversation, task plan, token counters and recap metadata. It is not secure erasure of historical storage. If the persistent write fails, the command reports could not clear conversation and does not proceed with the normal in-memory reset. Resolve the storage error rather than assuming the conversation was cleared.

Export a conversation

/export /absolute/path/to/conversation.md

Without a path, /export offers copying Markdown or saving a file. The suggested filename is agent-session-<session-id>.md. Relative paths are resolved against the current working directory. Saving never overwrites an existing file: choose a new filename when it reports a collision. A failed write reports the destination and error; fix the directory or permissions before retrying. Export requires an active persisted session and exports its visible transcript, not a portable session-import archive.

Review exports before sharing: prompts, tool results, and source excerpts may contain confidential material.

For a one-shot command, opt into persistence:

agent-cli --save-session -p "Review the current changes without modifying files."