AGENTS.md — Veskslop

What this is

Veskslop is a headless Discord client daemon built on the Vesktop codebase. It turns one or more Discord user accounts into a controllable service:

an MCP server (Streamable HTTP) lets AI agents drive a "puppet" account;
a second, read-only account can collect stats/data without acting;
audio is piped in and out over PipeWire;
video streams can be pushed into voice channels;
everything is local-first: clients reach it over LAN/Tailscale only.

Vesktop is a separate project with separate goals. This repo shares history with it but not direction. Do not carry Vesktop UI features here unless the daemon needs them.

Decisions (locked unless the user changes them)

Core: TypeScript on Node with pnpm. discord.js for gateway/REST, @discordjs/voice for voice.
Accounts: multiple user tokens. Expected setup is one read-only collector account plus one full-control puppet account; design for N identities behind one control surface.
MCP transport: Streamable HTTP only (no stdio/SSE unless asked).
Network: bind localhost by default. Remote access is always over LAN/Tailscale — never expose to the public internet. A client will later authenticate to the proxy for remote control.
Audio: PipeWire only.
GUI: optional minimal web debug UI if it is cheap to build; otherwise keep the existing Vesktop Electron build runnable for debugging. The daemon must never require Electron.
Pacing/safety: actions emulate a human using the Vesktop client through a queue:
- first action is snappy (~30–80 ms delay);
- subsequent bulk actions get randomized delays (~500–2800 ms);
- a risky fast mode is opt-in and minimizes delays;
- default capabilities are clamped to free-account limits (upload size, stream resolution, etc.);
- individual abilities can be toggled off.

How to proceed

Phase 0 — PoC, do this first. Find the smallest end-to-end thing that works, then stop and report back so the user can choose a direction. Candidate spikes, timeboxed:

discord.js login + list guilds + send a message from a throwaway test account.
Minimal MCP Streamable HTTP server exposing send_message / read_messages, wired to #1.
Join a voice channel and play a local file via @discordjs/voice (PipeWire output).

Prefer whichever is quickest to prove; do not build production architecture before the user picks.

After regrouping: headless daemon skeleton → multi-account session manager → pacing queue → MCP tool surface → audio pipelines → video pipeline → remote proxy/auth client → web debug UI.

Architecture sketch

MCP clients (agents) ──Streamable HTTP──▶ Veskslop core ──▶ Discord (user tokens)
remote web client ─────auth over LAN─────▶   │
                                             ├─ action queue (human-emulation pacing)
                                             ├─ capability policy + limits + audit log
                                             ├─ audio pipeline (PipeWire)
                                             └─ video pipeline

Guardrails for agents working here

Never commit tokens, credentials, or .env files. Use environment variables / a local secret store.
Do not hardcode Discord limits from memory — verify current free-tier numbers (upload size, stream resolution, rate limits) at implementation time, and keep them configurable.
All outbound actions go through the pacing queue; no direct sends.
Default to conservative limits and opt-in risky features.
Test against throwaway accounts and private test guilds only.
Run pnpm testTypes and pnpm lint before calling work done; pnpm build to compile.

Open questions

Which Phase 0 spike becomes the real foundation? (user decides after the spikes)
Voice E2EE (DAVE) support status in the current voice stack — research before committing.
Video pipeline feasibility: required codecs/containers and how to feed synthetic frames.
Scope and auth model of the future remote proxy client and web debug UI.
How much of the Vesktop Electron tree gets deleted once the daemon is self-sufficient.

Dev commands

pnpm install
pnpm build        # esbuild bundle into dist/
pnpm testTypes    # tsc --noEmit
pnpm lint

4.3 KiB Raw Blame History Unescape Escape