AI Thread Index

A local index for AI conversations you want to keep working on. Bring Claude and ChatGPT thread metadata into one view, then organise it by source, priority, progress and category.

AI Thread Index is a working prototype built with TypeScript, Bun and PostgreSQL. Its focus is shared curation: refreshing the imported thread list preserves the annotations attached to it. It stores titles, links, timestamps and optional first-message excerpts. Full conversation archival and full-text or semantic search are future work.

What is implemented

• A browser userscript for manually collecting Claude and ChatGPT thread metadata from a signed-in session.
• An authenticated ingestion API that updates imported records and marks threads absent from a completed scan as gone.
• A web interface with search over titles and first-message excerpts, filters, editable categories, priority and progress fields, and JSON export.
• A separate annotation table, with the name of the last editor recorded on each annotation.
• Revision-based polling so open views can receive changes from the same local service.
• Docker configuration and an API test suite with a separate disposable database.

The backend uses Bun's built-in HTTP, SQL and cryptography APIs. There are no npm runtime dependencies. See the architecture and current limitations.

Run locally

You need Docker with Docker Compose. On Windows, start Docker Desktop with Linux containers enabled. Run the following from this repository in PowerShell:

Copy-Item .env.example .env

Edit .env and replace every CHANGE_ME value. Set a different random value for ACCESS_PASSWORD, TOKEN_SECRET and POSTGRES_PASSWORD. This PowerShell snippet generates one 32-byte hexadecimal value; run it separately for each setting:

$randomBytes = New-Object byte[] 32
$generator = [System.Security.Cryptography.RandomNumberGenerator]::Create()
$generator.GetBytes($randomBytes)
$generator.Dispose()
[BitConverter]::ToString($randomBytes).Replace('-', '').ToLowerInvariant()

Keep those values in your local .env. Hexadecimal values also avoid special-character escaping in the database connection URL. Leave the default application port at 8787 for the supplied Compose configuration.

docker compose up -d --build

Open http://localhost:8787. Sign in with a display name and the ACCESS_PASSWORD you set. The display name records who last edited an annotation; it is not a separate authenticated account.

The application port is published only on 127.0.0.1, and PostgreSQL has no published host port. Keep these defaults for local use. The first Docker build requires internet access to fetch the container images.

To stop the application while retaining the database:

docker compose down

The database lives in a Docker volume. Adding -v to that command removes its data. Changing POSTGRES_PASSWORD in .env after initial database creation does not change the password stored by PostgreSQL.

Add your threads

1. Install Tampermonkey in the browser where you use Claude or ChatGPT.
2. Create a new userscript and paste in the contents of ai-sidebar-harvester.user.js.
3. In that installed local copy, set ACCESS_PASSWORD to the value from your .env. Check that SERVER_URL points to http://localhost:8787.
4. Save the script and open the relevant AI site while signed in. Use the script's Send control to collect and submit threads, then open the AI Thread Index viewer.

The distributed script has an empty password and automatic collection is disabled. The configured userscript contains a credential: keep your installed copy, userscript backups and any browser sync private.

Collection depends on the source sites' internal APIs and your signed-in browser session. Those APIs can change, and the harvester still needs work on rate-limit handling. Consult the source services' current terms before using it. It reads thread information; it does not provide an independent backup of full conversations.

Test in isolation

The publication safeguards can be checked without Docker using Node.js and Bun on your PATH:

node tests/public-safety.test.cjs

This uses synthetic inputs and mocked browser/network APIs to check credential refusal, unsafe-link handling and the integration suite's target guards. It does not exercise PostgreSQL or live AI websites.

Use the dedicated test stack for API integration:

docker compose -f compose.test.yml up --build --abort-on-container-exit --exit-code-from tests

This configuration uses a separate Compose project, a temporary PostgreSQL database, no published ports and an explicit THREADINDEX_TEST_MODE=isolated opt-in. The tests exercise login, ingestion, annotation writes, revision changes and reconciliation using synthetic data. On 2026-09-09, this suite passed all 24 checks using the supplied Bun 1.4.2 container image and PostgreSQL 17.10. The separate synthetic safeguard suite passed all 17 checks. Run these commands to verify your checkout and environment; these results do not verify current compatibility with live AI websites.

Do not point the API suite at your working database. Its reconciliation cases submit synthetic platform scans, which can mark real records as gone. Use docker compose -f compose.test.yml down to remove the stopped test containers after the run.

Development and scope

server.ts contains the API; schema.sql defines the data model; viewer.html contains the browser interface. The userscript is a separate ingestion client.

AI Thread Index was developed with AI assistance, including Claude and Codex. AI tools contributed code, documentation and review. The architecture, tests and documented limitations are provided so the implementation can be evaluated directly.

This release is a local prototype. Public hosting, stronger account separation, conflict-aware edits, broader imports and full conversation search need further development.