chatshelf 0.0.0-stage → 0.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/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,130 @@
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
+ [![GitHub stars](https://img.shields.io/github/stars/heyKhoaiz/chatshelf?style=flat&color=E8590C)](https://github.com/heyKhoaiz/chatshelf/stargazers)
9
+ [![CI](https://github.com/heyKhoaiz/chatshelf/actions/workflows/ci.yml/badge.svg)](https://github.com/heyKhoaiz/chatshelf/actions/workflows/ci.yml)
10
+ [![License: MIT](https://img.shields.io/badge/license-MIT-1C1917)](LICENSE)
11
+ ![Node 22.5+](https://img.shields.io/badge/node-%E2%89%A522.5-1C1917)
12
+ ![Zero dependencies](https://img.shields.io/badge/dependencies-0-15803D)
13
+
14
+ ![Chatshelf overview](https://raw.githubusercontent.com/heyKhoaiz/chatshelf/main/docs/overview.png)
15
+
16
+ </div>
17
+
18
+ ## Why
19
+
20
+ 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.
21
+
22
+ 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.
23
+
24
+ Chatshelf reads all of it locally and puts it on one shelf.
25
+
26
+ ## Features
27
+
28
+ - **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.
29
+ - **Search everything.** Titles, every prompt you typed, folders, branches and session IDs. Filter by tool, project and date (today, last 7 days, custom range…).
30
+ - **Read any chat.** Formatted Markdown, code blocks with copy buttons, the tools that ran, find-in-chat, and a "my prompts only" view.
31
+ - **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.
32
+ - **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.
33
+ - **Bookmarks.** Save whole chats or single messages, with notes. Bookmarks made with **Bookmark response** in the Claude Code VS Code extension show up too.
34
+ - **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.
35
+ - **Light and dark theme,** with reduced-motion support and 44px touch targets.
36
+ - **Private by design.** It runs on `127.0.0.1` only, has no dependencies and no telemetry, and never writes to other tools' files.
37
+
38
+ | Sessions | Conversation |
39
+ | --- | --- |
40
+ | ![Sessions list](https://raw.githubusercontent.com/heyKhoaiz/chatshelf/main/docs/sessions.png) | ![Conversation view](https://raw.githubusercontent.com/heyKhoaiz/chatshelf/main/docs/conversation.png) |
41
+ | **Projects: fix renamed folders** | **Dark theme** |
42
+ | ![Projects](https://raw.githubusercontent.com/heyKhoaiz/chatshelf/main/docs/projects.png) | ![Dark theme](https://raw.githubusercontent.com/heyKhoaiz/chatshelf/main/docs/dark.png) |
43
+
44
+ ## Quick start
45
+
46
+ You need **Node.js 22.5 or newer**.
47
+
48
+ ```bash
49
+ npx chatshelf # opens http://127.0.0.1:4317
50
+ ```
51
+
52
+ Or install it once and run `chatshelf` any time:
53
+
54
+ ```bash
55
+ npm install -g chatshelf
56
+ chatshelf
57
+ ```
58
+
59
+ From source (no dependencies, no build step):
60
+
61
+ ```bash
62
+ git clone https://github.com/heyKhoaiz/chatshelf.git
63
+ cd chatshelf
64
+ npm start
65
+ ```
66
+
67
+ To look around without your own history, run `npm run demo`. It uses fake chats in a temporary folder.
68
+
69
+ Options:
70
+
71
+ ```bash
72
+ chatshelf --no-open # don't open the browser
73
+ PORT=5000 chatshelf # use another port
74
+ CHATSHELF_TERMINAL=kitty chatshelf # pick the terminal for "Open in terminal"
75
+ ```
76
+
77
+ ## Supported tools
78
+
79
+ | Tool | Where it's read from (Linux) | Open / resume |
80
+ | --- | --- | --- |
81
+ | Claude Code | `~/.claude/projects/` | `claude --resume <id>` |
82
+ | Codex (CLI and IDE extension) | `~/.codex/sessions/` | `codex resume <id>` |
83
+ | Cursor | `~/.config/Cursor/User/globalStorage/state.vscdb` (opened read-only) | opens the project in Cursor |
84
+ | GitHub Copilot Chat | `~/.config/Code/User/workspaceStorage/*/chatSessions/` | opens the project in VS Code |
85
+ | OpenCode *(experimental)* | `~/.local/share/opencode/storage/` | `opencode` in the project |
86
+ | Gemini CLI *(experimental)* | `~/.gemini/tmp/*/chats/` | `gemini` in the project |
87
+ | ChatGPT, claude.ai | the export `.zip` you import in **Tools & import** | opens the chat on the website |
88
+
89
+ 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)
90
+
91
+ ## Fixing a renamed folder
92
+
93
+ 1. Open **Projects**. Any folder that no longer exists is marked **Folder missing**.
94
+ 2. Click **Fix**, then pick the new folder from the suggestions or browse to it.
95
+ 3. Click **Move sessions**. Then `cd` into the new folder and run `claude --resume`.
96
+
97
+ A move:
98
+
99
+ - copies the affected files to `~/.claude/projects-backup/` first
100
+ - moves the sessions, their subagent files and the project memory, without overwriting anything
101
+ - updates the folder path stored inside each session, and keeps each file's original date
102
+
103
+ **Backups → Restore** puts a backup back.
104
+
105
+ ## Where Chatshelf keeps its own data
106
+
107
+ | What | Where |
108
+ | --- | --- |
109
+ | Bookmarks | `~/.local/share/chatshelf/bookmarks.json` |
110
+ | Imported ChatGPT and claude.ai chats | `~/.local/share/chatshelf/imports/` |
111
+ | Search index cache | `~/.cache/chatshelf/` |
112
+
113
+ ## Privacy and safety
114
+
115
+ - It listens on `127.0.0.1` only and rejects requests with an unexpected `Host` header, which blocks DNS rebinding.
116
+ - Every API call needs a random token that changes each time the server starts.
117
+ - 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**.
118
+ - 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.
119
+
120
+ ## Contributing
121
+
122
+ 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.
123
+
124
+ If Chatshelf helped you find a lost chat, **[give it a ⭐ on GitHub](https://github.com/heyKhoaiz/chatshelf)**. It helps other people find it.
125
+
126
+ ## License
127
+
128
+ [MIT](LICENSE) © Shaikh khoaiz Ahmmed
129
+
130
+ 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,10 @@
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 path from 'node:path';
5
+ import { fileURLToPath } from 'node:url';
6
+
7
+ const server = path.join(path.dirname(path.dirname(fileURLToPath(import.meta.url))), 'server.mjs');
8
+ const child = spawn(process.execPath, ['--disable-warning=ExperimentalWarning', server, ...process.argv.slice(2)], { stdio: 'inherit' });
9
+ child.on('exit', (code) => process.exit(code ?? 0));
10
+ for (const sig of ['SIGINT', 'SIGTERM']) process.on(sig, () => child.kill(sig));
package/package.json CHANGED
@@ -1,6 +1,45 @@
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.1.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
+ }
45
+ }