agent-session-manager

Version: 0.3.1

A Rust TUI for viewing and cleaning agent sessions on local and remote machines.

The tool is built for routine maintenance: find historical sessions from Codex, Claude, Gemini, OpenCode, OpenClaw, and Hermes; inspect their messages; and permanently remove session files or SQLite records that are no longer needed.

Features

• Scan, view, search, and delete local sessions.
• Manage remote sessions through built-in SSH and SFTP support.
• Start immediately with local sessions while remote targets scan in the background.
• Detect remote host OS automatically from the remote home path.
• Support file-backed sessions and SQLite-backed sessions.
• Preview, delete, and verify one session or a marked batch of sessions.
• Quickly mark tiny throwaway sessions for safe cleanup.
• Show provider resume commands when a session format exposes one.
• Export the selected session to Markdown.
• Manage remote targets and provider path overrides inside the TUI.

Supported Providers

Provider	Default locations
Codex	~/.codex/sessions, ~/.codex/archived_sessions
Claude	~/.claude/projects, compat: ~/.claude/transcripts, ~/.claude/sessions
Gemini	~/.gemini/tmp
OpenCode	~/.local/share/opencode/storage, ~/.local/share/opencode/opencode.db
OpenClaw	~/.openclaw/agents
Hermes	~/.hermes/sessions, ~/.hermes/state.db

Remote targets use the detected remote home directory with the same provider-relative paths. Windows remotes use Windows path semantics, with paths converted to SFTP-compatible form for SFTP operations.

Requirements

• Rust toolchain
• Non-interactive SSH authentication for remote targets, such as an SSH config alias, key, or agent
• A usable known_hosts file for hosts that should already be trusted; unknown hosts are added on first connect

The application does not store SSH passwords and does not handle interactive password prompts.

Quick Start

cargo run

Build the binary:

cargo build

Run verification:

cargo fmt --check
cargo test
cargo clippy --all-targets -- -D warnings

TUI Keys

The TUI is Emacs-first: Ctrl navigation and editing keys are the primary shortcuts. Arrow keys and j/k remain available as compatibility shortcuts in non-editing lists. In Search mode, printable keys always edit the search field.

Key	Action
Ctrl+n / Down / j	Move to the next session
Ctrl+p / Up / k	Move to the previous session
/	Search
Enter	Reload messages for the current session
r	Refresh local sessions immediately and rescan remote targets in the background
p	Cycle provider filter
T	Cycle target filter
c	Find small sessions across all targets and open deletion preview
Space	Mark or unmark a session for deletion
d	Preview permanent deletion for the selected or marked sessions
R	Show the resume command for the selected session
E	Export the selected session to Markdown
t	Open remote target management
q / Ctrl+c	Quit

Search and target form editing:

Key	Action
Ctrl+a / Home	Move to the beginning of the field
Ctrl+e / End	Move to the end of the field
Ctrl+b / Left	Move back one character
Ctrl+f / Right	Move forward one character
Ctrl+d / Delete	Delete the character under the cursor
Ctrl+h / Backspace	Delete the previous character
Ctrl+k	Delete from the cursor to the end of the field
Ctrl+u	Delete from the cursor to the beginning of the field
Ctrl+w	Delete the previous word
Enter	Accept search or save the target form
Ctrl+g / Esc	Cancel the active search or form

Search result navigation:

Key	Action
Ctrl+n / Down	Move to the next filtered result
Ctrl+p / Up	Move to the previous filtered result

Deletion confirmation:

Key	Action
y	Permanently delete selected sessions
n / Ctrl+g / Esc	Cancel

Resume command dialog:

Key	Action
q / Ctrl+g / Esc	Close
c	Show a copy hint

Remote target management:

Key	Action
Ctrl+n / Down / j	Move to the next target
Ctrl+p / Up / k	Move to the previous target
n	Add a target
e / Enter	Edit a target
d	Delete a target config
q / Ctrl+g / Esc	Return to session management

Remote Targets

Press t to open target management. When adding or editing a target, fill in:

• Name: local display name
• SSH: SSH target, either user@host or an SSH config alias
• Provider root overrides: optional per-provider roots used instead of the default locations

Remote targets do not block startup. The TUI loads local sessions first, then connects to each configured remote target in a background worker. Remote targets scan concurrently with each other; providers on the same target scan serially to avoid spawning too many SSH/SFTP processes.

After saving, the background scan resolves the remote home directory and operating system over SFTP:

• /home/alice is treated as Unix.
• /C:/Users/alice is treated as Windows.

Remote targets enable all providers by default.

Provider root override semantics:

• Codex: root containing *.jsonl sessions, replacing both default Codex roots.
• Claude: either a project-session root, or the .claude base directory. The app prefers projects/, enriches metadata from sessions-index.json and history.jsonl, and also scans compatible transcripts/ and sessions/ roots.
• Gemini: replacement for ~/.gemini/tmp.
• OpenCode: either the OpenCode base directory or its storage directory. The paired opencode.db path is derived automatically.
• OpenClaw: replacement for ~/.openclaw/agents.
• Hermes: either the Hermes base directory or its sessions directory. The paired state.db path is derived automatically.

Configuration

The config file is saved to:

• Preferred: dirs::config_dir()/agent-session-manager/config.toml
• Fallback: ~/.agent-session-manager/config.toml

Example:

[[remotes]]
name = "workstation"
sshTarget = "workstation"
enabledProviders = ["codex", "claude", "gemini", "open-code", "open-claw", "hermes"]

[[remotes]]
name = "server"
sshTarget = "alice@example.com"
enabledProviders = ["codex", "claude"]

[remotes.pathOverrides]
codex = "/data/agent/codex-sessions"
claude = "/data/agent/.claude"
opencode = "/data/opencode"

The TUI writes name, sshTarget, the default provider list, and non-empty provider root overrides.

For Claude, sessions-index.json and history.jsonl are used as metadata sources and are not listed as standalone sessions.

Delete Semantics

Deletion is permanent.

Before deletion, the TUI shows each target, provider, session title, delete surface, and source path. File-backed sessions are deleted only after the source path is validated under the matching default or overridden provider root. SQLite-backed sessions delete the matching database records. Remote SQLite deletion downloads a temporary database copy, applies the change locally in a transaction, uploads a temporary remote file, and replaces the original database only if the remote fingerprint has not changed.

After deletion, the app rescans sessions and reports how many successful deletes were verified as absent. If the remote database changes during the operation, deletion is aborted to avoid overwriting new remote writes.

Small-session cleanup uses the same deletion path. Press c to scan all loaded local and remote sessions for conservative cleanup candidates: at most two user prompts, at most four total messages, at most 600 message characters, and no tool or attachment markers. Matching sessions are marked and shown in the normal deletion preview with the cleanup reason; unreadable sessions are skipped.

Export And Resume

E writes the selected session to Downloads/agent-session-manager when a downloads directory is available, otherwise next to the config directory. The export includes session metadata and loaded messages.

R shows the provider resume command when the provider exposes one. For remote sessions, the command is displayed as an ssh <target> '<resume command>' invocation. Clipboard integration is intentionally not bundled; copy the command manually from the dialog.

Limitations

• Session resume is displayed as a command only; the TUI does not launch it.
• SSH passwords are not stored, and interactive SSH password input is not supported.
• Remote SQLite cleanup assumes the target application is not writing to the database at the same time; concurrent changes cause the operation to fail.