mirror of
https://github.com/badlogic/pi-mono.git
synced 2026-11-05 23:37:25 +00:00
2a46c42080
Closes #11532. The docs and CLI help did not say which working directory a resumed session runs in. That directory controls tools, `@path` references, project configuration, and context files. ## Changes - `docs/sessions.md`: states that a session keeps the working directory it was created in, adds a table mapping each entry point to its working directory, and describes what happens when that directory no longer exists. Removes a paragraph that repeated the `--session`/`--fork` descriptions. - `docs/cli.md` and `--help`: clearer `--continue`, `--resume`, `--session`, `--session-id`, and `--fork` descriptions. The help only mentions the directory where it is not obvious (`--fork`). - `/resume` and `/import` command descriptions, mirrored in `docs/slash-commands.md`. `/import` notes that it preserves the session ID and working directory. | Entry point | Working directory | |---|---| | `--continue` | The current directory | | `--resume`, `/resume`, `--session`, `/import` | The session's working directory, which can differ from the current directory | | `--fork`, or a `--session` ID from another directory that you choose to fork | The current directory, in a new session | Behavior was verified against `createSessionManager` in `src/main.ts`, `SessionManager.open`/`continueRecent`/`forkFrom`, and `AgentSessionRuntime.importFromJsonl`.
74 lines
5.3 KiB
Markdown
74 lines
5.3 KiB
Markdown
# Sessions and Context
|
|
|
|
Pi 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.
|
|
|
|
## Continue or switch sessions
|
|
|
|
Pi saves sessions automatically unless you start it with `--no-session`.
|
|
|
|
```bash
|
|
pi --continue
|
|
pi --resume
|
|
```
|
|
|
|
`--continue` opens the most recent session for the current directory. `--resume` opens the session picker. In interactive mode, `/resume` opens the same picker and `/new` starts a new session.
|
|
|
|
Each session records the working directory it was created in and never changes it. Pi runs a session in its working directory, so tools, `@path` references, project configuration, and context files resolve from there.
|
|
|
|
| Entry point | Working directory |
|
|
|---|---|
|
|
| `--continue` | The current directory |
|
|
| `--resume`, `/resume`, `--session`, `/import` | The session's working directory, which can differ from the current directory |
|
|
| `--fork`, or a `--session` ID from another directory that you choose to fork | The current directory, in a new session |
|
|
|
|
If a session's working directory no longer exists, interactive mode offers to run the session in the current directory instead. Pi does not store that choice, so it asks again the next time you open the session. Other modes exit with an error.
|
|
|
|
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. It can also show paths, change sorting, and limit results to named sessions. See [Keybindings](keybindings.md#sessions) for its shortcuts.
|
|
|
|
## Choose how to branch
|
|
|
|
Pi 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, Pi 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](session-format.md).
|
|
|
|
## Manage conversation context
|
|
|
|
The model receives the active branch, not every branch in the session file. Pi combines that history with the system prompt, discovered context files, available tools, and loaded skill descriptions. [How Pi Works](how-pi-works.md#context) describes how those inputs are assembled.
|
|
|
|
The footer shows current context usage. When the active context approaches the model's limit, Pi 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](settings.md#compaction).
|
|
|
|
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](compaction.md) for thresholds, retained boundaries, branch-summary behavior, and extension hooks.
|
|
|
|
## Control session storage
|
|
|
|
By default, Pi stores sessions under `~/.pi/agent/sessions/`, grouped by working directory. Use `--session-dir`, `PI_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 cannot be resumed after Pi exits.
|
|
|
|
## Export or share a session
|
|
|
|
Use `/export` to write the current session as HTML or JSONL. Use `/share` to upload it and get a viewer link. By default, Pi uses a Radius artifact when Radius authentication is configured; otherwise, it uses a private GitHub gist. Set [`sessionShareDestination`](settings.md#sessions-and-context) to `gist` or `radius` to force one destination.
|
|
|
|
Review exported or shared sessions first. They can contain prompts, model responses, tool arguments, command output, file contents, and extension messages.
|
|
|
|
## Report a bug
|
|
|
|
Run `/bug [description]` to prepare a private report for the Pi 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 environment and provider configuration without credential values, plus recorded error diagnostics. Upload it through `radius.pi.dev` or export the same report as a zip to inspect and share yourself. Uploads do not require a login; Radius authentication attributes the report to your account so the developers can follow up. If an upload fails, Pi offers to export the zip.
|