Help & installation

The fastest way — no download:

1. Open https://vibe.codes-ai.uk
2. Create an account or sign in
3. Choose a workspace if you belong to more than one team, or create a new workspace
4. Start at Learn (courses & plan wizard), Composer, or Board
5. VS Code: Settings → Integrations for a token, then install the extension

Quick links (after sign-in): Learn hub · Build my plan · Teaching hub (admins)

Full in-app guide: sign in → Learn → Studio guide (/learn/docs).

Each workspace is an independent team: its own members, projects, learning progress, and settings. Your one account can belong to many workspaces.

Sign in

• One workspace — you enter it automatically
• Several workspaces — you see the Choose workspace picker (/choose-workspace)
• No workspace yet — create one on onboarding or accept an invite

Switch workspace

• Use the dropdown under the workspace name in the sidebar (or top bar)
• Or open Settings → Switch workspace
• Only workspaces you've been added to appear — invites are per workspace

Desktop team join

1. Admin copies the workspace join code from Settings
2. Teammate installs desktop, chooses Team member, enters code + email/password
3. Same login works on web — pick the workspace after sign-in if needed

Structured 60-day courses with daily scheduler, skills, and progress stored in your workspace database.

Professional paths (new in v0.2.1)

• Practical bookkeeping & accounting — AAT-aligned: double-entry, VAT, payroll, month-end
• Travel agency operator — IATA-style: quotes, GDS basics, ATOL, disruption ops

More learning

• Beginner path — computer basics → typing → kids coding → web fundamentals
• Concept labs — science, mathematics, arts PDFs + team progress
• Meta / Facebook marketing · Python · AI English
• Build my plan wizard — goals, diagnostic, auto-enrollment

Your personal dashboard: /learn/dashboard. Track adherence, streaks, and course completion there.

Admins and owners open the Teaching hub at /teach to monitor all learners in the workspace.

Teacher dashboard tabs

• Overview — team stats, course charts, top Watchdog alerts
• Watchdog — learners needing attention (no plan, inactive, low adherence, stalled courses)
• Roster — per-member courses, approve days, search
• Skills — team-wide mastery map on beginner-path courses
• Concept labs — who viewed/downloaded lab assets

Email & Slack alerts (Watchdog tab)

1. Open /teach → Watchdog tab → Email & Slack alerts
2. Set recipients, Slack webhook URL, critical-only vs warnings, digest interval
3. Optional server env: RESEND_API_KEY or SMTP_*, SLACK_WATCHDOG_WEBHOOK_URL
4. Use Send digest now to test; auto-sends when alerts change (throttled)

Members use /learn/dashboard only — full team roster is admin-only.

Class and course lecture editors support multiple locales — English, اردو (Urdu), German, and more — without overwriting the source language.

Where to edit

• Class lecture plan — open a class → lecture organizer tab; add locales, translate with AI, or dictate in ur-PK
• Course day editor — per-day content with locale tabs, RTL preview for Urdu, and bilingual split view

Urdu (RTL)

• Nastaliq typography and right-to-left layout in preview
• Per-locale slots stored in translations JSON — source locale stays intact
• AI translate via workspace course AI settings (Settings → Courses)

From any board task or support ticket, use Send to Claude to copy markdown, export a .md file (desktop), share an API link, or push to the in-app Claude terminal.

Claude Code (auto-fetch)

1. Settings → Integrations — create an API token
2. Download CLAUDE.md + fetch-sparkvibe-ticket.mjs into your Claude Code project
3. Set SPARKVIBE_API_TOKEN and SPARKVIBE_API_BASE in your shell
4. Paste a task UUID from the board drawer → node scripts/fetch-sparkvibe-ticket.mjs task <UUID> --markdown

API: GET /api/ext/tasks/{id} and /api/ext/support/{id} with Authorization: Bearer sv_…

Pull SparkVibe prompts into Visual Studio Code or Cursor. The sidebar has three folders — they are not the same as the web Vibe Library tabs.

What each folder means

