sessiongraph 0.0.0-stage → 0.1.9

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Vilchis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PRIVACY.md

@@ -0,0 +1,51 @@
+# Privacy and local data
+
+**Your session content stays on your computer while you import, search, and explore it in SessionGraph.** No SessionGraph account is required. SessionGraph has no cloud sync and sends no analytics or crash reports.
+
+## What happens locally
+
+- Imports read only the sources you select. Source histories are not modified, and importing does not start an agent, resume a conversation, or invoke a model.
+- Auto-import is enabled by default after source selection. It checks on startup, when returning to the app, and every minute while visible. Disable it in **Settings → Sources → Auto-import sessions**; this choice is saved in the local library and survives desktop restarts. Disabling it stops future automatic checks; an import already running can finish.
+- Parsing, indexing, search, and visualization run on your computer. Search does not use a remote embeddings or model service.
+- Imported conversations, metadata, timeline events, file-change evidence, and search checkpoints are saved in SessionGraph's local SQLite library.
+- View filters, time ranges, and appearance preferences are saved in the local SQLite library. Appearance preferences are also cached in browser/WebView local storage. Fonts and application assets are bundled.
+- Saved history remains available when a source is offline. Deselecting a source stops future imports; it does not delete previously imported history. Clearing the search index preserves imported history.
+
+## Network access
+
+| Action | Connection | Session content sent externally by SessionGraph |
+| --- | --- | --- |
+| Browse, search, and visualize saved history | Authenticated backend on `127.0.0.1` | None |
+| Import OpenCode history | OpenCode's authenticated loopback API; OpenCode must be running locally | None |
+| Import Claude Code, Codex, or Cursor history | Local history reads | None |
+| Check for or download desktop updates | GitHub Releases and its download infrastructure | None |
+| Install or update through npm | npm registry and its download infrastructure | None |
+| Open an external link | Your browser opens the destination you choose | The destination's normal browser/privacy behavior applies |
+| Continue a session in another harness | An explicit launch opens the selected harness | The harness may send saved context to its model provider under its own settings |
+
+The desktop app checks for updates automatically. GitHub and npm receive ordinary request metadata, such as your public IP address, when contacted. Update requests do not include your conversations, search terms, file paths, or session identifiers. SessionGraph therefore does not promise zero internet connections.
+
+Preparing a cross-harness continuation may write a local Markdown handoff containing saved conversation context. Preparing or copying the command does not start an agent. Running it allows the destination harness to read that context; that harness's privacy policy and configuration apply.
+
+## Where data is stored
+
+New installations use:
+
+- **macOS:** `~/Library/Application Support/SessionGraph/sessiongraph.sqlite`
+- **Windows:** `%LOCALAPPDATA%/SessionGraph/sessiongraph.sqlite`
+- **Linux:** `$XDG_DATA_HOME/sessiongraph/sessiongraph.sqlite`, defaulting to `~/.local/share/sessiongraph/sessiongraph.sqlite`
+
+`SESSIONGRAPH_DATA_DIR` overrides the location. Existing Session Atlas or Atlas libraries can be reused in place; see [storage resolution](docs/guide.md#local-storage-and-privacy). SQLite may also create `-wal` and `-shm` companion files. Saved-context Markdown files live in the library directory's `handoffs/` folder.
+
+**SessionGraph does not encrypt its database, search text, or handoff files.** Local filesystem permissions protect access where supported. Your OS account, disk encryption, device security, and backup/sync configuration affect confidentiality. SessionGraph does not control backups or the original harnesses' storage and cloud services.
+
+Application bundles and npm packages contain application assets, not your imported library. The repository's demo images and video use synthetic sessions.
+
+## How to verify the behavior
+
+- Inspect the [source adapters](server/adapters/), [local API](server/standalone.ts), [search worker](src/search/worker.ts), and [desktop updater](src/updater.ts).
+- After importing a library, disconnect from the internet and browse/search it. OpenCode imports additionally require its local service, but browsing saved history does not.
+- Use an OS-level network monitor or firewall to inspect both the native app and its bundled Node backend. Browser developer tools alone do not show native updater traffic. Distinguish update checks from actions that explicitly open another application.
+- Compare downloaded artifacts with the release's `SHA256SUMS`. The desktop updater verifies version-bound signatures before installation. These establish artifact integrity and authenticity; they are not a privacy audit.
+
+These statements describe SessionGraph's implemented behavior. They are not a claim of an independent security audit or protection against other software with access to your device.

package/README.md

@@ -1,3 +1,77 @@
-# Temporary Holding Version
+<h1 align="center">SessionGraph</h1>
+<p align="center">Explore &amp; visualize all your LLM sessions</p>
+<p align="center">
+  <a href="https://github.com/arvindell/sessiongraph/releases/latest">Download</a> ·
+  <a href="docs/guide.md">Documentation</a> ·
+  <a href="PRIVACY.md">Privacy</a> ·
+  <a href="docs/releases.md">Releases</a>
+</p>
 
-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.
+[![SessionGraph in action: playback, search, messages, and settings using synthetic sessions](docs/sessiongraph-demo.gif)](https://github.com/arvindell/sessiongraph/releases/latest/download/sessiongraph-demo.mp4)
+
+Explore **OpenCode, Claude Code, Codex, and Cursor** in one local-first app.
+Search conversations, explore clickable messages and tool calls, inspect changed files, and continue in another harness.
+Hover to preview messages, click to focus, and tune the glowing map, trails, and click sounds in Settings.
+Importing, searching, and visualization stay on your computer.
+
+### Your history stays local
+
+**No account. No cloud sync. No telemetry.** SessionGraph reads your selected local sources and keeps imported conversations and the search index on your computer. Importing and exploring history never starts an AI agent or sends your conversations to a model provider.
+
+Desktop update checks and downloads contact GitHub without session content; npm installation contacts the npm registry. Explicitly continuing a session opens your chosen harness, which follows its own network and privacy settings. Saved history is not encrypted by SessionGraph; device access and backups affect its confidentiality.
+
+[Read the privacy details, storage locations, and verification steps →](PRIVACY.md)
+
+### Install
+
+Download the latest desktop app — no Node.js required:
+
+| Platform | Direct downloads |
+| --- | --- |
+| macOS · Apple Silicon | [DMG](https://github.com/arvindell/sessiongraph/releases/latest/download/sessiongraph-darwin-arm64.dmg) |
+| macOS · Intel | [DMG](https://github.com/arvindell/sessiongraph/releases/latest/download/sessiongraph-darwin-x64.dmg) |
+| Windows · x64 | [EXE](https://github.com/arvindell/sessiongraph/releases/latest/download/sessiongraph-win32-x64.exe) · [MSI](https://github.com/arvindell/sessiongraph/releases/latest/download/sessiongraph-win32-x64.msi) |
+| Linux · x64 | [AppImage](https://github.com/arvindell/sessiongraph/releases/latest/download/sessiongraph-linux-x64.AppImage) · [DEB](https://github.com/arvindell/sessiongraph/releases/latest/download/sessiongraph-linux-x64.deb) · [RPM](https://github.com/arvindell/sessiongraph/releases/latest/download/sessiongraph-linux-x64.rpm) |
+| Linux · ARM64 | [AppImage](https://github.com/arvindell/sessiongraph/releases/latest/download/sessiongraph-linux-arm64.AppImage) · [DEB](https://github.com/arvindell/sessiongraph/releases/latest/download/sessiongraph-linux-arm64.deb) · [RPM](https://github.com/arvindell/sessiongraph/releases/latest/download/sessiongraph-linux-arm64.rpm) |
+
+Desktop updates appear as a small **Update** pill. Download and verify, then click **Restart** when you're ready.
+
+The npm launcher requires **Node.js 24+** (registry publishing is being finalized; use the downloads above for now):
+
+```sh
+npx sessiongraph
+npx sessiongraph --browser
+```
+
+- **`sessiongraph`** opens the native desktop app for your OS, with its own local backend and bundled runtime.
+- **`sessiongraph --browser`** starts an authenticated localhost server and opens the same explorer in your default browser. Keep the terminal running; **Ctrl+C** stops it.
+- Both use the same saved local library. Import once, explore in either mode.
+
+### Harness support
+
+| Harness | Import from | Continue sessions |
+| --- | --- | --- |
+| <img src="public/sources/opencode.svg" width="14" alt=""/> **OpenCode** | Authenticated local API; run OpenCode when importing | Native resume / saved-context handoff |
+| <img src="public/sources/claude.svg" width="14" alt=""/> **Claude Code** | Local projects, worktrees, and subagents via SDK | Native resume / saved-context handoff |
+| <img src="public/sources/openai.svg" width="14" alt=""/> **Codex** | Active and archived local rollouts | Native resume / saved-context handoff |
+| <img src="public/sources/cursor.svg" width="14" alt=""/> **Cursor** | IDE transcripts, CLI and ACP stores | CLI resume where supported / saved-context handoff |
+
+Import is read-only. Saved sessions remain available when a harness is offline. [Coverage and limitations →](docs/guide.md#source-coverage)
+
+Choose harnesses in **Settings → Sources** or **Manage sources** next to the source filter. **Auto-import is on by default**: SessionGraph checks for new and changed sessions on startup, when you return, and every minute while visible. Turn it off in **Settings → Sources → Auto-import sessions**. **Refresh sessions** also works manually.
+
+Your time range, source/project/directory filters, archived and child-session toggles, and appearance preferences are saved with the local library and restored after restarting.
+
+### Develop
+
+```sh
+pnpm install
+portless sessiongraph pnpm dev
+```
+
+`pnpm desktop:dev` runs the native app. `pnpm test` runs the tests.
+See the [guide](docs/guide.md) for source coverage, shortcuts, storage, and building locally.
+
+### License
+
+[MIT](LICENSE) © 2026 Alex Vilchis.

package/bin/sessiongraph.mjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+
+const require = createRequire(import.meta.url);
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+const args = new Set(process.argv.slice(2));
+if (args.has('--version')) { console.log(`SessionGraph ${pkg.version}`); process.exit(0); }
+if (args.has('--help')) {
+  console.log(`SessionGraph — Explore & visualize all your LLM sessions\n\n  npx ${pkg.name}            Open the desktop app\n  npx ${pkg.name} --browser  Open the local browser app\n\nChoose session sources on first launch. All imports and indexing stay local.`); process.exit(0);
+}
+if (Number(process.versions.node.split('.')[0]) < 24) { console.error('SessionGraph requires Node.js 24 or later for its launcher.'); process.exit(1); }
+function open(target) {
+  const [file, params] = process.platform === 'darwin' ? ['open', [target]] : process.platform === 'win32' ? ['rundll32.exe', ['url.dll,FileProtocolHandler', target]] : ['xdg-open', [target]];
+  const child = spawn(file, params, { stdio: 'ignore', detached: true });
+  child.on('error', () => console.error('Could not open the application. Check your desktop environment.')); child.unref();
+}
+if (!args.has('--browser')) {
+  const name = `${pkg.name}-app-${process.platform}-${process.arch}`;
+  try {
+    const manifest = require.resolve(`${name}/package.json`);
+    const app = join(dirname(manifest), 'payload', process.platform === 'darwin' ? 'SessionGraph.app' : process.platform === 'win32' ? 'SessionGraph.exe' : 'SessionGraph.AppImage');
+    if (process.platform === 'darwin') open(app);
+    else { const child = spawn(app, [], { detached: true, stdio: 'ignore', env: { ...process.env, ...(process.platform === 'linux' ? { APPIMAGE_EXTRACT_AND_RUN: '1' } : {}) } }); child.on('error', (e) => console.error(`SessionGraph could not open: ${e.message}`)); child.unref(); }
+  } catch {
+    console.error(`Desktop package ${name} is not installed.\nUse npx ${pkg.name} --browser, or install the matching desktop package.\nFor a source checkout: pnpm desktop:dev`); process.exitCode = 1;
+  }
+} else {
+  const child = spawn(process.execPath, [join(root, 'dist-server', 'server.mjs'), '--assets', join(root, 'dist'), '--parent-pid', String(process.pid)], { stdio: ['ignore', 'pipe', 'inherit'] });
+  child.on('error', (e) => { console.error(e.message); process.exitCode = 1; });
+  const lines = createInterface({ input: child.stdout });
+  lines.once('line', (line) => {
+    try { const { url } = JSON.parse(line); open(url); console.log('SessionGraph is open in your browser. Press Ctrl+C to close the local server.'); }
+    catch { console.error('SessionGraph local server did not start.'); child.kill(); }
+  });
+  child.on('exit', (code) => { process.exitCode = code || 0; });
+  for (const signal of ['SIGINT', 'SIGTERM']) process.on(signal, () => { child.kill(); });
+}