ThreadShelf Enhanced

Import, search, read and continue AI conversations on your own machine. ThreadShelf Enhanced adds richer rendering, broader export support and responsive layouts to ThreadShelf v1.3.0, while preserving its API routes, storage identities and light/dark interface.

Setup video · Installation · Configuration · Import support · Background jobs · Compatibility · Changelog · Contributing · Security

Interface

The web interface in light and dark themes, using synthetic demo conversations. View all release screenshots.

Dark theme — rich conversation reading with optional speech controls.

Light theme — hybrid archive search with the expanded control row.

Text-to-speech — optional local voices and playback settings.

What Enhanced adds

• Rich Markdown, tables, highlighted code, mathematics, diagrams, citations and supported ChatGPT rich content, with bundled rendering libraries and readable fallbacks.
• Native and converted JSON, HTML and ZIP imports, with original conversation data and per-message metadata retained alongside normalized turns.
• Inline click-to-load or automatic images, six compact/wide placeholder states and an optional server-only image cache with independent per-collection clearing.
• Independent animated rich-rendering switches for user prompts, thinking and responses. Turning rich rendering off keeps basic Markdown visible.
• English, Hungarian, German, Japanese, French and Russian interface settings.
• A bounded application layout, scrollable sidebar, responsive dialogs and deferred expensive rendering with stable reading position.
• Integrated Reader pagination for compatible ThreadShelf Local Suite clients. No separate pagination patch is needed.
• Project-local Node/npm setup and a Linux launcher for repeated starts and folder indexing.

Search embeddings and storage run locally. First setup and model use require network downloads. Optional remote AI and speech providers receive the content sent to them; local llama.cpp, Strata and installed CPU speech remain available. See security and privacy.

New in 1.4.2

• Grok archives: bounded rendering for saved citation, image, file, artifact and other card families, including passive task data and supported literal Chart.js charts. Saved card IDs bind references to their own message; unresolved sources remain inspectable labels.
• ChatGPT archives: expanded native citation metadata, navigation lists, file-citation chips and readable fallbacks for unknown widgets, with supported area and doughnut charts.
• VeniceAI citations: theme-aware soft-square labels for ^number^ markers, without inventing source destinations. Escaped markers, code and math remain source text.
• Safe HTML formatting: inert formatting tags and a limited text-style CSS allowlist work in user and response bubbles. Unsupported markup remains visible source; active content and application hooks are rejected.

Original messages, whole-message copy, exports, image-loading controls and rich/basic preferences retain their existing behavior. No reimport or re-embedding is required. See provider rendering, safe HTML and changelog.

Added in 1.4.1

• Conversation display: browser-saved JSON visibility, JSON-as-code, code-download, wrapping and line-number controls in Settings → Server. Each explanation sits in a recessed panel.
• Code and SVG: source-preserving downloads with language-specific extensions, Copy at the far right, display-only line numbers and validated standalone SVG Render/Code previews.
• Speech settings: Local voices appears under Providers & voices, with provider drafts and active installation progress retained across subtabs.
• Import destination: clearer Target collection selection and stale-preview protection, preserving the existing Chunks and replacement-import behavior.

Original conversation content, stored identities, existing vectors and the Local Suite APIs remain compatible. No archive reimport is required. See conversation display and changelog.

Added in 1.4.0

