sessioner - GitLite

KO | EN

gitlite — search

#cpp #agent #animation #json #gemini #devops #react-native #css #computer-vision #monitoring

sessioner

(★ 14)

✨ An interactive CLI to search, fork, merge, prune, trim, and manage Claude Code sessions from the terminal.

File Explorer

ZIP Download

- - architecture.md
  - conventions.md
  - typings.md
- - config.json
  - manifest.json
- - bot_stale.yml
  - cd_deploy.yml
  - ci_build.yml
  - ci_lint.yml
- FUNDING.yml
- settings.json
- - delete.ts
  - fork.ts
  - merge.ts
  - open.ts
  - preview.ts
  - prune.ts
  - rename.ts
  - trim.ts
- - index.ts
- - ansi.ts
  - format-date.ts
  - format-stats.ts
  - get-columns.ts
  - styled-label.ts
  - truncate.ts
- - analyze-prune.ts
  - count-subagents.ts
  - extract-first-user-message.ts
  - extract-messages.ts
  - get-entries.ts
  - list-sessions.ts
  - parse-line.ts
  - rewrite-jsonl.ts
  - search-sessions.ts
  - stats.ts
- - custom-select.ts
  - layout.ts
  - search.ts
  - select.ts
- types.ts
.gitattributes
.gitignore
.prettierignore
.prettierrc
CHANGELOG.md
CLAUDE.md
CODE_OF_CONDUCT.md
CONTRIBUTING.md
LICENSE
package-lock.json
package.json
README.md
SECURITY.md
tsconfig.json

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

Command Glossary

Commands referenced in this DOCs, explained below.

🔍

`npm`

View Details ▼

JavaScript and Node.js package manager.
Manage Node.js projects and their module dependencies.
Some subcommands such as `install`, `run`, etc. have their own usage documentation.

npm init {{[-y|--yes]}}

Create a `package.json` file with default values (omit `--yes` to do it interactively):

npm {{[i|install]}}

Download all the packages listed as dependencies in `package.json`:

npm {{[i|install]}} {{package_name}}@{{version}}

Download a specific version of a package and add it to the list of dependencies in `package.json`:

🔍

`xdg-open`

View Details ▼

Open a file or URL in the user's preferred application.

xdg-open .

Open the current directory in the default file explorer:

xdg-open {{https://example.com}}

Open a URL in the default browser:

xdg-open {{path/to/image}}

Open an image in the default image viewer:

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

✨ An interactive **CLI** to navigate and manage [**Claude Code**](https://docs.anthropic.com/en/docs/claude-code) sessions from the terminal.

[![NPM Version](https://img.shields.io/npm/v/sessioner.svg?label=&color=70a1ff&logo=npm&logoColor=white)](https://www.npmjs.com/package/sessioner)

---

## 💡 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

```bash
npm i sessioner
```

---

## 🚀 Quick Start

```bash
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 (<kbd>Ctrl+Shift+P</kbd> / <kbd>Cmd+Shift+P</kbd> → `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 (<kbd>Esc</kbd> 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

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

---

## Security Policy

Please check the [**SECURITY.md**](https://github.com/wellwelwel/sessioner/blob/main/SECURITY.md).

---

## Contributing

See the [**Contributing Guide**](https://github.com/wellwelwel/sessioner/blob/main/CONTRIBUTING.md) and please follow our [**Code of Conduct**](https://github.com/wellwelwel/sessioner/blob/main/CODE_OF_CONDUCT.md) 🚀

---

## Acknowledgements

[![Contributors](https://img.shields.io/github/contributors/wellwelwel/sessioner?label=Contributors)](https://github.com/wellwelwel/sessioner/graphs/contributors)

---

## License

**Sessioner** is under the [**MIT License**](https://github.com/wellwelwel/sessioner/blob/main/LICENSE).