@kud/claude-sessions-cli 1.0.3 → 2.0.0-next.3
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 +128 -71
- package/dist/index.js +896 -204
- package/package.json +8 -6
package/README.md
CHANGED
|
@@ -1,108 +1,165 @@
|
|
|
1
|
-
|
|
1
|
+
<div align="center">
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
<b>TUI session manager for Claude Code</b><br/>
|
|
5
|
-
Browse, open, create, and clean up your Claude sessions from a single interactive interface.
|
|
6
|
-
</p>
|
|
3
|
+
|
|
7
4
|
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
<a href="https://nodejs.org"><img alt="node version" src="https://img.shields.io/node/v/%40kud%2Fclaude-sessions-cli" /></a>
|
|
13
|
-
</p>
|
|
5
|
+
[](https://www.typescriptlang.org/)
|
|
6
|
+
[](https://nodejs.org/)
|
|
7
|
+
[](https://www.npmjs.com/package/@kud/claude-sessions-cli)
|
|
8
|
+
[](LICENSE)
|
|
14
9
|
|
|
15
|
-
|
|
10
|
+
**TUI session manager for Claude Code — browse, resume, organise, and clean up all your sessions from one interactive interface.**
|
|
16
11
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
## Table of Contents
|
|
12
|
+
[Features](#-features) • [Quick Start](#-quick-start) • [CLI Reference](#-cli-reference) • [Development](#-development)
|
|
20
13
|
|
|
21
|
-
|
|
22
|
-
- [Features](#features)
|
|
23
|
-
- [Install](#install)
|
|
24
|
-
- [Usage](#usage)
|
|
25
|
-
- [Key Bindings](#key-bindings)
|
|
26
|
-
- [Clean Mode](#clean-mode)
|
|
27
|
-
- [Requirements](#requirements)
|
|
14
|
+
</div>
|
|
28
15
|
|
|
29
|
-
|
|
16
|
+
---
|
|
30
17
|
|
|
31
|
-
|
|
18
|
+
## 🌟 Features
|
|
32
19
|
|
|
33
|
-
-
|
|
34
|
-
-
|
|
35
|
-
-
|
|
36
|
-
-
|
|
20
|
+
- 🗂 **Three-tab interface** — Code sessions grouped by project, Chat sessions with pins and tag folders, and a Scheduled tab
|
|
21
|
+
- ⭐ **Pin & tag chat sessions** — star important chats to the top, group others into collapsible `#tag` folders
|
|
22
|
+
- 🔁 **Instant resume** — press `enter` on any session and Claude Code opens right where you left off, using the correct `--resume`, `--continue`, or `--name` flag automatically
|
|
23
|
+
- 🪄 **Auto CLAUDE.md creation** — new chat sessions get a `CLAUDE.md` bootstrapped automatically; preview any session's `CLAUDE.md` in-place with `m`
|
|
24
|
+
- 🧹 **Clean mode** — interactive cleanup of ghost entries, history-less projects, and orphaned history folders; available as both a key binding (`C`) and a subcommand
|
|
25
|
+
- ✨ **Animated banner** — a sparkle ASCII animation plays on first launch while sessions load in the background; skip it with `--no-banner`
|
|
26
|
+
- 🔍 **Live search** — filter sessions by name or path as you type with `/`
|
|
37
27
|
|
|
38
|
-
|
|
28
|
+
---
|
|
39
29
|
|
|
40
|
-
|
|
41
|
-
| ---------- | ------------------------------------------------------------------- |
|
|
42
|
-
| Navigation | Sorted by last activity, grouped by type (chat / code) |
|
|
43
|
-
| Search | Fuzzy filter by name or path with `/` |
|
|
44
|
-
| Filter | Toggle between all / chat / code views with `tab` |
|
|
45
|
-
| New chat | Create a named chat session and open it immediately |
|
|
46
|
-
| Delete | Remove a session's history and directory with confirmation |
|
|
47
|
-
| Clean mode | Interactive cleanup of ghost entries, stale pointers, orphaned dirs |
|
|
30
|
+
## 🚀 Quick Start
|
|
48
31
|
|
|
49
|
-
|
|
32
|
+
Install the prerelease:
|
|
50
33
|
|
|
51
34
|
```sh
|
|
52
|
-
npm install -g @kud/claude-sessions-cli
|
|
35
|
+
npm install -g @kud/claude-sessions-cli@next
|
|
53
36
|
```
|
|
54
37
|
|
|
55
|
-
|
|
38
|
+
Launch the TUI:
|
|
56
39
|
|
|
57
40
|
```sh
|
|
58
|
-
claude-sessions
|
|
59
|
-
claude-sessions clean # clean up stale session data
|
|
41
|
+
claude-sessions
|
|
60
42
|
```
|
|
61
43
|
|
|
62
|
-
|
|
44
|
+
You will see a brief animated banner followed by the session browser:
|
|
63
45
|
|
|
64
46
|
```
|
|
65
|
-
|
|
47
|
+
✻ Claude
|
|
66
48
|
|
|
67
|
-
|
|
49
|
+
Code Chat Scheduled
|
|
68
50
|
|
|
69
|
-
|
|
70
|
-
▶ Hey ~/.chats/hey just now
|
|
71
|
-
Planning ~/.chats/planning 2h
|
|
51
|
+
/ search…
|
|
72
52
|
|
|
73
|
-
|
|
74
|
-
my-project ~/Projects/my-project yesterday
|
|
75
|
-
api ~/Projects/api 3d
|
|
53
|
+
› + New chat
|
|
76
54
|
|
|
77
|
-
|
|
55
|
+
› + my-api (3) 2h
|
|
56
|
+
+ my-site (1) yesterday
|
|
57
|
+
+ dotfiles (2) 5d
|
|
78
58
|
```
|
|
79
59
|
|
|
80
|
-
|
|
60
|
+
Pick a session with `↑` / `↓` and press `enter`. Claude Code opens immediately, resuming that exact conversation.
|
|
61
|
+
|
|
62
|
+
---
|
|
63
|
+
|
|
64
|
+
## 📖 CLI Reference
|
|
65
|
+
|
|
66
|
+
### Subcommands
|
|
81
67
|
|
|
82
|
-
|
|
|
83
|
-
|
|
|
84
|
-
|
|
|
85
|
-
| `
|
|
86
|
-
| `
|
|
87
|
-
| `/` | Search by name or path |
|
|
88
|
-
| `tab` | Cycle filter: all → chat → code |
|
|
89
|
-
| `C` | Open clean mode |
|
|
90
|
-
| `q` / `esc` | Quit |
|
|
68
|
+
| Command | Description |
|
|
69
|
+
| ----------------------------- | ------------------------------------------ |
|
|
70
|
+
| `claude-sessions` | Open the TUI session browser |
|
|
71
|
+
| `claude-sessions clean` | Run the standalone clean-up wizard |
|
|
72
|
+
| `claude-sessions --no-banner` | Open the TUI, skipping the intro animation |
|
|
91
73
|
|
|
92
|
-
|
|
74
|
+
### Tab overview
|
|
93
75
|
|
|
94
|
-
|
|
76
|
+
| Tab | Contents |
|
|
77
|
+
| ------------- | -------------------------------------------------------------------------------- |
|
|
78
|
+
| **Code** | Sessions from project directories, grouped by project, expand/collapse per group |
|
|
79
|
+
| **Chat** | Sessions from `~/.claude-sessions/chats/`, with pin stars and `#tag` folders |
|
|
80
|
+
| **Scheduled** | Placeholder for scheduled tasks (coming soon) |
|
|
81
|
+
|
|
82
|
+
### Key bindings
|
|
83
|
+
|
|
84
|
+
| Key | Context | Action |
|
|
85
|
+
| ----------- | --------------- | ------------------------------------------ |
|
|
86
|
+
| `↑` `↓` | Anywhere | Navigate the list |
|
|
87
|
+
| `←` `→` | Anywhere | Switch tabs |
|
|
88
|
+
| `tab` | Anywhere | Cycle to the next tab |
|
|
89
|
+
| `enter` | Session / group | Open or resume the session in Claude Code |
|
|
90
|
+
| `space` | Group header | Expand or collapse the project / tag group |
|
|
91
|
+
| `d` | Session | Delete session (with confirmation) |
|
|
92
|
+
| `d` | Project header | Delete all sessions for that project |
|
|
93
|
+
| `r` | Code session | Rename the session label |
|
|
94
|
+
| `p` | Chat session | Pin or unpin (★) the session |
|
|
95
|
+
| `t` | Chat session | Set or remove a `#tag` for the session |
|
|
96
|
+
| `m` | Chat session | Preview the session's `CLAUDE.md` inline |
|
|
97
|
+
| `f` | Chat session | Open the session folder in Finder |
|
|
98
|
+
| `/` | List | Enter search mode — filter by name or path |
|
|
99
|
+
| `C` | List | Open clean mode |
|
|
100
|
+
| `q` / `esc` | Anywhere | Quit |
|
|
101
|
+
|
|
102
|
+
### Clean mode
|
|
103
|
+
|
|
104
|
+
Scans `~/.claude.json` and `~/.claude/projects/` for stale data and groups issues by type. Select which categories to remove before confirming — nothing is deleted without an explicit `y`.
|
|
95
105
|
|
|
96
106
|
| Type | Meaning | Action |
|
|
97
107
|
| ---------------- | ------------------------------------------------------------------------ | ---------------------------- |
|
|
98
|
-
| ghost |
|
|
99
|
-
| no history |
|
|
108
|
+
| ghost | In `~/.claude.json` but the project directory no longer exists | Remove from `~/.claude.json` |
|
|
109
|
+
| no history | In `~/.claude.json` with no conversation history | Remove from `~/.claude.json` |
|
|
100
110
|
| orphaned history | History in `~/.claude/projects/` with no matching `~/.claude.json` entry | Trash the history folder |
|
|
101
111
|
|
|
102
|
-
|
|
112
|
+
Clean mode is available as the `C` key inside the TUI and as the standalone `claude-sessions clean` subcommand.
|
|
113
|
+
|
|
114
|
+
---
|
|
115
|
+
|
|
116
|
+
## 🔧 Development
|
|
103
117
|
|
|
104
|
-
|
|
118
|
+
### Project structure
|
|
119
|
+
|
|
120
|
+
```
|
|
121
|
+
claude-sessions-cli/
|
|
122
|
+
├── src/
|
|
123
|
+
│ └── index.tsx # entire application — TUI, banner, session logic
|
|
124
|
+
├── dist/ # compiled output (generated)
|
|
125
|
+
├── package.json
|
|
126
|
+
└── tsup.config.ts
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
### Scripts
|
|
130
|
+
|
|
131
|
+
| Script | Description |
|
|
132
|
+
| ---------------------- | ---------------------------------- |
|
|
133
|
+
| `npm run dev` | Run directly from source via `tsx` |
|
|
134
|
+
| `npm run build` | Compile to `dist/` with `tsup` |
|
|
135
|
+
| `npm run build:watch` | Watch mode compilation |
|
|
136
|
+
| `npm run typecheck` | Type-check without emitting |
|
|
137
|
+
| `npm run clean` | Remove `dist/` |
|
|
138
|
+
| `npm run publish:next` | Publish to the `next` tag on npm |
|
|
139
|
+
|
|
140
|
+
### Clone and run locally
|
|
141
|
+
|
|
142
|
+
```sh
|
|
143
|
+
git clone git@github.com:kud/claude-sessions-cli.git
|
|
144
|
+
cd claude-sessions-cli
|
|
145
|
+
npm install
|
|
146
|
+
npm run dev
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
---
|
|
150
|
+
|
|
151
|
+
## 🏗 Tech Stack
|
|
152
|
+
|
|
153
|
+
| Package | Role |
|
|
154
|
+
| ---------------- | --------------------------------------- |
|
|
155
|
+
| `ink` | React renderer for the terminal |
|
|
156
|
+
| `ink-text-input` | Controlled text input component for Ink |
|
|
157
|
+
| `ink-spinner` | Spinner component for loading states |
|
|
158
|
+
| `react` | UI component model |
|
|
159
|
+
| `tsup` | TypeScript bundler |
|
|
160
|
+
| `tsx` | Direct TypeScript execution for dev |
|
|
161
|
+
| `typescript` | Static typing |
|
|
162
|
+
|
|
163
|
+
---
|
|
105
164
|
|
|
106
|
-
|
|
107
|
-
- [Claude Code](https://claude.ai/code) installed (`claude` in `PATH`)
|
|
108
|
-
- [`trash`](https://github.com/sindresorhus/trash-cli) for safe deletes (`npm install -g trash-cli`)
|
|
165
|
+
MIT © [kud](https://github.com/kud) — Made with ❤️
|