• Hybrid search: independent lexical and semantic retrieval, complete filters and deterministic ranking, with a rebuildable local lexical cache.
• Archive and Markdown tools: bounded archive search/read in chat, live note folders, scoped writes, revision checks, history and explicit chat-write approval.
• More AI options: Strata and configurable OpenAI-compatible providers, opt-in API vision, streaming controls and memory-only private chats.
• Text-to-speech: optional Pocket/Kokoro CPU voices, self-hosted and selected API providers, streaming/buffered playback, protected saved credentials, pinned recordings and cache controls. Speech starts disabled; voice downloads require explicit review. Audio testing is unavailable until the selected CPU engine is ready.
• Interface refresh: cyan accents, raised controls, three settings tabs, speaker icons, stable controls and improved six-language/narrow-screen layouts.
• Headless setup: independent ALLOW_LAN_AI and ALLOW_LAN_TTS permissions for trusted-LAN web use, both disabled by default.
• Portable migration: verified stopped-installation copying with explicit paths, destination safeguards and an audit for dependencies on the old directory.
• Runtime and dependencies: project-local Node 26.13.0 LTS, npm 12.2.1 and reviewed dependency fixes. Existing public launchers and importer remain available.

See speech, search, live notes and migration.

Scalable imports and background jobs in 1.3.0

Version 1.3.0 replaces whole-folder allocations and oversized fingerprint strings with streaming normalization, bounded disk staging and batched storage. Matching archive and search-index generations are published together, and unchanged content can reuse verified embeddings.

Accepted imports run as persistent server jobs. Keep the tab open until file transfer and server acceptance finish; afterward, parsing and indexing continue without a connected browser. Return to Add data to inspect progress, skipped files, errors, cancellation or retry. Unsupported files are skipped without blocking valid conversations in the same folder or ZIP.

A single coordinator protects web, CLI, watcher and recovery work. Only one index operation and one HTTP server use a database at a time. Replacement imports reserve their collection against other writes while its published data remains readable. Memory monitoring accounts for process/native allocations and effective host/container limits; batches shrink, wait or fail safely under sustained pressure.

The existing API, stored identities, embedding model and vector dimensions remain compatible. Upgrade every process sharing a writable store to the current version together. Publication metadata changes the internal storage layout: retain a stopped backup, and never open a 1.3.0-written store with an older server. Prior release tags and assets remain available.

See import jobs and resource limits, the changelog and validation record for behavior, recovery and test scope.

How to set up?

Install ThreadShelf Enhanced on Linux: check prerequisites, download the source, run setup, review configuration, verify the installation, and start, stop, and restart the server.

ThreadShelf-Enhanced-How-to-Set-Up-Linux.mp4

Interactive terminal recording on asciinema · Download the MP4 · Download the asciicast

Installation

Download the 1.4.2 source ZIP or source TAR.GZ, with the consolidated SHA256SUM.txt. All releases remain available. You can also clone the repository's master branch. Extract into a writable directory and run setup there. Enhanced is distributed as source; it is not published to npm.

The setup scripts download official Node 26.13.0 LTS, verify its SHA-256 against the official checksum list, install npm 12.2.1 into the project-local runtime, install locked dependencies and build the application. They do not change your global Node installation or shell profile. Administrator access is not required.

Linux

Requires x64 or ARM64 Linux, Bash, curl or wget, tar and sha256sum.

bash setup-threadshelf.sh
./threadshelf-enhanced

Use bash setup-threadshelf.sh --start to set up and start in one command. For subsequent starts, run ./threadshelf-enhanced; it uses the compiled server and the downloaded runtime. Ctrl+C stops the child process, prints CTRL-C, and returns success so following ; or && commands continue. Startup and runtime failures retain their nonzero exit status. No terminal multiplexer is required.

The launcher resolves its project directory from its own location, including when reached through a symlink. Set THREADSHELF_ENHANCED_DIR to choose another installation explicitly.

Launcher command	Purpose
./threadshelf-enhanced	Start the server
./threadshelf-enhanced --help	Show usage (-h also works)
./threadshelf-enhanced --version	Show version information (-V also works)
./threadshelf-enhanced --check-runtime	Check the selected runtime
./threadshelf-enhanced --index /path/to/exports archive	Import a server-local folder into the archive collection
./threadshelf-enhanced --index /path/to/exports archive --clear	Replace that collection from the folder

The optional interactive importer provides a review screen, readiness checks, resource controls and explicit source-copy choices:

