sessioner 0.1.0

package/README.md

@@ -0,0 +1,251 @@
+<div align="center">
+
+# Sessioner
+
+✨ 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)
+
+</div>
+
+> 🚧 Work in Progress
+
+---
+
+## 💡 Why
+
+Claude Code supports native forking from specific points, but loses context like thoughts, references, choices, and subagents. It also provides no built-in way to browse, merge, prune, or trim the `.jsonl` session files stored in `~/.claude/projects`.
+
+**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
+- 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
+```
+
+> Requires **Node.js >= 22**.
+
+---
+
+## 🚀 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, 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
+
+### Open
+
+- Reveals the `.jsonl` file in your native file explorer
+- macOS (Finder), Windows (Explorer), and Linux (xdg-open)
+
+---
+
+### Stats
+
+- **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
+
+---
+
+### Fork
+
+- Creates an independent copy of the entire session
+- All UUIDs (messages and subagents) are remapped to new random values
+- 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
+  - **Short messages**: text under 50 characters
+  - **System/IDE tags**: `<system-reminder>`, `<ide_selection>`, `<ide_opened_file>`
+- Checkbox selection for what to remove (all pre-selected by default)
+- Repairs the parent-child UUID chain after pruning
+- Shows "Nothing to prune" when the session is already clean
+
+---
+
+### 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
+- Confirmation prompt before applying
+
+---
+
+### Rename
+
+- Text input for the new title (<kbd>Esc</kbd> to cancel)
+- Updates three locations:
+  - Session file (prepends a `session_title` line)
+  - Sessions index (`sessions-index.json`)
+  - First user message (injects title into metadata)
+- Tracks renames in a local cache (`.cache/renames.json`)
+
+---
+
+### Delete
+
+- Shows exactly what will be deleted:
+  - Session `.jsonl` file
+  - Subagents directory (with file count)
+- Removes the entry from the sessions index and rename cache
+- Confirmation prompt before applying
+
+---
+
+### Clean (main menu)
+
+- Batch-deletes empty session files
+- Only appears when empty files exist
+- Shows the count of empty sessions
+- Confirmation prompt before applying
+
+---
+
+## ⌨️ Navigation
+
+---
+
+### Main Menu
+
+- <kbd>Up</kbd> / <kbd>Down</kbd>: move cursor
+- <kbd>Enter</kbd>: confirm
+- <kbd>1</kbd>–<kbd>N</kbd>: select option by number
+- <kbd>0</kbd>: exit
+
+---
+
+### Session List
+
+- <kbd>Up</kbd> / <kbd>Down</kbd>: move cursor
+- <kbd>Enter</kbd>: select session
+- `←` Previous: previous page
+- `→` Next: next page
+- `☰` Back to menu: return to main menu
+- `✕` Exit: exit
+
+---
+
+### Action Menu
+
+- <kbd>Up</kbd> / <kbd>Down</kbd>: move cursor
+- <kbd>Enter</kbd>: confirm action
+- <kbd>1</kbd>–<kbd>8</kbd>: select action by number
+- <kbd>9</kbd>: back
+- <kbd>0</kbd>: exit
+
+---
+
+### Multi-Select (Merge / Prune)
+
+- <kbd>Enter</kbd>: toggle item (`☑` selected, `☐` unselected)
+- `✓` Confirm: confirm selection
+- `✕` Cancel: cancel
+
+---
+
+### Confirmation (Clean / Trim / Delete)
+
+- <kbd>Up</kbd> / <kbd>Down</kbd>: move cursor
+- <kbd>Enter</kbd>: confirm selection
+- <kbd>y</kbd>: yes
+- <kbd>n</kbd>: no
+- <kbd>1</kbd>: yes
+- <kbd>2</kbd>: no
+
+---
+
+### Text Input (Rename)
+
+- Type the new title
+- <kbd>Enter</kbd>: confirm
+- <kbd>Esc</kbd>: cancel
+
+---
+
+### Global
+
+- <kbd>ESC</kbd>: go back one level at a time until exit
+- <kbd>Ctrl+C</kbd>: exit
+
+---
+
+## 💻 Development
+
+```bash
+git clone https://github.com/wellwelwel/sessioner
+cd sessioner
+npm install
+npm start
+```
+
+- `npm start`: run the CLI
+- `npm run typecheck`: type-check without emitting
+- `npm run lint`: check formatting
+- `npm run lint:fix`: fix formatting
+
+---
+
+## ⚖️ License
+
+**Sessioner** is under the [**MIT License**](https://github.com/wellwelwel/sessioner/blob/main/LICENSE).

package/lib/actions/delete.d.ts

@@ -0,0 +1,4 @@
+import type { Session } from '../types.js';
+export declare const targets: (session: Session) => Promise<string[]>;
+export declare const cleanEmpty: (files: string[]) => Promise<void>;
+export declare const remove: (session: Session) => Promise<void>;

package/lib/actions/delete.js

@@ -0,0 +1,57 @@
+import { readFile, rm, unlink, writeFile } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import { readCache, writeCache } from '../helpers/rename-cache.js';
+import { countSubagents } from '../sessions/count-subagents.js';
+export const targets = async (session) => {
+    const name = basename(session.file);
+    const count = await countSubagents(session);
+    const items = [name];
+    if (count > 0)
+        items.push(`${count} subagent files`);
+    return items;
+};
+const removeFromIndex = async (session) => {
+    const path = join(dirname(session.file), 'sessions-index.json');
+    try {
+        const raw = await readFile(path, 'utf-8');
+        const index = JSON.parse(raw);
+        const before = index.entries.length;
+        index.entries = index.entries.filter((entry) => entry.sessionId !== session.id);
+        if (index.entries.length < before) {
+            await writeFile(path, JSON.stringify(index, null, 2));
+        }
+    }
+    catch { }
+};
+const removeFromCache = async (session) => {
+    try {
+        const cache = await readCache();
+        if (!(session.file in cache))
+            return;
+        delete cache[session.file];
+        await writeCache(cache);
+    }
+    catch { }
+};
+export const cleanEmpty = async (files) => {
+    for (const file of files) {
+        const id = basename(file, '.jsonl');
+        const subagentDir = join(dirname(file), id);
+        try {
+            await unlink(file);
+            await rm(subagentDir, { recursive: true, force: true });
+        }
+        catch { }
+    }
+};
+export const remove = async (session) => {
+    const id = basename(session.file, '.jsonl');
+    const subagentDir = join(dirname(session.file), id);
+    try {
+        await unlink(session.file);
+        await rm(subagentDir, { recursive: true, force: true });
+    }
+    catch { }
+    await removeFromIndex(session);
+    await removeFromCache(session);
+};

package/lib/actions/fork.d.ts

@@ -0,0 +1,2 @@
+import type { Session } from '../types.js';
+export declare const fork: (session: Session, title: string) => Promise<Session>;

package/lib/actions/fork.js

@@ -0,0 +1,30 @@
+import { randomUUID } from 'node:crypto';
+import { cp, rename as fsRename, readdir, readFile, writeFile, } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import { rewriteJsonl } from '../sessions/rewrite-jsonl.js';
+export const fork = async (session, title) => {
+    const id = randomUUID();
+    const dir = dirname(session.file);
+    const file = join(dir, `${id}.jsonl`);
+    const sourceId = basename(session.file, '.jsonl');
+    const raw = await readFile(session.file, 'utf-8');
+    const sourceDir = join(dir, sourceId);
+    const targetDir = join(dir, id);
+    await writeFile(file, rewriteJsonl(raw, id));
+    try {
+        await cp(sourceDir, targetDir, { recursive: true });
+        const subagentsDir = join(targetDir, 'subagents');
+        const entries = await readdir(subagentsDir);
+        for (const entry of entries) {
+            if (!entry.endsWith('.jsonl'))
+                continue;
+            const path = join(subagentsDir, entry);
+            const subagentId = randomUUID();
+            const content = await readFile(path, 'utf-8');
+            await writeFile(path, rewriteJsonl(content, subagentId));
+            await fsRename(path, join(subagentsDir, `${subagentId}.jsonl`));
+        }
+    }
+    catch { }
+    return { id, date: '', message: title, file };
+};

package/lib/actions/merge.d.ts

@@ -0,0 +1,2 @@
+import type { Session } from '../types.js';
+export declare const merge: (sessions: Session[], title: string) => Promise<Session>;

package/lib/actions/merge.js

@@ -0,0 +1,106 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import { rewriteJsonl } from '../sessions/rewrite-jsonl.js';
+const buildUuidMap = (lines) => {
+    const uuidMap = new Map();
+    for (const line of lines) {
+        if (!line.trim())
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (parsed.type === 'session_title')
+                continue;
+            if (parsed.uuid)
+                uuidMap.set(parsed.uuid, randomUUID());
+        }
+        catch { }
+    }
+    return uuidMap;
+};
+const remapSession = (lines, uuidMap, sessionId, previousLastUuid) => {
+    const mapped = [];
+    let lastUuid;
+    for (const line of lines) {
+        if (!line.trim())
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (parsed.type === 'session_title')
+                continue;
+            if (parsed.uuid) {
+                const newUuid = uuidMap.get(parsed.uuid);
+                if (newUuid) {
+                    parsed.uuid = newUuid;
+                    lastUuid = newUuid;
+                }
+            }
+            if (parsed.parentUuid) {
+                const remapped = uuidMap.get(parsed.parentUuid);
+                parsed.parentUuid = remapped ?? previousLastUuid ?? randomUUID();
+            }
+            else if (previousLastUuid && parsed.uuid) {
+                parsed.parentUuid = previousLastUuid;
+            }
+            if (parsed.sessionId)
+                parsed.sessionId = sessionId;
+            mapped.push(JSON.stringify(parsed));
+        }
+        catch {
+            mapped.push(line);
+        }
+    }
+    return { mapped, lastUuid };
+};
+const mergeJsonl = (contents, sessionId) => {
+    const allLines = [];
+    let lastUuid;
+    for (const content of contents) {
+        const lines = content.split('\n');
+        const uuidMap = buildUuidMap(lines);
+        const result = remapSession(lines, uuidMap, sessionId, lastUuid);
+        allLines.push(...result.mapped);
+        if (result.lastUuid)
+            lastUuid = result.lastUuid;
+    }
+    return allLines.join('\n');
+};
+const copySubagents = async (sourceSessions, targetDir) => {
+    const subagentsDir = join(targetDir, 'subagents');
+    for (const session of sourceSessions) {
+        const sourceId = basename(session.file, '.jsonl');
+        const sourceSubagents = join(dirname(session.file), sourceId, 'subagents');
+        try {
+            const entries = await readdir(sourceSubagents);
+            for (const entry of entries) {
+                if (!entry.endsWith('.jsonl'))
+                    continue;
+                const sourcePath = join(sourceSubagents, entry);
+                const subagentId = randomUUID();
+                const content = await readFile(sourcePath, 'utf-8');
+                await mkdir(subagentsDir, { recursive: true });
+                const targetPath = join(subagentsDir, `${subagentId}.jsonl`);
+                await writeFile(targetPath, rewriteJsonl(content, subagentId));
+            }
+        }
+        catch { }
+    }
+};
+export const merge = async (sessions, title) => {
+    const sorted = [...sessions].sort((first, second) => first.date.localeCompare(second.date));
+    const contents = [];
+    for (const session of sorted) {
+        const raw = await readFile(session.file, 'utf-8');
+        contents.push(raw);
+    }
+    const first = sorted[0];
+    if (!first)
+        return { id: '', date: '', message: title, file: '' };
+    const id = randomUUID();
+    const dir = dirname(first.file);
+    const file = join(dir, `${id}.jsonl`);
+    const targetDir = join(dir, id);
+    await writeFile(file, mergeJsonl(contents, id));
+    await copySubagents(sorted, targetDir);
+    return { id, date: '', message: title, file };
+};

package/lib/actions/open.d.ts

@@ -0,0 +1,2 @@
+import type { Session } from '../types.js';
+export declare const open: (session: Session) => void;

package/lib/actions/open.js

@@ -0,0 +1,10 @@
+import { exec } from 'node:child_process';
+const commands = {
+    darwin: (file) => `open -R "${file}"`,
+    win32: (file) => `explorer /select,"${file}"`,
+};
+const fallback = (file) => `xdg-open "${file}"`;
+export const open = (session) => {
+    const build = commands[process.platform] ?? fallback;
+    exec(build(session.file));
+};

package/lib/actions/preview.d.ts

@@ -0,0 +1,2 @@
+import type { Session } from '../types.js';
+export declare const preview: (session: Session, limit?: number) => Promise<string[]>;

package/lib/actions/preview.js

@@ -0,0 +1,56 @@
+import { createReadStream } from 'node:fs';
+import { createInterface } from 'node:readline';
+import { bold } from '../helpers/ansi.js';
+import { getColumns } from '../helpers/get-columns.js';
+import { truncate } from '../helpers/truncate.js';
+import { parseLine } from '../sessions/parse-line.js';
+const ROLE_LENGTH = 7; // "[ YOU ]" / "[ LLM ]"
+const PREVIEW_MARGIN = 10;
+const PREFIX_LENGTH = 2 + ROLE_LENGTH + 1 + PREVIEW_MARGIN;
+const PREVIEW_LIMIT = 10;
+const MIN_TEXT_LENGTH = 5;
+export const preview = (session, limit = PREVIEW_LIMIT) => new Promise((resolve) => {
+    const stream = createReadStream(session.file, 'utf-8');
+    const reader = createInterface({ input: stream, crlfDelay: Infinity });
+    const messages = [];
+    const columns = getColumns();
+    const close = () => {
+        resolve(messages);
+        reader.close();
+        stream.destroy();
+    };
+    reader.on('line', (line) => {
+        if (!line.trim())
+            return;
+        if (messages.length >= limit) {
+            close();
+            return;
+        }
+        const entry = parseLine(line);
+        if (!entry)
+            return;
+        if (entry.type === 'session_title')
+            return;
+        const texts = entry.message?.content ?? [];
+        for (const block of texts) {
+            if (block.type !== 'text' || !block.text)
+                continue;
+            const text = block.text
+                .replace(/\r?\n/g, ' ')
+                .trim()
+                .replace(/ {2,}/g, ' ');
+            if (text.startsWith('<'))
+                continue;
+            if (text.length <= MIN_TEXT_LENGTH)
+                continue;
+            const tag = entry.type === 'user' ? '[ YOU ]' : '[ LLM ]';
+            const role = bold(tag);
+            const available = columns - PREFIX_LENGTH;
+            const truncated = available > 0 ? truncate(text, available).trimEnd() : text;
+            messages.push(`  ${role} ${truncated}`);
+            break;
+        }
+    });
+    reader.on('close', () => resolve(messages));
+    stream.on('error', () => close());
+});

package/lib/actions/prune.d.ts

@@ -0,0 +1,2 @@
+import type { PruneOptions, Session } from '../types.js';
+export declare const prune: (session: Session, options: PruneOptions) => Promise<void>;

package/lib/actions/prune.js

@@ -0,0 +1,103 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { hasContent, isToolBlock, MIN_TEXT_LENGTH, SYSTEM_TAGS, textLength, } from '../sessions/analyze-prune.js';
+const stripTagsFromText = (text) => {
+    let result = text;
+    for (const tag of SYSTEM_TAGS) {
+        const open = `<${tag}>`;
+        const close = `</${tag}>`;
+        scan: while (true) {
+            const start = result.indexOf(open);
+            if (start === -1)
+                break scan;
+            const end = result.indexOf(close, start + open.length);
+            if (end === -1)
+                break scan;
+            result = result.slice(0, start) + result.slice(end + close.length);
+        }
+    }
+    return result;
+};
+const stripSystemTags = (blocks) => {
+    const result = [];
+    for (const block of blocks) {
+        if (block.type !== 'text' || !block.text) {
+            result.push(block);
+            continue;
+        }
+        const stripped = stripTagsFromText(block.text).trim();
+        if (!stripped)
+            continue;
+        result.push({ ...block, text: stripped });
+    }
+    return result;
+};
+const filterContent = (content, options) => {
+    let filtered = content;
+    if (options.toolBlocks) {
+        filtered = filtered.filter((block) => !isToolBlock(block));
+    }
+    if (options.systemTags) {
+        filtered = stripSystemTags(filtered);
+    }
+    return filtered;
+};
+const shouldSkipMessage = (type, content, options) => {
+    if (options.emptyMessages && content.length === 0)
+        return true;
+    if (options.shortMessages &&
+        type === 'assistant' &&
+        textLength(content) < MIN_TEXT_LENGTH)
+        return true;
+    return false;
+};
+const repairParentChain = (lines, survivingUuids) => {
+    let lastUuid;
+    return lines.map((line) => {
+        try {
+            const parsed = JSON.parse(line);
+            if (!parsed.uuid)
+                return line;
+            if (parsed.parentUuid && !survivingUuids.has(parsed.parentUuid)) {
+                parsed.parentUuid = lastUuid ?? parsed.parentUuid;
+                lastUuid = parsed.uuid;
+                return JSON.stringify(parsed);
+            }
+            lastUuid = parsed.uuid;
+            return line;
+        }
+        catch {
+            return line;
+        }
+    });
+};
+export const prune = async (session, options) => {
+    const raw = await readFile(session.file, 'utf-8');
+    const lines = raw.split('\n');
+    const kept = [];
+    const survivingUuids = new Set();
+    for (const line of lines) {
+        if (!line.trim())
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (hasContent(parsed)) {
+                const content = filterContent(parsed.message.content, options);
+                if (shouldSkipMessage(parsed.type, content, options))
+                    continue;
+                parsed.message.content = content;
+                if (parsed.uuid)
+                    survivingUuids.add(parsed.uuid);
+                kept.push(JSON.stringify(parsed));
+                continue;
+            }
+            if (parsed.uuid)
+                survivingUuids.add(parsed.uuid);
+            kept.push(line);
+        }
+        catch {
+            kept.push(line);
+        }
+    }
+    const repaired = repairParentChain(kept, survivingUuids);
+    await writeFile(session.file, repaired.join('\n') + '\n');
+};

package/lib/actions/rename.d.ts

@@ -0,0 +1,2 @@
+import type { Session } from '../types.js';
+export declare const rename: (session: Session, title: string) => Promise<void>;