{"id":45030280,"url":"https://github.com/tg-prplx/vellium","last_synced_at":"2026-05-09T12:01:37.683Z","repository":{"id":339128531,"uuid":"1160581879","full_name":"tg-prplx/vellium","owner":"tg-prplx","description":"RP/Writing focused LLM frontend","archived":false,"fork":false,"pushed_at":"2026-02-20T19:32:18.000Z","size":3336,"stargazers_count":52,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-02-23T15:26:11.554Z","etag":null,"topics":["chatgpt","electron","front","gpt","llm","react","writing"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tg-prplx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-18T05:42:35.000Z","updated_at":"2026-02-23T01:42:11.000Z","dependencies_parsed_at":"2026-02-20T06:01:30.902Z","dependency_job_id":null,"html_url":"https://github.com/tg-prplx/vellium","commit_stats":null,"previous_names":["tg-prplx/vellum","tg-prplx/vellium"],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/tg-prplx/vellium","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tg-prplx%2Fvellium","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tg-prplx%2Fvellium/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tg-prplx%2Fvellium/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tg-prplx%2Fvellium/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tg-prplx","download_url":"https://codeload.github.com/tg-prplx/vellium/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tg-prplx%2Fvellium/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29779262,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-24T04:54:30.205Z","status":"ssl_error","status_checked_at":"2026-02-24T04:53:58.628Z","response_time":75,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chatgpt","electron","front","gpt","llm","react","writing"],"created_at":"2026-02-19T05:04:32.433Z","updated_at":"2026-05-09T12:01:37.676Z","avatar_url":"https://github.com/tg-prplx.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Vellium\n\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"1439\" height=\"854\" alt=\"image\" src=\"https://github.com/user-attachments/assets/b4f68d1a-1c12-4abc-b810-1280f3ef49cb\" /\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\u003cstrong\u003eDesktop AI chat, RP, writing, RAG, agent, and plugin workbench.\u003c/strong\u003e\u003c/p\u003e\n\nDesktop app built with Electron, React, a local Express API, and SQLite.\n\n\u003cimg width=\"1440\" height=\"857\" alt=\"image\" src=\"https://github.com/user-attachments/assets/03e75de3-5b39-4012-98f8-4c959eb1fc80\" /\u003e\n\n## Current Release\n\n- Latest release: [`v0.9.7`](https://github.com/tg-prplx/vellium/releases/tag/v0.9.7)\n- Desktop builds: macOS (`arm64`, `x64`), Windows (`x64`), Linux (`x64` AppImage).\n- Release builds are unsigned. macOS and Windows may require manual confirmation on first launch.\n- The app is usable day to day, but still moving quickly. Expect active iteration around Agents, tool calling, and provider compatibility.\n\n## User Documentation\n\n- Detailed user guide: [`docs/vellium/README.md`](./docs/vellium/README.md)\n\n\n## Important\n- Use `npm run dev` for day-to-day development.\n- Use `npm run dev:electron` when testing the real desktop shell.\n- Use `npm run dist:mac`, `npm run dist:win`, or `npm run dist:linux` for platform bundles.\n- CI publishes GitHub Release assets when a `v*` tag is pushed.\n- Local data is stored in `data/` during development and in the Electron user-data directory in packaged builds.\n\n## Stack\n- Electron\n- React + TypeScript + Vite\n- Express\n- SQLite + `better-sqlite3`\n- Tailwind CSS\n\n## Core Features\n\n### Agents\n- Dedicated `Agents` workspace with ask, build, and research modes.\n- Workspace tools for listing, reading, searching, editing, moving, deleting, and diffing files.\n- Optional command execution for tests/builds, with separate security gates for shell-like commands, network commands, destructive file operations, and git writes.\n- OpenAI-compatible structured planning with JSON-schema responses when supported.\n- Mid-run corrections, abort/resume/retry, event traces, reasoning traces, and partial-response recovery.\n- Context management for long agent threads, including auto-compaction, continuation cues, duplicate read-only call guards, and stale-run cleanup after edits/deletes.\n\n### Chat / RP\n- Branching chat history.\n- Edit, delete, resend, regenerate.\n- Multi-character chats with auto-turns.\n- RP controls: prompt stack, author note, scene state, presets, personas.\n- LoreBook / World Info support, including SillyTavern-compatible world info import/export.\n- Reasoning support, including streamed reasoning fields and `\u003cthink\u003e...\u003c/think\u003e` parsing.\n- Vision attachments and chat attachments.\n- MCP tool calling for OpenAI-compatible chat/completions providers, with text-tool-call fallback parsing for providers that do not emit native tool calls cleanly.\n\n### Writing\n- Projects, chapters, scenes, outlines.\n- Summaries, rewrite/expand flows, consistency tools.\n- Character-aware writing workflows.\n- DOCX import and DOCX / Markdown export.\n- Writing-side RAG support.\n\n### Knowledge / RAG\n- Knowledge collections and ingestion.\n- RAG bindings for chat and writing.\n- Embedding and reranker model settings.\n- Hybrid retrieval-oriented foundation.\n\n### Providers\n- OpenAI-compatible providers.\n- KoboldCpp support.\n- Custom endpoint adapters for non-OpenAI / non-Kobold backends.\n- Presets for OpenAI, LM Studio, Ollama, KoboldCpp, OpenRouter, and custom OpenAI-compatible endpoints.\n- Manual fallback models for providers whose `/models` endpoint is missing, empty, or provider-specific.\n- Separate models for translate / compress / TTS / RAG.\n- API parameter forwarding controls for providers that reject unsupported sampling fields.\n\n### Plugins / Extensions\n- Toolbar tabs from plugins.\n- Plugin widgets in chat, writing, and settings slots.\n- Plugin actions in toolbar, messages, composer, and writing.\n- Plugin settings, permissions, plugin-local storage.\n- `Pluginfile` install/export.\n- Plugin themes.\n- Custom inspector fields.\n- Custom endpoint adapters.\n\n\u003cimg width=\"1121\" height=\"705\" alt=\"image\" src=\"https://github.com/user-attachments/assets/ec1b69b0-b8b0-4ca7-b3be-54a4c8f7ee03\" /\u003e\n\n\n## Requirements\n- Node.js + npm. Node.js 20+ is recommended because CI builds with Node 20.\n- Python 3 + Pillow for icon generation:\n\n```bash\npip install pillow\n```\n\nNotes:\n- `better-sqlite3` is native. Keep dev/build Node versions consistent.\n- If native ABI breaks, run `npm run rebuild:native`.\n\n## Quick Start\n\n1. Install dependencies:\n\n```bash\nnpm install\n```\n\n2. Start frontend + local API:\n\n```bash\nnpm run dev\n```\n\n3. Open:\n\n`http://localhost:1420`\n\n## Electron Dev\n\n```bash\nnpm run dev:electron\n```\n\nThis builds Electron entrypoints, starts the local server, starts Vite, waits for health checks, then launches Electron.\n\n## One-Click Bootstrap\n\nmacOS:\n\n```bash\n./setup-and-run-dev.sh\n```\n\nWindows:\n\n```bat\nsetup-and-run-dev.bat\n```\n\nThese scripts try to:\n- install Node.js LTS,\n- run `npm install`,\n- start `npm run dev`.\n\n## Build Desktop App\n\nAll desktop targets:\n\n```bash\nnpm run dist\n```\n\nmacOS only:\n\n```bash\nnpm run dist:mac\n```\n\nWindows only:\n\n```bash\nnpm run dist:win\n```\n\nLinux AppImage only:\n\n```bash\nnpm run dist:linux\n```\n\nBuild output goes to `release/`.\n\n## GitHub Actions\n\nWorkflow:\n- `.github/workflows/build-desktop.yml`\n\nWhat it does:\n- builds macOS (`x64`, `arm64`), Windows (`x64`), and Linux (`x64` AppImage) bundles,\n- uploads workflow artifacts,\n- publishes GitHub Release assets on `v*` tag pushes.\n\n## Plugins\n\nVellium now has a real plugin system.\n\nPlugin capabilities:\n- toolbar tabs,\n- slot widgets,\n- modal and inline actions,\n- plugin-local settings,\n- permission-gated API access,\n- plugin themes,\n- `Pluginfile` import/export.\n\nUseful docs:\n- [`docs/plugins/README.md`](./docs/plugins/README.md)\n\nRuntime plugin locations:\n- user plugins: `data/plugins`\n- bundled plugins: `data/bundled-plugins`\n\nImportant:\n- plugins are local extensions, not a trusted public plugin marketplace model,\n- plugin permissions should be reviewed before enabling write access,\n- plugin settings and permissions are managed in `Settings -\u003e Plugins`.\n\n### Pluginfile\n\n`Pluginfile` is the portable single-file plugin package format.\n\nYou can:\n- install a plugin from `Settings -\u003e Plugins -\u003e Install Pluginfile`,\n- export an existing plugin from `Settings -\u003e Plugins -\u003e Export Pluginfile`.\n\nBundled plugins can also be exported as `Pluginfile`.\n\n## Themes\n\nVellium supports:\n- built-in dark/light themes,\n- plugin-provided themes.\n\nBundled theme pack:\n- Catppuccin\n  - Latte\n  - Frappe\n  - Macchiato\n  - Mocha\n\nTheme plugins also propagate into plugin UI kit styling.\n\n## Extensions API\n\nVellium includes an extensions layer beyond normal plugins:\n- custom inspector fields,\n- custom endpoint adapters,\n- unified plugin-side backend access through `vellium.generate(...)` and related SDK namespaces.\n\nThis makes it possible to:\n- add inspector controls,\n- integrate non-OpenAI / non-Kobold backends,\n- build workflow plugins against a stable host-side contract.\n\n## TTS\n\nVellium supports OpenAI-compatible TTS:\n- configurable endpoint,\n- model selection,\n- voice selection,\n- per-message TTS actions.\n\n## App Icons\n\nGenerate icons:\n\n```bash\nnpm run build:icons\n```\n\nGenerated files:\n- `build/icon.png`\n- `build/icon.icns`\n- `build/icon.ico`\n\n## Useful Scripts\n- `npm run dev` — frontend + server.\n- `npm run dev:frontend` — Vite only.\n- `npm run dev:server` — Express API only.\n- `npm run dev:electron` — Electron + frontend + server.\n- `npm run build` — frontend production build.\n- `npm run build:server` — bundled server build.\n- `npm run build:desktop` — full desktop build pipeline without publishing.\n- `npm run dist` — package all desktop targets supported by the current host/CI runner.\n- `npm run dist:mac` / `npm run dist:win` / `npm run dist:linux` — package a specific desktop target.\n- `npm run rebuild:native` — rebuild `better-sqlite3`.\n- `npm run test` — Vitest.\n\n## Data Storage\n- In dev: local `data/`\n- In packaged app: `SLV_DATA_DIR` maps to Electron `userData/data`\n\n## Troubleshooting\n\n### `ERR_DLOPEN_FAILED` / `NODE_MODULE_VERSION ...`\nCause: `better-sqlite3` was built against a different Node ABI.\n\nFix:\n\n```bash\nnpm run rebuild:native\n```\n\nIf needed, remove `node_modules` and reinstall.\n\n### `EADDRINUSE: address already in use :::3001`\nCause: an old server process is still alive.\n\nFix:\n\n```bash\nlsof -nP -iTCP:3001 -sTCP:LISTEN\nkill -TERM \u003cpid\u003e\n```\n\n### Blank window or long startup in packaged builds\nCheck:\n- full desktop build was used,\n- `server-bundle.mjs` is present,\n- the bundled server reaches `/api/health`.\n\n### Plugins do not load\nCheck:\n- plugin is enabled in `Settings -\u003e Plugins`,\n- required permissions were granted,\n- after changing plugin files, use `Reload Plugins`,\n- after SDK/runtime changes, restart `npm run dev:electron`.\n\n## Project Structure\n- `src/` — React frontend\n- `server/` — Express API\n- `electron/` — Electron main + preload\n- `scripts/` — build/dev helper scripts\n- `docs/` — docs, plugin docs, assets\n- `data/` — runtime data, user plugins, bundled plugins\n- `build/` — electron-builder resources\n- `release/` — packaged desktop output\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftg-prplx%2Fvellium","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftg-prplx%2Fvellium","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftg-prplx%2Fvellium/lists"}