• Starters — SDLC templates (PRD, user stories, architecture, code review, etc.). Always available when connected; same curated set as Learn → Templates.
• Library — prompts you saved in Composer (Composer → Save). Empty until you save at least one. Same data as Vibe Library → My prompts.
• History — past versions of saved prompts (time-travel snapshots). Fills in after you save or update prompts.

Course lectures and teaching content live under Teach → Courses — they do not appear in the VS Code panel. Use Composer + browser for lectures; use VS Code for coding prompts and Claude Code.

Step 1 — Get a token

1. Open Settings → Integrations (any signed-in member — tokens are personal).
2. Click Generate token, label it e.g. VS Code · laptop, and copy the token immediately (starts with svk_).
3. Copy the Server URL on that page (e.g. https://vibe.codes-ai.uk) — no trailing slash.

Tokens are scoped to the workspace you were in when you generated them. Switch workspace in the browser and regenerate the token if Library looks empty but you have saves elsewhere.

Step 2 — Install the extension

Not on the public Marketplace — install from the SparkVibe repo (vscode-extension/) or a .vsix file:

1. cd vscode-extension && npm install && npm run compile
2. npm run package → vibe-studio-0.1.1.vsix
3. VS Code: Extensions (Ctrl+Shift+X) → … → Install from VSIX…
4. Or press F5 with the vscode-extension folder open (Extension Development Host).

Step 3 — Connect

1. Activity bar → Vibe Studio (spark icon).
2. Command Palette → Vibe Studio: Connect → Server URL + token.
3. Confirm the toast: connected to {workspace} as {email} · N saved, M starters.
4. Expand Starters first — you should see templates even if Library is empty.

Panel actions

• Send to Claude — opens a Claude terminal and pipes the prompt (Claude Code CLI on PATH).
• Insert into editor / Copy prompt / Open prompt as Markdown.
• Send to terminal — active integrated terminal.
• Vibe Studio: Refresh — reload after saving new prompts in the browser.

Library empty?

• Normal if you have not saved in Composer yet — use Starters or save a prompt in the browser, then Refresh.
• Wrong workspace — regenerate token in the workspace where your prompts live.
• Token rejected — full svk_… token; reconnect via Vibe Studio: Connect.
• Server URL must match where you saved prompts (e.g. https://vibe.codes-ai.uk).

Settings (VS Code)

Ctrl+, → search “Vibe Studio”: vibeStudio.serverUrl, vibeStudio.claudeCommand (default claude), vibeStudio.autoSubmit, vibeStudio.historyLimit.

How VS Code and Vibe Studio fit together

• Author in Vibe Studio (web) — build prompts/plans in Composer, save them to the Library.
• Pull in VS Code / Cursor — the extension lists your Starters, Library, and History; insert into the editor or hand to Claude Code.
• Run on a device — or skip the copy/paste entirely: use Send to device (below) to queue the prompt for the SparkVibe agent to run in the Claude CLI.

More detail: Vibe Studio guide → VS Code · full extension reference (GitHub)

Run SparkVibe prompts and tickets on your own machines. A lightweight agent on each device polls the server (outbound only — no open ports, works behind NAT) and runs work through your local Claude CLI, asking you to confirm first.

Set it up

1. Open Devices → Register a device. Copy the one-time token (starts with svd_) — it's shown only once.
2. Tick the projects this machine may run, then Save projects.
3. Run the agent on that machine (see Claude CLI agent settings below).

Send work to a device

• Composer — the Send to device button on a generated prompt.
• Board / tickets — Send to device in the task drawer sends the ticket key, title, and description.
• Telegram or the mobile app — pick a device + project and send from your phone.

Each queued item appears under Recent commands with its status; the device confirms before running and streams the result back.

The agent lives in the agent/ folder of the repo (zero dependencies, Node ≥ 18). Configure it with environment variables or a sparkvibe-agent.config.json file next to it.

Connect

• SPARKVIBE_URL — your server, e.g. https://vibe.codes-ai.uk
• SPARKVIBE_DEVICE_TOKEN — the svd_… token from Devices

How it runs prompts

• runCommand / runArgs — default claude -p "{prompt}". {prompt} is replaced with the payload; arguments are passed directly (no shell injection). Change these for a different CLI or flags.
• projects — map each project key to its local folder, e.g. { "WEB": "/code/web", "API": "C:/code/api" }. Falls back to the project's linked path, then the current directory.
• Confirm-before-run is the default; pass --yes (or autoRun) to run hands-free.

Run it

SPARKVIBE_URL=… SPARKVIBE_DEVICE_TOKEN=svd_… \
  node agent/sparkvibe-agent.mjs

Flags: --once (process one and exit), --yes (auto-run), --terminal (allow remote shells), --url / --token / --config.

Open an interactive shell on a device — like a VS Code terminal, but driven from the SparkVibe web or mobile app. Output streams back and you type commands in the app.

1. Run the agent with --terminal (off by default — the device operator opts in). Set SPARKVIBE_SHELL to choose the shell (defaults: bash, or cmd.exe on Windows).
2. On Devices (or the mobile app), pick a project under Remote terminal → Open terminal.
3. Type commands; results stream into the panel. Closing the panel or revoking the device ends the shell.

It is command/output oriented (great for scripts and build/test) — not a full TTY for apps like vim.

For full screen control of a device (beyond the in-app terminal), SparkVibe runs a self-hosted RustDesk relay. Connections route through your own server — not RustDesk's public one.

How it works

Every device running RustDesk pointed at your relay gets a unique ID. The relay is a matchmaker, not a middleman that stores your screen: the hbbs server introduces the two devices and tries to open a direct peer-to-peer link; if the networks won't allow that (strict NAT/firewall), the encrypted stream falls back through the hbbr relay. The shared Key encrypts the handshake and gates who may use the relay.

Both devices must be configured to the same relay to see each other. A device left on RustDesk's public network cannot connect to one on your relay — they're in different "phone books".

1 — Point a device at your relay

1. Install the free RustDesk client on the device (phone and PC).
2. RustDesk → Settings → Network → ID/Relay Server (unlock the row if it's locked). Copy from the Devices page relay card:
   • ID Server — relay host/IP from Devices
   • Relay Server — the same host (set it explicitly; better for mobile)
   • API Server — leave empty (Pro/web console only — not used by SparkVibe's OSS relay)
   • Key — relay public key (ends in =)
3. Click OK. Bottom-left status should go 🟢 Ready within a few seconds.
4. Note the device's ID, and set a permanent password on the PC for unattended access.

API Server ≠ SparkVibe API. Mobile app Settings (server URL / token) is only for Devices · Board · prompts. Putting vibe.codes-ai.uk (or any URL) into RustDesk's API Server causes Ready↔disconnect loops.

Stability fine-tune (stops most disconnects)

• Same Network card on both ends — phone and PC must share identical ID / Relay / Key; API empty on both.
• PC always-on — install RustDesk as a service / start on boot; permanent password; unlock screen if Windows sleeps.
• Mobile battery — disable battery optimization for RustDesk; keep it in foreground while controlling.
• Flaky NAT — in session options, prefer / force relay if direct P2P keeps dropping (cellular ↔ home Wi‑Fi often needs relay).
• Quality — drop resolution / FPS on mobile if bandwidth is weak; audio off if you only need control.

Red / "please check your connection" usually means a mistyped host, API Server filled by mistake, or ports 21115–21119 blocked.

2 — Connect

From SparkVibe: paste the device's ID into its card on the Devices page; Connect opens rustdesk://<id>, which dials through this same relay.

From RustDesk directly (either direction — both devices must be 🟢 Ready on your relay):

• You → them: type their ID in "Control Remote Desktop" → Connect → enter their password.
• Them → you: they type your ID + your password (or you click Accept on the incoming prompt).

Access control

Knowing an ID is not enough to control a device. The connection requires either the remote device's permanent password (for unattended access) or someone at that device clicking Accept on the incoming prompt. Clear the three Network fields any time to put a device back on the public RustDesk network.

The relay key is shared across your team — don't publish it. Anyone with the address + key can use the relay.

Send ready prompts and tickets to your devices from a Telegram chat.

1. Settings → Integrations → Telegram relay → copy the /start <code> command.
2. Send it to your workspace's SparkVibe bot to link the chat.
3. Then: /devices, /device <n>, /project <KEY>, /prompt <text>, /task <KEY>.

Requires TELEGRAM_BOT_TOKEN set on the server (admin). The device still confirms before running.

Each workspace can switch whole feature areas on or off, so a delivery-only team needn't see Teaching or Study.

• Admins: Settings → Workspace → Workspace modules — toggle Teaching, Study, Library, Vibe Studio, Remote assist. Disabled modules disappear from members' sidebar; admins always keep access so they can re-enable.
• Superadmins (platform level): Superadmin sets each module to Workspace decides, On for everyone, or Off everywhere across all workspaces, and reviews every workspace.

Context Vault is your personal, markdown context for a workspace — so you don't re-brief every AI tool. Three parts, three verbs: Save a session, Pin insights, Load it back.

The three Context files

• Profile — stable facts: who you are, your stack, how you work, hard rules.
• Projects — each project with status & stack.
• Current State — living: this week's focus, deadlines, what's in flight.

Edit them on the Context tab and click Save. The Pin bar appends a one-line insight to whichever file you choose.

Save a session

On the Sessions tab, give it a title, paste rough notes, optionally pick a project to scope it, and Save. Don't want to format it yourself? Draft with AI structures your notes into Decisions / Learned / Files touched / Next actions (uses your workspace LLM — set one in Settings → LLMs).

Load it into any AI tool

The Load tab assembles Profile + Projects + Current State + your latest sessions into one markdown brief — Assemble then Copy, and paste it at the start of a Claude / Cursor / ChatGPT session.

Use it in Claude Code (export)

1. Click Export for Claude Code on the Vault page — downloads sparkvibe-vault.zip.
2. Unzip it to a stable folder, e.g. ~/vault.
3. Copy skills/save, skills/pin, skills/load into ~/.claude/skills/.
4. In Claude Code: /load to brief a session, /save to log it, /pin <insight> to promote a fact.

The vault is plain markdown you own — Memcrate-compatible, so it also opens in Obsidian and syncs via git/iCloud/Dropbox.

Projects → Project explorer links a workspace project to a folder on your computer (e.g. D:\ACCA). The path is stored in the database for the whole team.

Cloud site vs desktop

• https://vibe.codes-ai.uk (browser) — can save and edit folder paths, but cannot browse your PC's files. You will see a banner explaining this.
• SparkVibe Desktop — runs a local server with LOCAL_FS=true and reads folders on your machine. Use Download and open Projects there to browse like Windows Explorer.

Link or edit a path

1. Select a project → Link folder or Edit folder path.
2. Paste the full path, or use Browse in the desktop app.
3. Save — the link works for Code explain, context packs, and agents when running locally.

Empty folder list on the cloud? Expected — install the desktop app or run npm run dev locally with LOCAL_FS=true to browse files.

Index private GitHub repositories for Code → requirements, repo monitor, and context packs. Admins add a personal access token under Settings → Integrations (workspace Git access). Use a fine-scoped token with repo read access only.

1. Open Settings → Integrations and paste your GitHub token
2. On a project → Links & settings → paste the private https://github.com/org/repo URL
3. Use Code → requirements or Repo monitor from the project sidebar

Project sidebar → Code → requirements. Link a Git repo or local folder, click Index repository, then generate PRD, user stories, business context, acceptance criteria, and gap analysis. Saves to project Documentation.

Requires a workspace AI provider (Settings → AI providers) or server keys (Groq, Gemini, OpenRouter).

Project sidebar → Database explorer. Add a PostgreSQL URL in Links & settings (prefer a read-only database user), then Scan database for tables, columns, primary keys, and foreign keys.

• Per-table AI explanations in plain language
• Mermaid ERD diagram
• Full doc pack: overview, relationships, business logic, user stories, design review, indexes, API ideas, sample SQL

Generated markdown is saved to project Documentation and downloaded as a zip.

Project sidebar → Text → knowledge pack. Paste meeting notes, specs, or research (40+ characters), then generate PLAN, ARCHITECTURE, TASKS, AGENTS, glossary, and open questions.

Run full pipeline optionally produces cleaned markdown, Mermaid diagrams, Marp HTML slides, Slidev deck, and Typst PDF in one zip.

From any board task drawer → Send to Claude → Context pack (.zip). The zip includes ticket markdown,CLAUDE.md, a Cursor .mdc rule, memory.md starter, repo activity (desktop), project file notes, and related prompts.

Drop the folder into your Claude Code or Cursor project and start fixing with full context.

Open a project → sidebar Prompt A/B lab. Create an experiment with two variants (library picks or pasted text), compare readiness scores, note token usage, and pick A, B, or tie as the winner.

Configure JazzCash, EasyPaisa, Raast, and bank transfer under Payments → PK setup.

1. Add merchant API keys for hosted checkout, or mobile/bank accounts for manual instructions
2. On a member profile, choose PKR and start a payment — JazzCash, EasyPaisa, Raast, or bank transfer
3. Register callbacks: /api/payments/jazzcash/callback and /api/payments/easypaisa/callback

Learn → Family dashboard (/learn/parent) shows linked learners' progress and current-month tuition status.

1. Admins link guardians at Teaching → Parents with email + WhatsApp phone (E.164)
2. Guardians sign in with the linked email and see read-only progress + payment instructions
3. WhatsApp tuition — send fee reminders per guardian or Remind all due (requires server WHATSAPP_* or TWILIO_* env)

Admins open Settings → Members → a member name for join date, projects, courses, tasks, technical timeline, and monthly payment ledger (Stripe, Pakistani providers, or manual).

Stripe

Set STRIPE_SECRET_KEY and webhook secret. Use Stripe tuition / Stripe payroll on member profiles (GBP).

Long lists use search + pagination instead of endless scrolling — members, prompts, projects, and guardian links. Sidebar compact mode and Claude project folders are stored in your workspace database, not browser localStorage.

Download v0.4.2 from the download page or portal:

• Installer (recommended): SparkVibe-Setup-0.4.2.exe — Start menu + desktop shortcut
• Portable: SparkVibe-Portable-0.4.2.exe — run from USB, no install

Steps

1. Download from /download or GitHub Releases v0.4.2
2. Run the EXE — if SmartScreen appears, choose More info → Run anyway (unsigned build)
3. First-run setup wizard: personal mode (local DB) or team member (workspace code + login)
4. Run database migrate if prompted (personal mode)
5. Sign in — pick workspace if you belong to more than one

Requirements

• Windows 10/11 (64-bit)
• PostgreSQL 14+ reachable (team shared DB or local for personal mode)
• ~250 MB disk

Press F1 inside the desktop app for built-in help. See docs/INSTALL_WINDOWS.md in the repo.

Download DMG or ZIP (arm64 / x64) from /download or GitHub Releases tag v0.4.2.

DMG (recommended)

1. Open SparkVibe-0.4.2.dmg
2. Drag SparkVibe to Applications
3. If Gatekeeper blocks: right-click app → Open → confirm
4. Configure database in setup wizard; default server URL can point to https://vibe.codes-ai.uk

Build from source (developers)

npm install
npm run desktop:build:mac

Requires macOS with Xcode CLI tools. CI: Build Mac workflow on release tags.

The Android app is a Capacitor shell that loads your hosted SparkVibe URL.

1. Get SparkVibe-0.4.2-android.apk from GitHub Releases or CI artifacts
2. On device: Settings → allow install from unknown sources (if needed)
3. Install APK
4. On first launch enter server: https://vibe.codes-ai.uk
5. Sign in — choose workspace if prompted

Build locally

npm run mobile:init
npm run mobile:apk

Requires JDK 17+. Play Store release is documented in docs/INSTALL_ANDROID.md.

Each workspace shares one PostgreSQL database so projects, prompts, learning, and boards stay in sync for that team.

Option A — Hosted team (easiest)

1. Use the web app at https://vibe.codes-ai.uk
2. Admin shares workspace join code (Settings) or invite link
3. Desktop/Android: team member setup with code + credentials
4. Same user can join multiple workspaces via separate invites

Option B — Self-hosted

1. Deploy SparkVibe to your VM (see repo deploy/ and docs/GITHUB_DEPLOY.md)
2. Set DATABASE_URL for all clients
3. TLS + firewall Postgres appropriately