Compare commits
8
Commits
global-shortcuts
...
main
| Author | SHA1 | Date | |
|---|---|---|---|
 zib
|
68fc8bb6e0 | ||
|
zib
|
e0c192e324 | ||
|
zib
|
d1b4fb2178 | ||
|
zib
|
b4cd86ef30 | ||
|
zib
|
394a2300b7 | ||
 agent
|
24447f5d93 | ||
|
agent
|
4a10eec56a | ||
|
agent
|
09b8624333 |
@@ -0,0 +1,85 @@
|
|||||||
|
# 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:
|
||||||
|
|
||||||
|
1. `discord.js` login + list guilds + send a message from a throwaway test account.
|
||||||
|
2. Minimal MCP Streamable HTTP server exposing `send_message` / `read_messages`, wired to #1.
|
||||||
|
3. 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
|
||||||
|
|
||||||
|
```sh
|
||||||
|
pnpm install
|
||||||
|
pnpm build # esbuild bundle into dist/
|
||||||
|
pnpm testTypes # tsc --noEmit
|
||||||
|
pnpm lint
|
||||||
|
```
|
||||||
@@ -1,60 +1,237 @@
|
|||||||
# Vesktop
|
<!--
|
||||||
|
Veskslop README
|
||||||
|
IMAGE SLOTS — drop the files in docs/images/ and they render automatically:
|
||||||
|
docs/images/veskslop-hero.png hero banner (~1600x500)
|
||||||
|
docs/images/veskslop-terminal.png terminal screenshot of the daemon
|
||||||
|
docs/images/veskslop-mcp.png AI control / MCP flow diagram
|
||||||
|
docs/images/veskslop-audio.png audio + video pipeline diagram
|
||||||
|
Rename or add slots as needed. Everything else here is text-only.
|
||||||
|
-->
|
||||||
|
|
||||||
Vesktop is a custom Discord desktop app
|
<div align="center">
|
||||||
|
|
||||||
**Main features**:
|
<img src="docs/images/veskslop-hero.png" alt="Veskslop — Discord for the machines" width="100%" />
|
||||||
- Vencord preinstalled
|
|
||||||
- Much more lightweight and faster than the official Discord app
|
|
||||||
- Linux Screenshare with sound & wayland
|
|
||||||
- Much better privacy, since Discord has no access to your system
|
|
||||||
|
|
||||||
**Not yet supported**:
|
# 💀 Veskslop
|
||||||
- Global Keybinds
|
|
||||||
- see the [Roadmap](https://github.com/Vencord/Vesktop/issues/324)
|
|
||||||
|
|
||||||
|
### The headless, agentic, MCP-pilled Discord client.
|
||||||
|
|
||||||
|
|
||||||
## Installing
|
**No window. No mouse. No human. Just tools, pipes, and a Discord account living its best digital life.**
|
||||||
|
|
||||||
Visit https://vesktop.dev/install
|
[](#)
|
||||||
|
[](#-why-though)
|
||||||
|
[](#-mcp-the-brain)
|
||||||
|
[](#-audio-pipes)
|
||||||
|
[](#-video-streams)
|
||||||
|
[](https://github.com/Vencord/Vesktop)
|
||||||
|
[](LICENSE)
|
||||||
|
|
||||||
## Building from Source
|
</div>
|
||||||
|
|
||||||
You need to have the following dependencies installed:
|
---
|
||||||
- [Git](https://git-scm.com/downloads)
|
|
||||||
- [Node.js](https://nodejs.org/en/download)
|
|
||||||
- pnpm: `npm install --global pnpm`
|
|
||||||
|
|
||||||
Packaging will create builds in the dist/ folder
|
> ⚠️ **Veskslop is NOT Vesktop.** They are separate projects with separate goals.
|
||||||
|
> [Vesktop](https://github.com/Vencord/Vesktop) makes Discord nicer for **humans**.
|
||||||
|
> Veskslop deletes the human entirely and installs a robot in their place.
|
||||||
|
|
||||||
```sh
|
## 🚀 What is Veskslop
|
||||||
git clone https://github.com/Vencord/Vesktop
|
|
||||||
cd Vesktop
|
|
||||||
|
|
||||||
# Install Dependencies
|
Veskslop takes the beloved Vesktop base and surgically removes the part where a person has to click things. What remains is a **headless Discord client**: a daemon that speaks Discord natively, exposes itself as a **proxy**, and lets an **AI agent drive a real Discord account** over **MCP** — while you pipe **audio in**, pipe **audio out**, and shove **live video streams** down its throat.
|
||||||
pnpm i
|
|
||||||
|
|
||||||
# Either run it without packaging
|
It is Discord, but as infrastructure. It is the account you already have, plus `curl`, minus dignity.
|
||||||
pnpm start
|
|
||||||
|
|
||||||
# Or package (will build packages for your OS)
|
Think of it as:
|
||||||
pnpm package
|
|
||||||
|
|
||||||
# Or only build the Linux Pacman package
|
- 🖥️ **A Discord client with the client removed.** Runs on a server, in a container, on a Raspberry Pi, in your weird home lab, wherever.
|
||||||
pnpm package --linux pacman
|
- 🔀 **A proxy.** Messages, events, voice state, attachments — everything is forwarded, interceptable, scriptable, and API-shaped.
|
||||||
|
- 🧠 **An agent body.** Your MCP-capable AI gets a real account with real permissions and real consequences.
|
||||||
|
- 🔊 **An audio router.** Play anything into voice. Capture anything out. TTS in, STT out, pipes for days.
|
||||||
|
- 📹 **A streaming endpoint.** Push files, cameras, generative visuals, or pure slop into a voice channel.
|
||||||
|
- 🧪 **A science experiment that will absolutely not get your account banned** *(allegedly)*.
|
||||||
|
|
||||||
# Or package to a directory only
|
> **Status: pre-alpha.** The repo currently carries the Vesktop base + global shortcut work. The headless core is being carved out. Everything below is the target architecture — some of it works, some of it is a promise, all of it is the vision.
|
||||||
pnpm package:dir
|
|
||||||
|
## 🗿 Why though
|
||||||
|
|
||||||
|
Because clicking is for mortals. Because you want a Discord presence that never sleeps, never typos, and never says "brb". Because "can an AI run a Discord account" is the kind of question that deserves a yes and a README.
|
||||||
|
|
||||||
|
Real reasons people actually want this:
|
||||||
|
|
||||||
|
- Automate community management, moderation, and notifications without a desktop app running.
|
||||||
|
- Bridge Discord into other systems: chatops, dashboards, MCP agents, home automation, whatever.
|
||||||
|
- Route voice audio both ways: feed a bot ears and a mouth.
|
||||||
|
- Stream synthetic video into a voice channel for demos, testing, or entertainment.
|
||||||
|
- Run entirely headless on a VPS with no GUI stack whatsoever.
|
||||||
|
|
||||||
|
## 🧠 MCP: the brain
|
||||||
|
|
||||||
|
Veskslop ships an **MCP server** so any MCP-capable agent (Claude, GPT-based agents, your local Llama abomination, a cron job with delusions of grandeur) can operate the account through structured tool calls.
|
||||||
|
|
||||||
|
**Planned tool surface** (names may change, vibes will not):
|
||||||
|
|
||||||
|
| Tool | Description |
|
||||||
|
| --- | --- |
|
||||||
|
| `discord_send_message` | Send a message to a channel, thread, or DM. |
|
||||||
|
| `discord_read_messages` | Read recent messages, with filters, pagination, and search. |
|
||||||
|
| `discord_list_guilds` | List guilds, channels, threads, and their IDs. |
|
||||||
|
| `discord_react` | Add or remove reactions. |
|
||||||
|
| `discord_edit_message` | Edit a message the account sent. |
|
||||||
|
| `discord_delete_message` | Delete a message the account sent. |
|
||||||
|
| `discord_upload_file` | Upload attachments with optional captions. |
|
||||||
|
| `discord_join_voice` | Join a voice channel and stay there like a loyal appliance. |
|
||||||
|
| `discord_leave_voice` | Leave the voice channel. Deeply emotional. |
|
||||||
|
| `discord_play_audio` | Pipe an audio source into the voice channel. |
|
||||||
|
| `discord_capture_audio` | Capture per-user audio out of the voice channel. |
|
||||||
|
| `discord_start_stream` | Start a video stream in the current voice channel. |
|
||||||
|
| `discord_stop_stream` | Stop the stream. |
|
||||||
|
| `discord_set_presence` | Status, activity, custom status. Look busy. |
|
||||||
|
| `discord_set_voice_state` | Mute, deafen, self-mute, self-deafen. |
|
||||||
|
| `discord_get_state` | Snapshot of the account, gateway, and pipelines. |
|
||||||
|
|
||||||
|
Every tool is designed to be **safe by default**: explicit opt-in for destructive actions, rate-limit awareness, and a sandbox mode that logs instead of sends.
|
||||||
|
|
||||||
|
## 🔀 Proxy mode
|
||||||
|
|
||||||
|
Veskslop is also a **proxy layer** in front of Discord:
|
||||||
|
|
||||||
|
- **REST passthrough** with authentication handled once.
|
||||||
|
- **Gateway event bus** — every event is consumable by local code, webhooks, or other processes.
|
||||||
|
- **Inbound injection** — anything that can hit the proxy can act as the account, with policy checks in between.
|
||||||
|
- **Message middleware** — transform, filter, log, reroute, or mirror traffic.
|
||||||
|
- **Multi-account ready** (eventually) — one daemon, several identities, maximum chaos.
|
||||||
|
|
||||||
|
```txt
|
||||||
|
your app / agent / script ──▶ Veskslop proxy ──▶ Discord
|
||||||
|
│
|
||||||
|
├─ policy / rate limit / audit log
|
||||||
|
└─ event bus ──▶ subscribers
|
||||||
```
|
```
|
||||||
|
|
||||||
## Building LibVesktop from Source
|
## 🔊 Audio pipes
|
||||||
|
|
||||||
This is a small C++ helper library Vesktop uses on Linux to emit D-Bus events. By default, prebuilt binaries for x64 and arm64 are used.
|
Voice is a first-class citizen, not an afterthought duct-taped on at 3am.
|
||||||
|
|
||||||
If you want to build it from source:
|
- **Audio in:** play PCM, Opus, or arbitrary encoded media into a voice channel. Wire up TTS, a soundboard, a radio stream, or an entire DAW.
|
||||||
1. Install build dependencies:
|
- **Audio out:** capture the mixed voice channel, individual speakers, or both. Feed it to STT, a recorder, or your stream.
|
||||||
- Debian/Ubuntu: `apt install build-essential python3 curl pkg-config libglib2.0-dev`
|
- **Virtual devices:** capture from a virtual sink and monitor, so routing stays clean on Linux (PipeWire / PulseAudio).
|
||||||
- Fedora: `dnf install @c-development @development-tools python3 curl pkgconf-pkg-config glib2-devel`
|
- **Format plumbing:** resampling, channel mapping, gain, and opus encoding handled by the pipeline.
|
||||||
2. Run `pnpm buildLibVesktop`
|
- **Backpressure aware:** buffers exist. They are bounded. We learned things.
|
||||||
3. From now on, building Vesktop will use your own build
|
|
||||||
|
```txt
|
||||||
|
mic / TTS / file ──▶ ffmpeg ──▶ opus ──▶ Veskslop ──▶ voice channel
|
||||||
|
│
|
||||||
|
voice channel ──▶ per-user decode ──▶ mix ──▶ PCM/file/STT ──▶ anywhere
|
||||||
|
```
|
||||||
|
|
||||||
|
<br />
|
||||||
|
<img src="docs/images/veskslop-audio.png" alt="Veskslop audio pipeline" width="80%" />
|
||||||
|
<br />
|
||||||
|
|
||||||
|
## 📹 Video streams
|
||||||
|
|
||||||
|
Send video where Discord expects a camera:
|
||||||
|
|
||||||
|
- Push **files**, **test patterns**, **generated frames**, or **live sources** (camera, RTSP, screen capture) into a voice channel.
|
||||||
|
- Target Discord's expected codec/container (H.264 / VP8 in the right envelope) without babysitting it by hand.
|
||||||
|
- Manage streams as pipelines: start, stop, swap sources on the fly.
|
||||||
|
- Perfect for demos, dashboards-as-TV, synthetic presenters, and things we should not describe further.
|
||||||
|
|
||||||
|
```sh
|
||||||
|
# planned CLI energy
|
||||||
|
veskslop stream start --guild 123 --channel 456 --source ./slop.mp4 --loop
|
||||||
|
```
|
||||||
|
|
||||||
|
## 🏗️ Architecture
|
||||||
|
|
||||||
|
```txt
|
||||||
|
┌─────────────────────────────────────────────────────────────────┐
|
||||||
|
│ MCP CLIENTS │
|
||||||
|
│ Claude · GPT agents · local models · scripts │
|
||||||
|
└───────────────────────────────┬─────────────────────────────────┘
|
||||||
|
│ MCP (stdio / HTTP)
|
||||||
|
┌───────────────────────────────▼─────────────────────────────────┐
|
||||||
|
│ VESKSLOP CORE │
|
||||||
|
│ tool server · session daemon · account state · rate guard │
|
||||||
|
│ policy engine · audit log · event bus · config │
|
||||||
|
└───────┬───────────────────┬────────────────────┬────────────────┘
|
||||||
|
│ │ │
|
||||||
|
┌───────▼───────┐ ┌───────▼────────┐ ┌───────▼──────────┐
|
||||||
|
│ Discord API │ │ Audio pipeline │ │ Video pipeline │
|
||||||
|
│ REST + WSS │ │ Opus / WebRTC │ │ encode / stream │
|
||||||
|
└───────────────┘ └────────────────┘ └──────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
## ⚡ Quickstart
|
||||||
|
|
||||||
|
> These commands describe the intended developer flow. The headless daemon is a work in progress; today the repo builds the Vesktop base.
|
||||||
|
|
||||||
|
```sh
|
||||||
|
git clone https://git.0xfeedc0de.com/zib/Veskslop.git
|
||||||
|
cd Veskslop
|
||||||
|
|
||||||
|
# dependencies
|
||||||
|
pnpm install
|
||||||
|
|
||||||
|
# build
|
||||||
|
pnpm build
|
||||||
|
|
||||||
|
# run the daemon (planned)
|
||||||
|
DISCORD_TOKEN="your-token-here" pnpm vesk slop
|
||||||
|
```
|
||||||
|
|
||||||
|
Connect an MCP client (Claude Desktop style):
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"veskslop": {
|
||||||
|
"command": "pnpm",
|
||||||
|
"args": ["vesk", "mcp"],
|
||||||
|
"env": {
|
||||||
|
"DISCORD_TOKEN": "your-token-here"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 🗺️ Roadmap
|
||||||
|
|
||||||
|
- [x] Fork Vesktop and keep the good parts
|
||||||
|
- [x] Global shortcuts / keybinds base
|
||||||
|
- [ ] Extract a true headless core (no Electron window)
|
||||||
|
- [ ] Gateway + REST session daemon
|
||||||
|
- [ ] MCP server with the tool surface above
|
||||||
|
- [ ] Outbound audio pipeline
|
||||||
|
- [ ] Inbound audio capture pipeline
|
||||||
|
- [ ] Video stream pipeline
|
||||||
|
- [ ] Proxy mode + event bus
|
||||||
|
- [ ] Policy engine, audit log, rate limiting
|
||||||
|
- [ ] Container image (`veskslop:slop-latest`)
|
||||||
|
- [ ] Documentation that is not a README
|
||||||
|
- [ ] Achieve AGI (stretch goal)
|
||||||
|
|
||||||
|
## 🧨 Disclaimer
|
||||||
|
|
||||||
|
Veskslop automates a **user account**, which is the kind of thing Discord's Terms of Service has opinions about. Run it on an account you can afford to lose, respect rate limits, do not use it to spam or harass, and generally do not be the reason we cannot have nice things. This project is unaffiliated with Discord Inc. and with the Vesktop project. You are the captain of this ship, and the ship is on fire by design.
|
||||||
|
|
||||||
|
## 🙏 Credits
|
||||||
|
|
||||||
|
Veskslop stands on the shoulders of legends:
|
||||||
|
|
||||||
|
- [Vesktop](https://github.com/Vencord/Vesktop) — the base, the vibe, the head start.
|
||||||
|
- [Vencord](https://github.com/Vencord/Vencord) — the plugin ecosystem that made Vesktop what it is.
|
||||||
|
- [Discord](https://discord.com) — the API we lovingly abuse.
|
||||||
|
- Every protocol implementation that let us shove Opus through a websocket at 3am.
|
||||||
|
|
||||||
|
## 📜 License
|
||||||
|
|
||||||
|
GPL-3.0-or-later. See [LICENSE](LICENSE). Fork responsibly, ship slop ethically.
|
||||||
|
|
||||||
|
<div align="center">
|
||||||
|
|
||||||
|
<br />
|
||||||
|
|
||||||
|
**Veskslop** — *because your Discord account deserves a mind of its own.*
|
||||||
|
|
||||||
|
</div>
|
||||||
|
|||||||
Binary file not shown.
|
After Width: | Height: | Size: 1.7 MiB |
Reference in New Issue
Block a user