chatshelf 0.0.0-stage → 0.2.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Shaikh khoaiz Ahmmed
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,153 @@
1
- # Temporary Holding Version
1
+ <div align="center">
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ # Chatshelf
4
+
5
+ **One place for your AI coding chats.**
6
+ Browse, search and bookmark your history from Claude Code, Codex, Cursor and GitHub Copilot, and get Claude Code sessions back after you rename a project folder.
7
+
8
+ [![npm](https://img.shields.io/npm/v/chatshelf?color=E8590C)](https://www.npmjs.com/package/chatshelf)
9
+ [![npm downloads](https://img.shields.io/npm/dm/chatshelf?color=1C1917)](https://www.npmjs.com/package/chatshelf)
10
+ [![GitHub stars](https://img.shields.io/github/stars/heyKhoaiz/chatshelf?style=flat&color=E8590C)](https://github.com/heyKhoaiz/chatshelf/stargazers)
11
+ [![CI](https://github.com/heyKhoaiz/chatshelf/actions/workflows/ci.yml/badge.svg)](https://github.com/heyKhoaiz/chatshelf/actions/workflows/ci.yml)
12
+ [![License: MIT](https://img.shields.io/badge/license-MIT-1C1917)](LICENSE)
13
+ ![Node 22.5+](https://img.shields.io/badge/node-%E2%89%A522.5-1C1917)
14
+ ![Zero dependencies](https://img.shields.io/badge/dependencies-0-15803D)
15
+
16
+ ![Chatshelf overview](https://raw.githubusercontent.com/heyKhoaiz/chatshelf/main/docs/overview.png)
17
+
18
+ </div>
19
+
20
+ ## Why
21
+
22
+ AI coding tools each keep their chat history in a different place, in a different format. Finding "that chat where we fixed the rate limiter" means remembering which tool, which folder and which day.
23
+
24
+ Claude Code has one more trap. It files every session under the folder's path, so **renaming a project folder makes its sessions disappear** from `claude --resume`. They're still on disk, under the old name.
25
+
26
+ Chatshelf reads all of it locally and puts it on one shelf.
27
+
28
+ ## Features
29
+
30
+ - **Every tool in one list.** Claude Code, Codex, Cursor and GitHub Copilot Chat are read straight from your disk. ChatGPT and claude.ai come in through their data exports. OpenCode and Gemini CLI are experimental.
31
+ - **Search everything.** Titles, every prompt you typed, folders, branches and session IDs. Filter by tool, project and date (today, last 7 days, custom range…).
32
+ - **Read any chat.** Formatted Markdown, code blocks with copy buttons, the tools that ran, find-in-chat, and a "my prompts only" view.
33
+ - **Pick up where you left off.** One click resumes a Claude Code or Codex session in a terminal, or opens the project in Cursor or VS Code.
34
+ - **Fix renamed folders.** Chatshelf spots Claude Code projects whose folder no longer exists, suggests the new folder, and moves the sessions there, with a backup first.
35
+ - **Bookmarks.** Save whole chats or single messages, with notes. Bookmarks made with **Bookmark response** in the Claude Code VS Code extension show up too.
36
+ - **Made for the keyboard.** <kbd>Ctrl</kbd> <kbd>K</kbd> command palette, <kbd>j</kbd>/<kbd>k</kbd> to move, <kbd>/</kbd> to search, <kbd>?</kbd> for the full list.
37
+ - **Light and dark theme,** with reduced-motion support and 44px touch targets.
38
+ - **Private by design.** It runs on `127.0.0.1` only, has no dependencies and no telemetry, and never writes to other tools' files.
39
+
40
+ | Sessions | Conversation |
41
+ | --- | --- |
42
+ | ![Sessions list](https://raw.githubusercontent.com/heyKhoaiz/chatshelf/main/docs/sessions.png) | ![Conversation view](https://raw.githubusercontent.com/heyKhoaiz/chatshelf/main/docs/conversation.png) |
43
+ | **Projects: fix renamed folders** | **Dark theme** |
44
+ | ![Projects](https://raw.githubusercontent.com/heyKhoaiz/chatshelf/main/docs/projects.png) | ![Dark theme](https://raw.githubusercontent.com/heyKhoaiz/chatshelf/main/docs/dark.png) |
45
+
46
+ ## Quick start
47
+
48
+ You need **Node.js 22.5 or newer**.
49
+
50
+ ```bash
51
+ npx chatshelf # opens http://chatshelf.localhost:4317
52
+ ```
53
+
54
+ Or install it once and run `chatshelf` any time:
55
+
56
+ ```bash
57
+ npm install -g chatshelf
58
+ chatshelf
59
+ ```
60
+
61
+ ### Open it
62
+
63
+ - Run `chatshelf` (or `npx chatshelf`). It opens **http://chatshelf.localhost:4317** in your browser.
64
+ - Already running? Running `chatshelf` again just opens the browser to it.
65
+ - Bookmark the address to get back in one click while it's running.
66
+ - Press **Ctrl+C** in the terminal to stop it. Run `chatshelf --help` to see every option.
67
+ - Just installed and your shell says `command not found`? Open a new terminal tab, or run `rehash` (zsh) or `hash -r` (bash).
68
+
69
+ Update to the latest version:
70
+
71
+ ```bash
72
+ npx chatshelf@latest # npx: always run the newest version
73
+ npm update -g chatshelf # if you installed it with -g
74
+ ```
75
+
76
+ Releases and notes: [GitHub releases](https://github.com/heyKhoaiz/chatshelf/releases) · [npm](https://www.npmjs.com/package/chatshelf).
77
+
78
+ From source (no dependencies, no build step):
79
+
80
+ ```bash
81
+ git clone https://github.com/heyKhoaiz/chatshelf.git
82
+ cd chatshelf
83
+ npm start
84
+ ```
85
+
86
+ The address works in Chrome, Edge, Firefox and Brave with no setup. If your browser can't open it (Safari on macOS, for example), use http://127.0.0.1:4317. Both always work.
87
+
88
+ To look around without your own history, run `npm run demo`. It uses fake chats in a temporary folder.
89
+
90
+ Options:
91
+
92
+ ```bash
93
+ chatshelf --help # all options
94
+ chatshelf --version # installed version
95
+ chatshelf --no-open # don't open the browser
96
+ PORT=5000 chatshelf # use another port
97
+ CHATSHELF_TERMINAL=kitty chatshelf # pick the terminal for "Open in terminal"
98
+ ```
99
+
100
+ ## Supported tools
101
+
102
+ | Tool | Where it's read from (Linux) | Open / resume |
103
+ | --- | --- | --- |
104
+ | Claude Code | `~/.claude/projects/` | `claude --resume <id>` |
105
+ | Codex (CLI and IDE extension) | `~/.codex/sessions/` | `codex resume <id>` |
106
+ | Cursor | `~/.config/Cursor/User/globalStorage/state.vscdb` (opened read-only) | opens the project in Cursor |
107
+ | GitHub Copilot Chat | `~/.config/Code/User/workspaceStorage/*/chatSessions/` | opens the project in VS Code |
108
+ | OpenCode *(experimental)* | `~/.local/share/opencode/storage/` | `opencode` in the project |
109
+ | Gemini CLI *(experimental)* | `~/.gemini/tmp/*/chats/` | `gemini` in the project |
110
+ | ChatGPT, claude.ai | the export `.zip` you import in **Tools & import** | opens the chat on the website |
111
+
112
+ On macOS and Windows, Chatshelf looks in the matching application-data folders. The experimental readers follow each tool's documented storage layout and need testing with real data. [Help wanted!](CONTRIBUTING.md#add-or-fix-a-tool-reader)
113
+
114
+ ## Fixing a renamed folder
115
+
116
+ 1. Open **Projects**. Any folder that no longer exists is marked **Folder missing**.
117
+ 2. Click **Fix**, then pick the new folder from the suggestions or browse to it.
118
+ 3. Click **Move sessions**. Then `cd` into the new folder and run `claude --resume`.
119
+
120
+ A move:
121
+
122
+ - copies the affected files to `~/.claude/projects-backup/` first
123
+ - moves the sessions, their subagent files and the project memory, without overwriting anything
124
+ - updates the folder path stored inside each session, and keeps each file's original date
125
+
126
+ **Backups → Restore** puts a backup back.
127
+
128
+ ## Where Chatshelf keeps its own data
129
+
130
+ | What | Where |
131
+ | --- | --- |
132
+ | Bookmarks | `~/.local/share/chatshelf/bookmarks.json` |
133
+ | Imported ChatGPT and claude.ai chats | `~/.local/share/chatshelf/imports/` |
134
+ | Search index cache | `~/.cache/chatshelf/` |
135
+
136
+ ## Privacy and safety
137
+
138
+ - It listens on `127.0.0.1` only and accepts only the `127.0.0.1`, `localhost` and `chatshelf.localhost` host names, which blocks DNS rebinding.
139
+ - Every API call needs a random token that changes each time the server starts.
140
+ - It reads other tools' files but never changes them. The only writes outside its own folders are moving or restoring Claude Code sessions, and only when you click **Move** or **Restore**.
141
+ - One network request: the **Star on GitHub** button fetches the public star count from `api.github.com`, cached for 6 hours. Nothing about you or your chats is sent.
142
+
143
+ ## Contributing
144
+
145
+ Contributions are very welcome, especially readers for more tools (Windsurf, Zed, Aider, Continue…) and testing the experimental ones. See **[CONTRIBUTING.md](CONTRIBUTING.md)**. It takes about five minutes to get going: no build step, no dependencies.
146
+
147
+ If Chatshelf helped you find a lost chat, **[give it a ⭐ on GitHub](https://github.com/heyKhoaiz/chatshelf)**. It helps other people find it.
148
+
149
+ ## License
150
+
151
+ [MIT](LICENSE) © Shaikh khoaiz Ahmmed
152
+
153
+ Chatshelf is an independent project. It is not affiliated with Anthropic, OpenAI, Anysphere (Cursor), GitHub, Google or the other tools it reads. Product names belong to their owners.
@@ -0,0 +1,45 @@
1
+ #!/usr/bin/env node
2
+ // Starts Chatshelf. Re-runs Node with the SQLite "experimental" warning hidden.
3
+ import { spawn } from 'node:child_process';
4
+ import fs from 'node:fs';
5
+ import path from 'node:path';
6
+ import { fileURLToPath } from 'node:url';
7
+
8
+ const root = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
9
+ const args = process.argv.slice(2);
10
+ const { version } = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
11
+ const port = process.env.PORT || '4317';
12
+
13
+ if (args.includes('--version') || args.includes('-v')) {
14
+ console.log(version);
15
+ process.exit(0);
16
+ }
17
+ if (args.includes('--help') || args.includes('-h')) {
18
+ console.log(`Chatshelf ${version}: one place for your AI coding chats
19
+
20
+ Usage
21
+ chatshelf start and open http://chatshelf.localhost:${port}
22
+ (if it's already running, this just opens the browser)
23
+ chatshelf --no-open start without opening the browser
24
+ chatshelf --version print the version
25
+ chatshelf --help show this help
26
+
27
+ Settings (environment variables)
28
+ PORT=5000 use another port
29
+ CHATSHELF_TERMINAL=kitty terminal for "Open in terminal"
30
+
31
+ Stop it with Ctrl+C. If the address doesn't open in your browser, use http://127.0.0.1:${port}.
32
+ Docs: https://github.com/heyKhoaiz/chatshelf`);
33
+ process.exit(0);
34
+ }
35
+
36
+ const major = Number(process.versions.node.split('.')[0]);
37
+ const minor = Number(process.versions.node.split('.')[1]);
38
+ if (major < 22 || (major === 22 && minor < 5)) {
39
+ console.error(`Chatshelf needs Node.js 22.5 or newer. You have ${process.versions.node}. Get it at https://nodejs.org`);
40
+ process.exit(1);
41
+ }
42
+
43
+ const child = spawn(process.execPath, ['--disable-warning=ExperimentalWarning', path.join(root, 'server.mjs'), ...args], { stdio: 'inherit' });
44
+ child.on('exit', (code) => process.exit(code ?? 0));
45
+ for (const sig of ['SIGINT', 'SIGTERM']) process.on(sig, () => child.kill(sig));
package/package.json CHANGED
@@ -1,6 +1,46 @@
1
1
  {
2
2
  "name": "chatshelf",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.2.0",
4
+ "description": "One place for your AI coding chats: browse, search and bookmark Claude Code, Codex, Cursor and Copilot history, and fix Claude Code sessions after renaming a folder. Local, no dependencies.",
5
+ "license": "MIT",
6
+ "author": "Shaikh khoaiz Ahmmed",
7
+ "homepage": "https://github.com/heyKhoaiz/chatshelf#readme",
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "git+https://github.com/heyKhoaiz/chatshelf.git"
11
+ },
12
+ "bugs": {
13
+ "url": "https://github.com/heyKhoaiz/chatshelf/issues"
14
+ },
15
+ "keywords": [
16
+ "claude-code",
17
+ "codex",
18
+ "cursor",
19
+ "copilot",
20
+ "chat-history",
21
+ "ai",
22
+ "developer-tools",
23
+ "local-first"
24
+ ],
25
+ "type": "module",
26
+ "bin": {
27
+ "chatshelf": "bin/chatshelf.mjs"
28
+ },
29
+ "files": [
30
+ "server.mjs",
31
+ "sources.mjs",
32
+ "public",
33
+ "bin"
34
+ ],
35
+ "engines": {
36
+ "node": ">=22.5"
37
+ },
38
+ "scripts": {
39
+ "start": "node --disable-warning=ExperimentalWarning server.mjs",
40
+ "demo": "node scripts/demo.mjs",
41
+ "test": "node test/smoke.mjs",
42
+ "check": "node --check server.mjs && node --check sources.mjs && node --check public/app.js",
43
+ "prepublishOnly": "npm run check && npm test",
44
+ "release": "node scripts/release.mjs"
45
+ }
46
+ }