@hype/clod 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,8 +1,22 @@
1
+ <div align="center">
2
+
3
+ <img src="./logo.png" width="120" height="120" alt="rock">
4
+
1
5
  # clod
2
6
 
3
7
  Terminal UI for managing Claude Code sessions.
4
8
 
5
- Browse, search, preview, resume, and delete any session from any directory.
9
+ [![npm][npm-image]][npm-url]
10
+ [![build][build-image]][build-url]
11
+
12
+ [npm-image]: https://img.shields.io/npm/v/@hype/clod.svg
13
+ [npm-url]: https://www.npmjs.com/package/@hype/clod
14
+ [build-image]: https://github.com/ungoldman/clod/actions/workflows/tests.yml/badge.svg
15
+ [build-url]: https://github.com/ungoldman/clod/actions/workflows/tests.yml
16
+
17
+ </div>
18
+
19
+ Browse, search, preview, resume, rename, and delete any session from any directory.
6
20
 
7
21
  ![clod session list](images/demo.png)
8
22
 
@@ -10,8 +24,15 @@ Like `claude -r` but better.
10
24
 
11
25
  ## Install
12
26
 
27
+ **Requirements:**
28
+
29
+ - Node 22+
30
+ - Claude Code CLI (`claude`) on PATH for resume
31
+
32
+ Install globally via your node package manager of choice:
33
+
13
34
  ```
14
- npm install -g @hype/clod
35
+ pnpm i -g @hype/clod
15
36
  ```
16
37
 
17
38
  This puts `clod` on your PATH, so you can run it from anywhere:
@@ -20,11 +41,6 @@ This puts `clod` on your PATH, so you can run it from anywhere:
20
41
  clod
