Sessioner

✨ An interactive CLI to navigate and manage Claude Code sessions from the terminal.

---

💡 Why

Claude Code supports native forking from specific points, but can loses context like thoughts, references, choices, and subagents. It also provides no built-in way to search, browse, merge, prune, or trim sessions.

Sessioner gives you a keyboard-driven interface to manage those sessions directly, including a full fork that preserves subagents and all session data:

• Browse all sessions in a project, sorted by date
• Search text across all sessions with highlighted results
• Preview conversations before acting
• Fork, merge, prune, trim, rename, or delete sessions
• View session and project stats (duration, tokens, costs, tool usage)
• Batch-clean empty session files

---

📦 Install

npm i sessioner

---

🚀 Quick Start

sessioner

• The CLI detects your current project and opens a main menu.

Options

Flag	Short	Description	Default
--project <path>	-p	Project path	Current directory
--base <path>	-b	Agent base directory	~/.claude/projects

---

How It Works

1. Scans {base}/{project} for .jsonl session files
2. Shows a main menu (Sessions, Search, Stats, Clean)
3. Shows a paginated session list sorted by date (newest first)
4. Displays a conversation preview for the selected session (up to 10 messages)
5. Opens an action menu to operate on it

---

🛠️ Actions

Note

Actions that modify session files (fork, merge, prune, trim, rename, delete, clean) require restarting the Claude Code extension to take effect.

• In VS Code, you can use the Reload Window command (Ctrl+Shift+P / Cmd+Shift+P → Developer: Reload Window).

◌ Open

• Reveals the .jsonl session file in your native file explorer
• macOS (Finder), Windows (Explorer), and Linux (xdg-open)

---

◌ Search (across all sessions)

• Search for a text input (case-insensitive)
• Results grouped by session title, with match count and date
• Highlight matched text
• Paginated 10 matches at a time
• Clicking a match opens the session's action menu

---

◌ Fork

• Creates an independent copy of the entire session
• All UUIDs (messages and subagents) are remapped to forked session
• Prompts for a custom title after forking
• Switches context to the new forked session

---

◌ Merge

• Combines multiple sessions into a single new one
• Multi-select UI with checkboxes for choosing which sessions to include
• Sessions are concatenated in chronological order
• All UUIDs are remapped to avoid conflicts
• Subagent files are copied and remapped
• Prompts for a custom title after merging

---

◌ Prune

• Analyzes the session and reports what can be removed:
  • Tool blocks: tool_use and tool_result entries
  • Empty messages: no text content after tools are stripped
  • System/IDE tags: <system-reminder>, <ide_selection>, <ide_opened_file>
  • Old custom titles: duplicate custom-title entries (keeps the most recent)
  • Short messages: text under 50 characters (unselected by default)
• Provides checkbox selection for what to remove
• Repairs the parent-child UUID chain after pruning

---

◌ Trim

• Lists all messages in reverse order (newest first)
• Each line shows [ YOU ] or [ LLM ] followed by the message text
• Select the last message you want to keep
• Everything after the selected point is removed

---

◌ Stats

🚧 WIP

• Session stats (from the action menu): statistics for a single session
• Project stats (from the main menu): aggregated statistics across all sessions
• Both display:
  • Duration (time between first and last message)
  • Message counts (user vs assistant)
  • Token usage (input, output, cache creation, cache read)
  • Cost breakdown by model
  • Tool usage frequency
  • Subagent count
• Project stats also shows the total session count

---

◌ Rename

• Text input for the new title (Esc to cancel)
• Writes a custom-title entry to the session file (same format used by the Claude Code extension)

---

◌ Delete

• Shows exactly what will be deleted:
  • Session .jsonl file
  • Subagents directory (with file count)
• Removes the entry from the sessions index

---

◌ Clean (main menu)

• Batch-deletes empty session files
• Only appears when empty files exist
• Shows the count of empty sessions

---

⌨️ Navigation

• Up / Down: move cursor
• Enter: confirm
• 0: exit
• ESC: go back one level at a time until exit
• Ctrl+C: exit

---

Security Policy

Please check the SECURITY.md.

---

Contributing

See the Contributing Guide and please follow our Code of Conduct 🚀

---

Acknowledgements

---

License

Sessioner is under the MIT License.