bash manual-importer.sh
bash manual-importer.sh --help

Its default JavaScript old-space ceiling is 4096 MiB, with startup headroom checks and configurable --heap-mb/--reserve-mb. Its non-interactive mode and --health/--dry-run inspection modes are documented in its help. It uses the same coordinated server import pipeline. The public launcher does not require tmux or GNU Screen.

Use --clear only when you intend to replace the collection. An older Linux distribution may need a newer system libc to run official Node binaries; setup checks the runtime before replacing an existing installation.

Windows

Requires x64 or ARM64 Windows and PowerShell.

.\setup-threadshelf.ps1 -Start

For subsequent starts on x64:

.\.local\node-v26.13.0-win-x64\node.exe dist\src\server.js

Substitute arm64 for x64 on ARM machines. If execution policy blocks a downloaded script, review it and use Unblock-File .\setup-threadshelf.ps1; organization-managed policy still applies. See validation for platform verification scope.

Setup options and an existing Node installation

Purpose	Bash	PowerShell
Install only the local Node/npm runtime	--runtime-only	-RuntimeOnly
Select Node	--node-version 26.13.0	-NodeVersion 26.13.0
Select npm	--npm-version 12.2.1	-NpmVersion 12.2.1

Environment overrides are THREADSHELF_NODE_VERSION and THREADSHELF_NPM_VERSION. Node 24+ is required for lossless JSON numeric-token handling; npm 12 requires Node 24.15+ within the 24.x line. Setup rejects incompatible combinations. The root package explicitly allows the install scripts needed by its pinned dependencies. CPU embeddings are used by default; optional CUDA downloads are skipped unless ONNXRUNTIME_NODE_INSTALL=cuda12 is set.

If a compatible Node/npm runtime is already installed:

npm ci
npm run build
npm start

Configuration

Setup preserves an existing .env and copies .env.example when it is absent. The default UI address is http://localhost:3000.

Setting	Purpose
HOST	Bind address; the supplied default is 127.0.0.1 for this computer only
PORT	HTTP port; default 3000
ALLOW_LAN_AI	0 by default; 1 permits AI chat, model setup and Markdown-vault controls through the allowed LAN web address
ALLOW_LAN_TTS	0 by default; 1 permits speech setup, credentials, saved audio and playback through the allowed LAN web address
ALLOWED_ORIGINS	Optional comma-separated full browser origins for a deliberate proxy or separate frontend; exact same-origin is the default
ALLOWED_HOSTS	Comma-separated request hostnames/IP addresses, without schemes or ports
THREADSHELF_DATA_DIR	Override the common data directory
LANCEDB_PATH, UPLOADS_DIR, COLLECTIONS_PATH	Override individual storage locations
THREADSHELF_MEMORY_RESERVE_MB, THREADSHELF_PROCESS_MEMORY_MB	Override the memory governor's headroom and process RSS budgets
THREADSHELF_IMAGE_CACHE_PATH	Optional separate location for disposable image-cache data
OPENROUTER_API_KEY, HF_TOKEN, GITHUB_TOKEN	Optional credentials for the corresponding integrations

Host checks do not provide authentication. Remote access requires an appropriate network boundary or authenticated reverse proxy. Keep .env, uploaded exports, databases and model files out of source control. The upstream manual explains inherited generation, MCP, search and configuration features; its npm publishing and installation instructions apply to upstream ThreadShelf.

Headless trusted-LAN AI and speech

Edit the root .env beside the setup scripts, using your server's actual address:

HOST=0.0.0.0
ALLOWED_HOSTS=localhost,127.0.0.1,192.168.1.50
ALLOW_LAN_AI=1
ALLOW_LAN_TTS=1

The two flags are independent. Only the exact value 1 enables permission; 0, unset or any other value keeps that feature's management localhost-only. Restart after editing; an explicitly exported process variable overrides .env. After migration, edit the copied .env, because it replaces the fresh template.