21
42
  ```
22
43
 
23
- ### Requirements
24
-
25
- - Node 22+
26
- - Claude Code CLI (`claude`) on PATH for resume
27
-
28
44
  ## Usage
29
45
 
30
46
  ### Keys
@@ -36,6 +52,7 @@ clod
36
52
  | `/` | Search titles (fuzzy) and message contents |
37
53
  | `space` | Preview conversation |
38
54
  | `enter` | Resume selected session |
55
+ | `r` | Rename selected session (enter confirms, esc cancels; `←`/`→` move the cursor, `alt+←`/`→` jump by word) |
39
56
  | `u` | Usage dashboard (token counts) |
40
57
  | `s` | Cycle sort: recent → lexicographic → by directory |
41
58
  | `D` | Delete (moves to Trash; includes tasks, file-history, session-env, debug/telemetry, and history.jsonl prompt lines) |
@@ -107,3 +124,5 @@ Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines
107
124
  ## License
108
125
 
109
126
  [ISC](LICENSE)
127
+
128
+ Logo is the rock emoji, rendered locally from the system Apple Color Emoji font.
package/dist/list.js CHANGED
@@ -4,6 +4,9 @@ const sessionIdAt = (items, i) => items[i].session.sessionId;
4
4
  // below these widths a column is hidden rather than truncated into noise
5
5
  export const BRANCH_MIN = 8;
6
6
  export const DIR_MIN = 10;
7
+ export function termSize(stdout) {
8
+ return { width: stdout?.columns || 80, height: stdout?.rows || 24 };
9
+ }
7
10
  export function truncate(str, max) {
8
11
  if (!str)
9
12
  return '';
package/dist/sessions.js CHANGED
@@ -1,4 +1,4 @@
1
- import { readdir, readFile, stat, writeFile } from 'node:fs/promises';
1
+ import { appendFile, readdir, readFile, stat, writeFile } from 'node:fs/promises';
2
2
  import { homedir } from 'node:os';
3
3
  import { basename, join } from 'node:path';
4
4
  import { trashPaths } from "./trash.js";
@@ -263,6 +263,17 @@ export async function getSessionMessages(filePath) {
263
263
  return [];
264
264
  }
265
265
  }
266
+ // Rename by appending the records Claude Code's /rename writes; the last one
267
+ // wins on parse. custom-title feeds the resume picker, agent-name the title
268
+ // shown inside a resumed session.
269
+ export async function renameSession(filePath, title) {
270
+ const sessionId = basename(filePath, '.jsonl');
271
+ const records = [
272
+ { type: 'custom-title', customTitle: title, sessionId },
273
+ { type: 'agent-name', agentName: title, sessionId }
274
+ ];
275
+ await appendFile(filePath, records.map((r) => `${JSON.stringify(r)}\n`).join(''));
276
+ }
266
277
  // Trash everything Claude Code keys by session id under ~/.claude, plus the
267
278
  // session's history.jsonl lines. Goes to Trash (recoverable). Skips plans/ and
268
279
  // paste-cache/ (shared) and sessions/<pid>.json (ephemeral).
package/dist/ui.js CHANGED
@@ -1,8 +1,8 @@
1
1
  import { Box, Text, useApp, useInput, useStdout } from 'ink';
2
2
  import React from 'react';
3
3
  import { saveConfig } from "./config.js";
4
- import { buildDisplayItems, computeNavigate, computePage, computeRowLayout, ctxStr, filterItems, findAdjacentSessionId, nextSortMode, pad, truncate, usedStr } from "./list.js";
5
- import { deleteSession, fmtTokens, getSessionMessages, MONTHS, relativeTime, shortPath } from "./sessions.js";
4
+ import { buildDisplayItems, computeNavigate, computePage, computeRowLayout, ctxStr, filterItems, findAdjacentSessionId, nextSortMode, pad, termSize, truncate, usedStr } from "./list.js";
5
+ import { deleteSession, fmtTokens, getSessionMessages, MONTHS, relativeTime, renameSession, shortPath } from "./sessions.js";
6
6
  import { bar, computeStats, sparkline } from "./stats.js";
7
7
  const h = React.createElement;
8
8
  const { useState, useEffect, useMemo, memo } = React;
@@ -28,20 +28,68 @@ const SessionRow = memo(function SessionRow({ session, selected, termWidth, sort
28
28
  }
29
29
  return h(Box, { flexDirection: 'row' }, h(Text, {}, ' '), h(Text, {}, title), branchCol ? h(Text, { color: 'yellow', dimColor: true }, ` ${branchCol}`) : null, dirCol ? h(Text, { color: 'cyan', dimColor: true }, ` ${dirCol}`) : null, h(Text, { dimColor: true }, ` ${usedCol}`), h(Text, { color: 'green', dimColor: true }, ` ${ctxCol}`), h(Text, { dimColor: true }, ` ${timeCol}`));
30
30
  });
31
+ // ─── Row rename field ────────────────────────────────────────────────────────
32
+ function InputText({ value, cursor, termWidth }) {
33
+ const style = { backgroundColor: 'grey', color: 'white', bold: true };
34
+ // Past the end there is no character to sit on: show a block instead
35
+ // (ink trims trailing whitespace, so an inverse space would be invisible).
36
+ if (cursor >= value.length) {
37
+ return h(Box, {}, h(Text, style, pad(`> ${value}█`, termWidth)));
38
+ }
39
+ // The cursor is the inverse-video cell over the character it sits on.
40
+ return h(Box, {}, h(Text, style, `> ${value.slice(0, cursor)}`), h(Text, { ...style, inverse: true }, value[cursor]), h(Text, style, pad(value.slice(cursor + 1), Math.max(0, termWidth - cursor - 3))));
41
+ }
42
+ function openRename(title) {
43
+ return { value: title, cursor: title.length };
44
+ }
45
+ function cursorLeft({ value, cursor }) {
46
+ return { value, cursor: Math.max(0, cursor - 1) };
47
+ }
48
+ function cursorRight({ value, cursor }) {
49
+ return { value, cursor: Math.min(value.length, cursor + 1) };
50
+ }
51
+ // Start of the word left of the cursor: skip spaces, then the word itself.
52
+ function cursorPrevWord({ value, cursor }) {
53
+ let i = cursor;
54
+ while (i > 0 && value[i - 1] === ' ')
55
+ i--;
56
+ while (i > 0 && value[i - 1] !== ' ')
57
+ i--;
58
+ return { value, cursor: i };
59
+ }
60
+ // Start of the word right of the cursor: skip the rest of this word, then spaces.
61
+ function cursorNextWord({ value, cursor }) {
62
+ let i = cursor;
63
+ while (i < value.length && value[i] !== ' ')
64
+ i++;
65
+ while (i < value.length && value[i] === ' ')
66
+ i++;
67
+ return { value, cursor: i };
68
+ }
69
+ function backspace({ value, cursor }) {
70
+ const c = Math.max(0, cursor - 1);
71
+ return { value: value.slice(0, c) + value.slice(cursor), cursor: c };
72
+ }
73
+ function insert({ value, cursor }, text) {
74
+ return {
75
+ value: value.slice(0, cursor) + text + value.slice(cursor),
76
+ cursor: cursor + text.length
77
+ };
78
+ }
31
79
  // ─── Directory header ─────────────────────────────────────────────────────────
32
80
  function DirectoryHeader({ cwd }) {
33
81
  return h(Box, { paddingLeft: 1 }, h(Text, { color: 'yellow' }, shortPath(cwd)));
34
82
  }
35
83
  // ─── Preview mode ─────────────────────────────────────────────────────────────
36
- function PreviewMode({ session, onBack, termWidth, termHeight }) {
84
+ function PreviewMode({ session, onBack, termWidth, termHeight, loadMessages }) {
37
85
  const [messages, setMessages] = useState(null);
38
86
  const [scroll, setScroll] = useState(0);
39
87
  useEffect(() => {
40
- getSessionMessages(session.filePath).then((msgs) => {
88
+ loadMessages(session.filePath).then((msgs) => {
41
89
  setMessages(msgs);
42
90
  setScroll(Math.max(0, msgs.length - 1));
43
91
  });
44
- }, [session.filePath]);
92
+ }, [session.filePath, loadMessages]);
45
93
  const viewHeight = termHeight - HEADER_HEIGHT - HINT_HEIGHT - 2;
46
94
  useInput((input, key) => {
47
95
  if (input === 'q' || input === ' ' || key.escape || key.backspace) {
@@ -75,11 +123,11 @@ function renderMessages(messages, scroll, viewHeight, termWidth) {
75
123
  }));
76
124
  }
77
125
  // ─── Delete confirm ───────────────────────────────────────────────────────────
78
- function DeleteConfirm({ session, onConfirm, onCancel, termWidth, termHeight }) {
126
+ function DeleteConfirm({ session, onConfirm, onCancel, termWidth, termHeight, loadMessages }) {
79
127
  const [messages, setMessages] = useState(null);
80
128
  useEffect(() => {
81
- getSessionMessages(session.filePath).then(setMessages);
82
- }, [session.filePath]);
129
+ loadMessages(session.filePath).then(setMessages);
130
+ }, [session.filePath, loadMessages]);
83
131
  useInput((input) => {
84
132
  if (input === 'y')
85
133
  onConfirm();
@@ -133,11 +181,10 @@ function StatsView({ sessions, onBack, termWidth, termHeight }) {
133
181
  const section = (label) => h(Box, { marginTop: 1 }, h(Text, { bold: true, color: 'cyan' }, label));
134
182
  return h(Box, { flexDirection: 'column' }, h(Box, { paddingX: 1 }, h(Text, { color: 'white', bold: true }, 'Usage · real throughput (cache reads excluded)')), h(Box, { paddingX: 1, flexDirection: 'column' }, h(Text, {}, `${stats.totalSessions} sessions `, h(Text, { color: 'green', bold: true }, `${fmtTokens(stats.totalThroughput)} throughput`), h(Text, { dimColor: true }, ` ${fmtTokens(stats.grandTotal)} incl. cache reads`)), section('Token breakdown'), ...bdRows.map((r) => h(Text, { key: r.label }, pad(r.label, labelW), h(Text, { color: r.label === 'Cache rd' ? 'gray' : 'green' }, bar(r.value, bdMax, barW)), h(Text, { dimColor: true }, ` ${fmtTokens(r.value)}`))), section('Throughput / day (30d)'), h(Text, {}, h(Text, { dimColor: true }, `${pad(sparkStart, 7)} `), h(Text, { color: 'green' }, spark), h(Text, { dimColor: true }, ` ${sparkEnd}`)), section('By model'), ...stats.byModel.map((m) => h(Text, { key: m.name }, pad(m.name, labelW), h(Text, { color: 'green' }, bar(m.throughput, modelMax, barW)), h(Text, { dimColor: true }, ` ${fmtTokens(m.throughput)}`))), section('Top projects by throughput'), ...projects.map((p) => h(Text, { key: p.cwd }, pad(truncate(shortPath(p.cwd), projLabelW), projLabelW), ' ', h(Text, { color: 'green' }, bar(p.throughput, projMax, barW)), h(Text, { dimColor: true }, ` ${fmtTokens(p.throughput)}`)))), h(Box, { marginTop: 1 }, h(Text, { dimColor: true }, 'q/esc/u back')));
135
183
  }
136
- export default function App({ loadFirst, loadRest, initialSortMode, onResume, onDelete = deleteSession }) {
184
+ export default function App({ loadFirst, loadRest, initialSortMode, onResume, onDelete = deleteSession, onRename = renameSession, loadMessages = getSessionMessages }) {
137
185
  const { exit } = useApp();
138
186
  const { stdout } = useStdout();
139
- const termWidth = stdout?.columns || 80;
140
- const termHeight = stdout?.rows || 24;
187
+ const { width: termWidth, height: termHeight } = termSize(stdout);
141
188
  const [sessions, setSessions] = useState([]);
142
189
  const [selectedId, setSelectedId] = useState(null);
143
190
  const [viewStart, setViewStart] = useState(0);
@@ -145,6 +192,8 @@ export default function App({ loadFirst, loadRest, initialSortMode, onResume, on
145
192
  const [sortMode, setSortMode] = useState(initialSortMode ?? 'recent');
146
193
  const [searchQuery, setSearchQuery] = useState('');
147
194
  const [isSearching, setIsSearching] = useState(false);
195
+ const [rename, setRename] = useState(null);
196
+ const [error, setError] = useState(null);
148
197
  const [loading, setLoading] = useState(true);
149
198
  // Paint before any session is parsed: newest batch first, the rest in one later
150
199
  // batch (disjoint from the first, so a delete can't be resurrected by the merge).
@@ -196,6 +245,48 @@ export default function App({ loadFirst, loadRest, initialSortMode, onResume, on
196
245
  useInput((input, key) => {
197
246
  if (mode !== 'list')
198
247
  return;
248
+ if (error)
249
+ setError(null);
250
+ if (rename !== null) {
251
+ if (key.escape) {
252
+ setRename(null);
253
+ return;
254
+ }
255
+ if (key.return) {
256
+ const title = rename.value.trim();
257
+ setRename(null);
258
+ if (current && title && title !== (current.title || 'Untitled')) {
259
+ // update the row in the same frame the input closes
260
+ const updateRow = (s) => s.sessionId === current.sessionId ? { ...s, title } : s;
261
+ setSessions((cur) => cur.map(updateRow));
262
+ // persist in the background; revert and warn if it fails
263
+ onRename(current.filePath, title).catch((err) => {
264
+ const revertRow = (s) => s.sessionId === current.sessionId ? { ...s, title: current.title } : s;
265
+ setSessions((cur) => cur.map(revertRow));
266
+ setError(`could not save rename: ${err.message}`);
267
+ });
268
+ }
269
+ return;
270
+ }
271
+ // alt+arrows arrive as meta+arrow (xterm-style CSI) or as ESC b / ESC f
272
+ // (macOS terminals), which ink reports as meta plus a plain b / f.
273
+ if (key.leftArrow || (key.meta && input === 'b')) {
274
+ setRename((r) => r && (key.meta ? cursorPrevWord(r) : cursorLeft(r)));
275
+ return;
276
+ }
277
+ if (key.rightArrow || (key.meta && input === 'f')) {
278
+ setRename((r) => r && (key.meta ? cursorNextWord(r) : cursorRight(r)));
279
+ return;
280
+ }
281
+ if (key.backspace || key.delete || input === '\x7f') {
282
+ setRename((r) => r && backspace(r));
283
+ return;
284
+ }
285
+ if (input && input !== '\x7f' && !key.ctrl && !key.meta) {
286
+ setRename((r) => r && insert(r, input));
287
+ }
288
+ return;
289
+ }
199
290
  if (isSearching) {
200
291
  if (key.escape) {
201
292
  setIsSearching(false);
@@ -260,6 +351,9 @@ export default function App({ loadFirst, loadRest, initialSortMode, onResume, on
260
351
  onResume(current);
261
352
  exit();
262
353
  }
354
+ else if (input === 'r' && current) {
355
+ setRename(openRename(current.title || 'Untitled'));
356
+ }
263
357
  else if (input === 'D' && current)
264
358
  setMode('deleting');
265
359
  else if (input === 's') {
@@ -277,7 +371,8 @@ export default function App({ loadFirst, loadRest, initialSortMode, onResume, on
277
371
  session: current,
278
372
  onBack: () => setMode('list'),
279
373
  termWidth,
280
- termHeight
374
+ termHeight,
375
+ loadMessages
281
376
  });
282
377
  }
283
378
  if (mode === 'stats') {
@@ -314,7 +409,8 @@ export default function App({ loadFirst, loadRest, initialSortMode, onResume, on
314
409
  setViewStart((vs) => Math.min(vs, Math.max(0, next.length - 1 - listHeight)));
315
410
  setMode('list');
316
411
  },
317
- onCancel: () => setMode('list')
412
+ onCancel: () => setMode('list'),
413
+ loadMessages
318
414
  });
319
415
  }
320
416
  const snippet = current?.lastUserMessage
@@ -328,33 +424,41 @@ export default function App({ loadFirst, loadRest, initialSortMode, onResume, on
328
424
  lexic: 'sorted lexicographically'
329
425
  };
330
426
  const matchCount = filteredItems.filter((i) => i.type === 'session').length;
331
- const searchLabel = isSearching || searchQuery
332
- ? ` │ /${searchQuery}${isSearching ? '█' : ''} ${matchCount} matches`
333
- : '';
427
+ // searchQuery is only ever non-empty while searching, so the label tracks isSearching
428
+ const searchLabel = isSearching ? ` │ /${searchQuery}█ ${matchCount} matches` : '';
334
429
  const headerText = pad(sessions.length === 0 && loading
335
430
  ? ' clod │ loading sessions…'
336
431
  : ` clod │ ${sessions.length}${loading ? '+' : ''} sessions │ ${sortLabel[sortMode]}${searchLabel}${loading ? ' │ loading…' : ''}`, termWidth);
337
- const navText = pad(' ↑↓ nav / search space preview enter resume u usage s sort D delete q quit', termWidth);
432
+ const navText = pad(rename !== null
433
+ ? ' enter confirm esc cancel'
434
+ : ' ↑↓ nav / search space preview enter resume r rename u usage s sort D delete q quit', termWidth);
338
435
  return h(Box, { flexDirection: 'column' }, h(Box, {
339
436
  borderStyle: 'single',
340
437
  borderLeft: false,
341
438
  borderRight: false,
342
439
  borderTop: false,
343
440
  borderColor: 'gray'
344
- }, h(Text, { backgroundColor: 'black', color: 'white', bold: true }, headerText)), h(Box, { flexDirection: 'column', height: listHeight }, viewSlice.length === 0 && loading
441
+ }, h(Text, { backgroundColor: error ? 'red' : 'black', color: 'white', bold: true }, error ? pad(` ${error}`, termWidth) : headerText)), h(Box, { flexDirection: 'column', height: listHeight }, viewSlice.length === 0 && loading
345
442
  ? h(Box, { paddingX: 2 }, h(Text, { dimColor: true }, 'Loading…'))
346
443
  : null, ...viewSlice.map((item) => item.type === 'header'
347
444
  ? h(DirectoryHeader, { key: item.cwd, cwd: item.cwd })
348
- : h(SessionRow, {
349
- key: item.session.sessionId,
350
- session: item.session,
351
- selected: item.session.sessionId === selectedId,
352
- termWidth,
353
- sortMode,
354
- timeWidth,
355
- usedWidth,
356
- ctxWidth
357
- }))), h(Box, {
445
+ : item.session.sessionId === selectedId && rename !== null
446
+ ? h(InputText, {
447
+ key: item.session.sessionId,
448
+ value: rename.value,
449
+ cursor: rename.cursor,
450
+ termWidth
451
+ })
452
+ : h(SessionRow, {
453
+ key: item.session.sessionId,
454
+ session: item.session,
455
+ selected: item.session.sessionId === selectedId,
456
+ termWidth,
457
+ sortMode,
458
+ timeWidth,
459
+ usedWidth,
460
+ ctxWidth
461
+ }))), h(Box, {
358
462
  flexDirection: 'row',
359
463
  borderStyle: 'single',
360
464
  borderColor: 'gray',
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@hype/clod",
3
3
  "description": "Terminal UI for managing Claude Code sessions.",
4
- "version": "1.0.0",
4
+ "version": "1.1.0",
5
5
  "author": "Nate Goldman <ungoldman@gmail.com>",
6
6
  "bin": {
7
7
  "clod": "./dist/index.js"
@@ -46,7 +46,7 @@
46
46
  "type": "module",
47
47
  "scripts": {
48
48
  "build": "tsc -p tsconfig.build.json",
49
- "coverage": "node --test --experimental-test-coverage --test-coverage-exclude='test/**' --test-coverage-exclude='src/index.ts' --test-coverage-exclude='src/trash.ts' --test-coverage-exclude='src/ui.ts' --test-coverage-lines=100 --test-coverage-branches=100 --test-coverage-functions=100 test/*.test.ts",
49
+ "coverage": "node --test --experimental-test-coverage --test-coverage-exclude='test/**' --test-coverage-exclude='src/index.ts' --test-coverage-exclude='src/trash.ts' --test-coverage-lines=100 --test-coverage-branches=100 --test-coverage-functions=100 test/*.test.ts",
50
50
  "dev": "node --watch src/index.ts",
51
51
  "format": "biome check --write .",
52
52
  "lint": "biome check .",