From clone to first answer in 60 seconds
No config files, no separate server. Clone the repo, install with bun, seed the demo e-commerce database, push the Prisma schema, and start the dev server. Type "demo" and you're in.
01Prerequisites
SelectStar runs on Next.js 16 with Turbopack and requires Node 20+ and Bun. It connects to SQLite (out of the box), PostgreSQL (via pg), or MySQL (architecture-ready). You'll need an OpenAI-compatible LLM — the default is the z-ai-web-dev-sdk pointed at OpenCode Zen. See Configuration to swap providers.
Required by Next.js 16 with Turbopack. Check with `node --version`.
Package manager & script runner. Check with `bun --version`.
SQLite is bundled. PostgreSQL via `postgresql://`. MySQL is architecture-ready.
z-ai-web-dev-sdk (default), OpenAI, vLLM, Ollama, or LM Studio.
02Clone & install
Clone the repo from GitHub and install dependencies with bun. SelectStar pulls in Next.js 16, Prisma 6, better-sqlite3, pg, react-vega, framer-motion, zustand, sonner, and the z-ai-web-dev-sdk in one install.
# Clone the repo
git clone https://github.com/Shyamnath-Sankar/SelectStar.git
cd SelectStar
# Install dependencies (bun is recommended)
bun install
# npm, pnpm, and yarn also work:
# npm install
# pnpm install
# yarn install03Seed the demo database
SelectStar ships with a realistic e-commerce SQLite database — 6 tables, ~3,200 orders, ~8,000 line items. Running the seed script creates db/demo.db so you can explore the full agent pipeline immediately. You can also run the Node-compatible version with node scripts/seed-demo.js.
# Seed the demo e-commerce database (creates db/demo.db)
bun run scripts/seed-demo.ts
# Tables created:
# regions (6 rows)
# customers (480 rows)
# categories (12 rows)
# products (180 rows)
# orders (~3,214 rows)
# order_items (~8,142 rows)04Push the Prisma schema
SelectStar uses Prisma + SQLite to store its own sessions, chat messages, canvas objects, and audit logs. Push the schema to create the app's own database tables. This is separate from the demo database — the app DB stores SelectStar's metadata, not your data.
# Push the Prisma schema (creates the app's own SQLite DB)
bun run db:push
# If you edit prisma/schema.prisma later, re-run:
# bun run db:generate # regenerate the Prisma client
# bun run db:push # push the new schema
# To reset the app DB entirely (DESTRUCTIVE — drops all sessions):
# bun run db:reset05Start the dev server
Start the Next.js 16 dev server with Turbopack. Open http://localhost:3000 and you'll see the connection screen. The dev server hot-reloads on every file change.
06Your first turn
Type "demo" in the connection string field, click Connect. You'll see suggested starter questions based on the real schema. Try one — watch the agent pipeline run end-to-end in the chat pane, with structured artifacts landing in the canvas.
Try these starter questions:
- • "How many orders are there, broken down by status?"
- • "Show me the distribution of order totals."
- • "Chart the top 8 products by total sales as a bar chart."
- • "Give me a statistical profile of the products table."
- • "Cluster the products into 3 groups based on price and stock."
- • "Forecast the next 6 months of order counts."
Watch the chat pane for live agent steps: 🧭 Router → ⌘ SQL → 📊 EDA / 📈 Viz / 🧠 ML → ✦ Synthesis.
07Try Classic Mode (CSV / XLSX)
Don't have a database handy? Switch to Classic Mode on the connection screen and upload a CSV, TSV, XLSX, XLSM, XLSB, or ODS file (up to 25 MB each). Each XLSX sheet becomes its own table, and you can upload multiple files — the agent can JOIN across them. Edit cells directly in the spreadsheet grid; the SQL agent sees your edits live.
# In the browser:
# 1. Click "Classic Mode" on the connection screen
# 2. Drag in one or more files (.csv, .tsv, .xlsx, .xlsm, .xlsb, .ods)
# 3. Max 25 MB per file
# 4. Click "Upload"
# What happens server-side:
# - Each file is parsed (XLSX → one table per sheet)
# - All tables register in the same in-memory SQLite workspace
# - The agent can JOIN across tables from different files
# - You can edit cells via the spreadsheet grid
# - SQL queries see your edits live
# - Export the edited table back out as CSV or XLSX08Troubleshooting
bun install fails on better-sqlite3
better-sqlite3 is a native module. Make sure you have build tools installed (Python 3, make, g++). On Linux: `sudo apt install python3 make g++`. On macOS: `xcode-select --install`. On Windows: install windows-build-tools.
Demo DB seed fails with 'file already exists'
Delete db/demo.db and db/demo.db-shm and db/demo.db-wal, then re-run `bun run scripts/seed-demo.ts`. The seed script doesn't overwrite by default.
Prisma db:push fails
Make sure you've run `bun install` first (it runs prisma generate as a postinstall). If the app DB is in a bad state, delete db/app.db and re-run `bun run db:push`.
LLM calls fail with 401 / connection refused
Check your .env.local — LLM_BASE_URL, LLM_API_KEY, and LLM_MODEL must be set. The default uses z-ai-web-dev-sdk pointed at OpenCode Zen. See Configuration to swap providers.
Classic Mode upload fails with 413
Files are limited to 25 MB each. If your file is larger, split it into multiple smaller files (the agent can JOIN across them) or sample the data down.
Next steps
Now that SelectStar is running, configure your LLM provider or dive into the architecture.