Agent Session Manager

A terminal-based session manager for Claude Code sessions.

Features

• Session Overview: Display all Claude Code sessions with project info, date, and message count
• Quick Navigation: Switch between sessions easily with arrow keys and Enter
• Sortable Columns: Sort by project name, message count, or date
• Search: Find sessions quickly with f
• Message Preview: Show conversation content with scrollable preview
• Session Export: Export sessions as Markdown files to a configurable path
• Settings: Configure export path via g, persisted across sessions
• Trash System: Safely delete and restore sessions
• Parallel Loading: Fast loading of large session sets with multi-threading
• TUI Interface: Intuitive terminal interface with ratatui

Screenshots

The tool provides two tabs:

• Sessions Tab: Overview of all active sessions
• Trash Tab: Deleted sessions for recovery

Installation

Requirements

• Rust 1.70+ and Cargo
• Claude Code (CLI)

Build from Source

git clone https://github.com/DEIN_USERNAME/agent-session-manager.git
cd agent-session-manager
cargo build --release

The binary will be in target/release/agent-session-manager.

Optionally install to PATH:

cargo install --path .

Usage

Note: agent-session-manager is currently designed to work exclusively with Claude Code. It reads session data from Claude Code's internal directories and manages sessions created through Claude Code only.

Simply run:

agent-session-manager

Keyboard Shortcuts

Key	Function
↑ / ↓	Select session (list) / scroll preview (line by line)
← / →	Switch focus between list and preview
Enter	Switch to selected session
Tab	Switch between Sessions/Trash
Ctrl+F	Open search
s	Toggle sort (Project → Msgs → Date)
S	Toggle sort direction (▲/▼)
d	Delete session (with confirmation)
y	Confirm delete
n / Esc	Cancel delete
r	Restore session from Trash
t	Empty trash (in Trash tab)
e	Export session as Markdown
g	Open settings (configure export path)
0	Move all sessions with 0 messages to trash
PgUp / PgDn	Page scroll (depending on focus)
h	Show help (README)
q / Esc	Quit

Architecture

The project uses a clean module structure:

• models.rs: Data models for sessions and messages
• store.rs: Session management and file I/O (with parallel loading via rayon)
• commands.rs: Session operations (delete, export, restore)
• config.rs: Persistent configuration (export path, config file management)
• ui.rs: TUI rendering with ratatui
• app.rs: Application logic and state management
• main.rs: Event loop and terminal setup

Development

Development Build

cargo run

Release Build

cargo build --release

Testing

The project uses a 3-layer test architecture:

Layer 1 — Unit Tests (92 tests in src/):

cargo test

Layer 2 — Integration Tests (9 tests in tests/integration.rs):

cargo test --test integration

Layer 3 — E2E TUI Tests (6 tests in tests/e2e/):

Launches the binary and interacts via keyboard input with @microsoft/tui-test (xterm.js-based, cross-platform).

cargo build                     # Binary must be built first
cd tests/e2e && npm test        # Run E2E tests

Tests generate snapshots on each run in tests/e2e/__snapshots__/sessions.test.ts.snap — ASCII representations of terminal state at each checkpoint for visual inspection.

Session Data

Sessions are read from the Claude Code session directory:

~/.claude/projects/<project-hash>/sessions/

Exported sessions go to the configured export path (default):

~/claude-exports/

The export path can be changed via g → Settings modal. The configuration is saved to:

• Linux/macOS: ~/.config/agent-session-manager/config.json
• Windows: %APPDATA%\agent-session-manager\config.json

Trash directory:

~/.claude/trash.json

Performance

The tool uses rayon for parallel loading of sessions:

• All session files are processed simultaneously by multiple threads
• Significantly faster with large session sets (100+)
• Progress bar shows loading status

Contributing

Contributions welcome! Please open an issue or pull request.

License

MIT License - see LICENSE file for details.

Acknowledgments

• Built with ratatui for the TUI
• crossterm for terminal handling
• rayon for parallel data processing
• Developed for Claude Code