pi-sessions
A fast terminal UI for browsing, previewing, resuming and managing pi coding agent sessions.
A fork of ccsessions by Marek Miśkiewicz, which does the same for Claude Code. The full behaviour is specified in SPECS.md; changes from ccsessions are listed in CHANGELOG.md.
Features
- Project & session browser — every pi project on your machine, newest first, with recently-active indicators (●), fork markers (⑂), message counts, token usage and cost
- Conversation preview — the tail of the active branch, rendered with
roles, Markdown for pi's replies, tool calls (⚙),
!commands (⌘) and compaction markers, without opening pi - One-key resume —
rreplaces the TUI withpi --session <file>in the session's working directory;ccopies the command to the clipboard (OSC 52) - Archive & delete — move sessions out of
pi --resume(reversibly) or delete them for good, per session or per project, with confirmation dialogs - Resizable panes — drag the bars between panes with the mouse; sizes
are remembered per layout across runs (
~/.config/pi-sessions/settings.json) - Export — Markdown with YAML front matter (ready for Quarto/Pandoc) or the raw JSONL, never overwriting an existing file
- Live document —
lkeeps_session_<id>.mdin sync with a running session, so a live-reloading renderer can show it with LaTeX rendered - Fast — session metadata is cached per file (mtime + size), scanning runs off the UI thread, previews read only the tail of large files
Requirements
- Python ≥ 3.10
- pi installed (
pion PATH — needed only for resuming) - macOS or Linux
Installation
pipx install pi-sessions-tui # or: uv tool install pi-sessions-tui
Both install the pisessions command.
Or from a clone:
git clone https://github.com/psychobarge/pi-sessions
pip install -e pi-sessions
Usage
pisessions
| Key | Action |
|---|---|
j / k / arrows |
Move within the focused pane |
Tab / Shift+Tab |
Switch panes |
r |
Resume the selected session (in place) |
c |
Copy the resume command to the clipboard |
a |
Archive ↔ restore session · archive ↔ restore project |
d |
Delete session / project (with confirmation) |
n |
Rename project (set a display alias) |
e |
Export the session (Markdown or raw JSONL) |
l |
Follow the session in a live Markdown document |
/ |
Filter the focused list (projects or sessions) |
p |
Command palette (change theme) |
Ctrl+R |
Rescan now (a rescan also runs automatically) |
q |
Quit |
a and d act on the session when the Sessions pane is focused and on
the whole project when the Projects pane is focused.
pi keeps no record of running sessions, so ● means modified in the last
PI_SESSIONS_LIVE_SECONDS seconds (default 120). Sessions marked this way
cannot be archived or deleted.
Configuration
| Variable | Default | Purpose |
|---|---|---|
PI_SESSIONS_ROOT |
pi's own (PI_CODING_AGENT_SESSION_DIR, $PI_CODING_AGENT_DIR/sessions, ~/.pi/agent/sessions) |
Where to read sessions |
PI_SESSIONS_PI_BIN |
pi |
Command used to resume |
PI_SESSIONS_RESUME_ROOT |
— | Rewrite the sessions root in resume commands, for a pi that sees it elsewhere (container) |
PI_SESSIONS_LIVE_SECONDS |
120 |
Recently-active threshold |
PI_SESSIONS_TRASH |
0 |
Delete through the trash command |
PI_SESSIONS_LIVE_DIR |
session cwd | Where live documents go (use a plain directory for Quarto projects) |
PI_SESSIONS_REFRESH_SECONDS |
10 |
Auto-refresh interval, 0 disables |
PI_SESSIONS_THEME |
saved choice, else ansi-dark |
Textual theme |
PI_SESSIONS_CODE_THEME |
follows the theme | Pygments style for code blocks |
PI_SESSIONS_NERD_FONT, PI_SESSIONS_EYE, PI_SESSIONS_EYE_OFF |
— | Live-document glyphs |
Settings and project aliases live in ~/.config/pi-sessions/, the cache in
~/.cache/pi-sessions/.
pi in a container
If pi runs in Docker with its agent directory in a named volume, the host
cannot see the sessions. Bind-mount a host directory over the container's
sessions directory (e.g. -v ~/.pi/agent/sessions:/root/.pi/agent/sessions),
then set PI_SESSIONS_RESUME_ROOT=/root/.pi/agent/sessions so resume
commands use the path pi sees.
How it works
pi stores each session as <sessions root>/--<encoded cwd>--/<timestamp>_<id>.jsonl:
a header line, then entries linked into a tree. pi-sessions reads those files
and never modifies them. Archiving a session moves it into an archived/
subdirectory, which pi does not list. Archiving a project moves its directory
to sessions-archive/ next to the sessions root. Everything happens locally;
no network requests.
Development
pip install -e . --group dev
pytest
License
1 maintainer
Metadata
1 maintainer
Release files for pi-sessions-tui 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pi_sessions_tui-0.1.0.tar.gz | 60.6 kB | With provenance | Details for pi_sessions_tui-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pi_sessions_tui-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for pi_sessions_tui-0.1.0-py3-none-any.whl |
Total release size: 99.5 kB
Release files / pi_sessions_tui-0.1.0.tar.gz
| Download URL | pi_sessions_tui-0.1.0.tar.gz |
|---|---|
| Size | 60.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8107950f6b925ebf673aa23f40db041827688109e8c4fd279771e9698bc2c495
|
|
BLAKE2b-256 checksum How to use checksums |
fdb969606e103d4a7ee888d812c44cb6132d6ac60313045a3b5032be4c187d60
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.
Transparency logRelease files / pi_sessions_tui-0.1.0-py3-none-any.whl
| Download URL | pi_sessions_tui-0.1.0-py3-none-any.whl |
|---|---|
| Size | 39.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
244f0da0d6ca6d4a3d2fca7b1f3b97970a1f7fd5852c41e0a56c2bea82e0a447
|
|
BLAKE2b-256 checksum How to use checksums |
5035a54a3adb7e8919804873f572b82fd1a97bf618813546cebf85f16c43c2e8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.
Transparency logSecurity for pi-sessions-tui 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for pi_sessions_tui-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
