{"id":51503559,"url":"https://github.com/cameroncodesstuff/liqu-companion","last_synced_at":"2026-07-07T22:01:12.161Z","repository":{"id":368508897,"uuid":"1284862070","full_name":"CameronCodesStuff/liqu-companion","owner":"CameronCodesStuff","description":"A highly customizable desktop companion. Pre-installed character + import section for VRM character models.","archived":false,"fork":false,"pushed_at":"2026-06-30T21:44:36.000Z","size":9131,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-30T23:22:30.475Z","etag":null,"topics":["desktop-companion","liqu","liqu-companion"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CameronCodesStuff.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-MODEL/vn3license_en.pdf","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-06-30T09:05:33.000Z","updated_at":"2026-06-30T21:44:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/CameronCodesStuff/liqu-companion","commit_stats":null,"previous_names":["cameroncodesstuff/liqu-companion"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/CameronCodesStuff/liqu-companion","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CameronCodesStuff%2Fliqu-companion","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CameronCodesStuff%2Fliqu-companion/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CameronCodesStuff%2Fliqu-companion/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CameronCodesStuff%2Fliqu-companion/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CameronCodesStuff","download_url":"https://codeload.github.com/CameronCodesStuff/liqu-companion/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CameronCodesStuff%2Fliqu-companion/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35243953,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-07T02:00:07.222Z","response_time":90,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["desktop-companion","liqu","liqu-companion"],"created_at":"2026-07-07T22:01:11.507Z","updated_at":"2026-07-07T22:01:12.147Z","avatar_url":"https://github.com/CameronCodesStuff.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Liqu Desktop Companion\n\nA transparent, always-on-top 3D desktop companion built with **Electron** and **three.js + [@pixiv/three-vrm](https://github.com/pixiv/three-vrm)**. A VRM character floats above your windows, animates naturally, reacts to your cursor, can walk around your screen, and can talk with you by text or voice through your choice of AI provider — including a fully offline option.\n\n\u003ctable align=\"center\"\u003e\u003ctr\u003e\n\u003ctd\u003e\u003cimg src=\"assets/screenshots/character-idle.gif\" alt=\"Character idle animation\" height=\"340\"\u003e\u003c/td\u003e\n\u003ctd\u003e\u003cimg src=\"assets/screenshots/desktop-overlay-cropped.gif\" alt=\"Transparent desktop overlay\" height=\"340\"\u003e\u003c/td\u003e\n\u003c/tr\u003e\u003c/table\u003e\n\n\u003e Bring your own VRM model and (optionally) an AI API key or a local Ollama install.\n\n## Features\n\n**Character \u0026 animation**\n- Supports **VRM, GLTF/GLB, FBX, and OBJ** model formats — drop any of them in directly or inside a zip\n- VRM models get full support: expressions, eye tracking, spring-bone wind, blend shapes\n- Other formats load, render, and auto-frame correctly; VRM-specific features gracefully degrade\n- Frameless, transparent, always-on-top window\n- Natural procedural animation: layered breathing, weight shifting, per-bone follow-through, and quaternion-based pose blending (no rigid snapping)\n- 28 selectable poses/behaviors (wave, sit, dance, think, stretch, walk, and more)\n- Constant turbulent wind on hair/cloth physics, with a stronger gust pose\n- Eyes track your cursor independently of the head\n- Blinking, expressions, and a brief surprised reaction when you poke the character\n- Auto-sleep when idle; idle variation so it never loops one motion\n- Drag the character (or the handle) to move it anywhere\n\n**Movement**\n- **Wander** — roams between screen edges on its own\n- **Follow the cursor** — walks after your mouse\n- **Come here** — walks to your cursor once\n- Edge-snapping when you drop it near a screen border\n\n**AI \u0026 voice**\n- Chat by text or voice (mic button)\n- Providers: **Anthropic (Claude)**, **OpenAI (GPT)**, **Google (Gemini)**, and **Ollama** (local, offline, free)\n- Model field auto-fills a sensible default per provider, with a dropdown of common models\n- Optional persistent memory across restarts\n- Optional real API TTS (OpenAI / ElevenLabs) with amplitude-based lip-sync\n- Optional vision: the character can look at your screen and react\n\n**System**\n- Global hotkey `Alt+Shift+L` to show/hide\n- Open on system startup\n- Optional clipboard-context and CPU-load awareness\n- \"Hide everything but the character\" mode\n- Settings persist across restarts\n\nA built-in **Help** tab inside the app lists where to get API keys and VRM models.\n\n## Quick start\n\nRequires [Node.js](https://nodejs.org) 18+.\n\n```bash\ngit clone https://github.com/CameronCodesStuff/liqu-companion.git\ncd liqu-companion\nnpm install\nnpm start\n```\n\nOr, with no terminal:\n- **Windows:** double-click `start.bat`\n- **macOS / Linux:** double-click / run `start.sh`\n\nThe first run installs dependencies automatically.\n\n## Adding a character\n\nOpen **Settings → Appearance** and drop a `.zip` containing a `.vrm` file onto the import box (or click to browse). Imported characters are stored in your user-data folder and can be renamed or deleted in-app.\n\nWhere to find free VRM models:\n- [VRoid Hub](https://hub.vroid.com) — many free models (check each license)\n- [VRoid Studio](https://vroid.com/en/studio) — make your own\n- [Booth.pm](https://booth.pm) — search 無料 (free)\n\n## Setting up AI\n\nOpen **Settings → AI**, pick a provider, and paste an API key:\n\n| Provider | Get a key at |\n| --- | --- |\n| Anthropic (Claude) | [console.anthropic.com](https://console.anthropic.com) |\n| OpenAI (GPT) | [platform.openai.com](https://platform.openai.com) |\n| Google (Gemini) | [aistudio.google.com](https://aistudio.google.com) |\n| ElevenLabs (voice) | [elevenlabs.io](https://elevenlabs.io) |\n\n### Offline \u0026 free (Ollama)\n\n1. Install [Ollama](https://ollama.com).\n2. Pull a model: `ollama pull llama3.2` (or `llama3.2-vision` for the vision feature).\n3. In the AI tab, choose **Ollama**, confirm the URL, and click **Test**.\n\nNo API key required — runs fully local and private.\n\nKeys are stored locally via `electron-store` in your OS user-data folder, in plain form — suitable for a personal machine, not a hardened secrets vault.\n\n## Building installers\n\n```bash\nnpm run dist        # current platform\nnpm run dist:win    # Windows installer (.exe, NSIS)\nnpm run dist:mac    # macOS .dmg\nnpm run dist:linux  # Linux AppImage / .deb\n```\n\nThe Windows build is a full setup wizard (choose install folder, shortcuts, run-on-finish) and registers an uninstaller in **Add or Remove Programs**. Replace the placeholder icons in `assets/icons/` with your own before a real release.\n\n\u003e Building a `.exe` requires Windows; a `.dmg` requires macOS. Code-signing requires your own developer certificate and is not configured here.\n\n## Project structure\n\n```\nliqu-companion/\n├── package.json\n├── start.bat / start.sh            # one-click launchers\n├── build-installer.bat / .sh       # build native installers\n├── src/\n│   ├── main.js                     # Electron main: window, tray, movement, AI proxy, IPC\n│   ├── preload.js                  # secure context bridge\n│   └── renderer/\n│       ├── index.html\n│       ├── style.css\n│       └── companion.js            # three.js scene, animation, AI/voice, UI\n└── assets/\n    ├── model/                      # bundled VRM\n    └── icons/                      # app + tray icons\n```\n\n## Tech\n\nElectron · three.js · @pixiv/three-vrm · electron-store · JSZip. `three`, `three-vrm`, and `jszip` load via an import map from a CDN, so first run needs an internet connection; bundle them locally (esbuild/Vite) for a fully offline build.\n\n## Notes \u0026 limitations\n\n- Pose values target a standard VRM humanoid rig; unusual rigs may need tuning (see the pose definitions in `companion.js`).\n- Voice input uses the browser's built-in speech recognition (online), not a bundled offline model.\n- Real amplitude lip-sync requires API TTS; otherwise mouth movement is approximated from word timing.\n\n## License\n\nCode: see repository. Bundled VRM models retain their original creators' licenses — see `LICENSE-MODEL/`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcameroncodesstuff%2Fliqu-companion","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcameroncodesstuff%2Fliqu-companion","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcameroncodesstuff%2Fliqu-companion/lists"}