Rewrite README for the Veskslop headless MCP client vision
This commit is contained in:
agent
@@ -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>
|
||||||
|
|||||||
Reference in New Issue
Block a user