These flags grant the full corresponding controls without an API key to clients that can reach an allowed server address. They are not authentication or subnet filters. Keep this deployment on a trusted network or behind authenticated access. Host and exact browser-origin checks still apply. Native clients need no browser origin entry. The separate /v1 listener and its key policy are unchanged.

ALLOW_LAN_TTS=1 does not enable speech or download voices. Open Settings → Text-to-Speech, enable and save, then review Download local voices. AI access is not needed for speech. With the TTS flag disabled, the separate authenticated LAN CPU playback option remains available as described in TTS.md.

Import support and known limits

The adapters support ChatGPT, Claude, Google AI Studio, OpenRouter, selected LM Studio formats, Grok, Meta AI, Gemini/Takeout, Venice, normalized ThreadShelf conversations and supported converted exports. JSON and embedded HTML data are parsed without executing export scripts, and original input files are never rewritten.

• Duplicate export representations: a ZIP containing both conversations.json and chat.html imports both and can create duplicate conversations. Keep one conversation representation per import.
• Local image companions: folder uploads include supported image files. Keep companion paths intact; a server-local folder or ZIP with one conversation representation and its image companions also preserves supported local media.
• Venice: native unencrypted version 4 backups are supported; encrypted backups are unsupported.
• JSONL: newline-delimited JSON is unsupported. Use a supported JSON document, HTML export or ZIP.
• Skipped files versus failed exports: unrelated, unsupported and empty auxiliary files are skipped. A recognized but malformed export, failed preparation or no valid conversations prevents destructive collection replacement.
• Resource limits: bounded staging removes the whole-folder memory requirement. Individual records, whole-document formats, images and archives still have explicit safety limits, and replacement imports need free disk space. Unknown rich widgets may remain readable source or placeholders.

See the compatibility contract and import adapter notes for exact behavior and limits.

Existing deployments and clients

Stop all server, MCP, importer and watcher processes first. Back up the complete .lancedb, .uploads, .collections.json, .threadshelf and .env, or their configured external locations. The complete database includes its publication/job metadata and SQLite sidecars; do not copy selected LanceDB tables alone.

For a fresh directory, run setup without starting the server, then use the verified migration tool:

.local/node-v26.13.0-linux-x64/bin/node scripts/migrate-installation.mjs \
  --stopped --source /path/to/old-installation --target /path/to/new-installation

Both paths are required. The tool never deletes the source and refuses existing target data. --include-caches also copies the supported optional cache directories; --audit-only checks dependencies without copying. Windows examples, custom-layout limitations and rollback guidance are in the migration guide.

Preserve relative layouts and inspect absolute paths, custom data roots and symlinks before removing the old installation. Do not copy old dependencies, local Node binaries or generated builds over the fresh source. Keep the old copy until stored threads, search, media, generation settings and client connections are verified.

All processes sharing the new store must run 1.4.0. Opening old data does not require reimporting exports, although pending index work may recover at startup. Once the new server writes generation metadata, rollback means restoring the stopped backup, not starting an older binary against the changed store. Preserve the server URL and source paths when bookmarks or thread identities depend on them.

Enhanced adds metadata columns while preserving existing normalized turns and identity keys. Compatible Local Suite clients keep their own archive formats; Enhanced does not migrate their databases. Do not install the older Reader pagination patch over Enhanced. The compatibility matrix distinguishes server API checks from desktop and archive behavior.

Development, help and licensing

See CONTRIBUTING.md for setup, focused tests and pull request guidance, and validation for the current release gate. Report reproducible bugs with synthetic examples in GitHub Issues. For vulnerabilities, follow SECURITY.md.

Enhanced originated with 1.0.0, based on upstream commit 3430dd04f50218fdea916b104709d24a651017fc (v1.3.0). It is a distinct fork maintained by davoda1. Original copyright and MIT licensing are retained; see LICENSE and third-party notices.