zib/Veskslop-t
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

README: reflect the live text layer, real tools, and true roadmap

Browse Source
This commit is contained in:
Fisto
2026-09-11 16:13:02 +02:00
parent af6e553df3
commit 6fd77ca88d
1 changed files with 81 additions and 71 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+80 -70
View File
@@ -36,20 +36,20 @@
## 🚀 What is Veskslop ## 🚀 What is Veskslop
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. Veskslop takes the beloved Vesktop base and deletes the part where a person has to click things. What remains is a **headless Discord client** driven through a **validated capability layer**, so an **AI agent can run a real Discord account over MCP**. Text automation works today. Audio pipes and video streams are the next descent into madness.
It is Discord, but as infrastructure. It is the account you already have, plus `curl`, minus dignity. It is Discord, but as infrastructure. It is the account you already have, plus `curl`, minus dignity.
Think of it as: Think of it as:
- 🖥️ **A Discord client with the client removed.** Runs on a server, in a container, on a Raspberry Pi, in your weird home lab, wherever. - 🖥️ **A Discord client with the client removed.** Runs on a server, in a container, on a Raspberry Pi, in your weird home lab, wherever.
- 🔀 **A proxy.** Messages, events, voice state, attachments — everything is forwarded, interceptable, scriptable, and API-shaped. - 🧠 **An agent body (text tools live).** Your MCP-capable AI gets a real account with real permissions and real consequences.
- 🧠 **An agent body.** Your MCP-capable AI gets a real account with real permissions and real consequences. - 🔀 **A proxy (planned).** Messages, events, voice state, attachments — everything forwarded, interceptable, scriptable, and API-shaped.
- 🔊 **An audio router.** Play anything into voice. Capture anything out. TTS in, STT out, pipes for days. - 🔊 **An audio router (planned).** 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 streaming endpoint (planned).** Push files, cameras, generative visuals, or pure slop into a voice channel.
- 🧪 **A science experiment that will absolutely not get your account banned** *(allegedly)*. - 🧪 **A science experiment that will absolutely not get your account banned** *(allegedly)*.
> **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. > **Status: text layer works.** The real Vesktop client runs headless and is driven through a validated capability layer. Triggers, trust tiers, conversation context, response policy, polls, persistent logging, and MCP tools are live. Voice actions, audio, and video are still the vision. The design docs live in [docs/INDEX.md](docs/INDEX.md).
## 🗿 Why though ## 🗿 Why though
@@ -67,32 +67,29 @@ Real reasons people actually want this:
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. 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): **Live tool surface** (names may change, vibes will not):
| Tool | Description | | Tool | Description |
| --- | --- | | --- | --- |
| `discord_send_message` | Send a message to a channel, thread, or DM. | | `get_state` | User, guilds, and channels. Cache-only, zero queries. |
| `discord_read_messages` | Read recent messages, with filters, pagination, and search. | | `get_voice_state` | Which voice channel a user is in and who else is suffering there. |
| `discord_list_guilds` | List guilds, channels, threads, and their IDs. | | `send_message` | Send a message as the account. Query-paced. |
| `discord_react` | Add or remove reactions. | | `read_messages` | Read the client's message cache. |
| `discord_edit_message` | Edit a message the account sent. | | `send_dm` | Slide into someone's DMs. |
| `discord_delete_message` | Delete a message the account sent. | | `get_context` | Recent conversation context for a channel. Fetches new messages only. |
| `discord_upload_file` | Upload attachments with optional captions. | | `get_message_log` | Trigger log: trusted entries and a reserved untrusted buffer. |
| `discord_join_voice` | Join a voice channel and stay there like a loyal appliance. | | `get_action_log` | Durable audit trail: triggers, commands, replies, errors. |
| `discord_leave_voice` | Leave the voice channel. Deeply emotional. | | `get_puppet_config` / `set_puppet_config` | Response policy, context limits, poll duration. |
| `discord_play_audio` | Pipe an audio source into the voice channel. | | `whitelist_list` / `whitelist_add` / `whitelist_remove` | Trust tiers: user, trusted, admin. |
| `discord_capture_audio` | Capture per-user audio out of the voice channel. | | `run_commands` | Run several read-only tools in one call. |
| `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. **Planned**: voice join/leave, audio play/capture, video streams, message edit/delete/upload, presence and voice state control.
## 🔀 Proxy mode Every action is **safe by default**: strict input validation in the client, structured errors, a hard outbound rate limit, and paced sends. A buggy agent cannot crash the client or spam Discord.
Veskslop is also a **proxy layer** in front of Discord: ## 🔀 Proxy mode (planned)
Veskslop is also meant to be a **proxy layer** in front of Discord:
- **REST passthrough** with authentication handled once. - **REST passthrough** with authentication handled once.
- **Gateway event bus** — every event is consumable by local code, webhooks, or other processes. - **Gateway event bus** — every event is consumable by local code, webhooks, or other processes.
@@ -107,7 +104,7 @@ your app / agent / script ──▶ Veskslop proxy ──▶ Discord
└─ event bus ──▶ subscribers └─ event bus ──▶ subscribers
``` ```
## 🔊 Audio pipes ## 🔊 Audio pipes (planned)
Voice is a first-class citizen, not an afterthought duct-taped on at 3am. Voice is a first-class citizen, not an afterthought duct-taped on at 3am.
@@ -127,7 +124,7 @@ voice channel ──▶ per-user decode ──▶ mix ──▶ PCM/file/STT ─
<img src="docs/images/veskslop-audio.png" alt="Veskslop audio pipeline" width="80%" /> <img src="docs/images/veskslop-audio.png" alt="Veskslop audio pipeline" width="80%" />
<br /> <br />
## 📹 Video streams ## 📹 Video streams (planned)
Send video where Discord expects a camera: Send video where Discord expects a camera:
@@ -144,71 +141,82 @@ veskslop stream start --guild 123 --channel 456 --source ./slop.mp4 --loop
## 🏗️ Architecture ## 🏗️ Architecture
```txt ```txt
┌─────────────────────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────────┐
│ MCP CLIENTS │ │ MCP CLIENTS │
│ Claude · GPT agents · local models · scripts │ │ Claude · agents · scripts · cron │
└───────────────────────────────┬─────────────────────────────────┘ └──────────────────────────┬──────────────────────────┘
│ MCP (stdio / HTTP) │ Streamable HTTP (localhost)
┌───────────────────────────────▼─────────────────────────────────┐ ┌──────────────────────────▼──────────────────────────┐
│ VESKSLOP CORE │ │ VESKSLOP DAEMON │
│ tool server · session daemon · account state · rate guard │ │ triggers · trust · context · response policy │
│ policy engine · audit log · event bus · config │ │ action log · pacing · MCP tool server │
└───────┬───────────────────┬────────────────────┬────────────────┘ └──────────────────────────┬──────────────────────────┘
│ │ │ │ JSON lines over a Unix socket
┌───────▼───────┐ ┌───────▼────────┐ ┌───────▼──────────┐ ┌──────────────────────────▼──────────────────────────┐
│ Discord API │ │ Audio pipeline │ │ Video pipeline │ │ VESKTOP CORE (validated actions) │
│ REST + WSS │ │ Opus / WebRTC │ │ encode / stream │ │ state · messages · reactions · voice state │
└───────────────┘ └────────────────┘ └──────────────────┘ └──────────────────────────┬──────────────────────────┘
│ official client traffic
┌──────────────────────────▼──────────────────────────┐
│ DISCORD │
└─────────────────────────────────────────────────────┘
``` ```
The core exposes a fixed action list with strict validation. All logic lives in the daemon. This
keeps client patches small and upstream rebases easy. See [docs/core-bridge.md](docs/core-bridge.md).
## ⚡ Quickstart ## ⚡ Quickstart
> These commands describe the intended developer flow. The headless daemon is a work in progress; today the repo builds the Vesktop base.
```sh ```sh
git clone https://git.0xfeedc0de.com/zib/Veskslop.git git clone https://git.0xfeedc0de.com/zib/Veskslop-t.git
cd Veskslop cd Veskslop-t
# dependencies # dependencies and build
pnpm install pnpm install
# build
pnpm build pnpm build
# run the daemon (planned) # log in once with a terminal QR code
DISCORD_TOKEN="your-token-here" pnpm vesk slop cd poc && pnpm poc:qr
# run the client headless (use Xvfb on a server), then the daemon
pnpm control:bridge
``` ```
Connect an MCP client (Claude Desktop style): The daemon speaks **Streamable HTTP MCP** on `http://127.0.0.1:8788/mcp`. Point any MCP client at
that address, or poke it by hand:
```json ```sh
{ curl -s http://127.0.0.1:8788/mcp \
"mcpServers": { -H 'Content-Type: application/json' \
"veskslop": { -H 'Accept: application/json, text/event-stream' \
"command": "pnpm", -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
"args": ["vesk", "mcp"],
"env": {
"DISCORD_TOKEN": "your-token-here"
}
}
}
}
``` ```
The full setup, including the headless client and the mock core, is in
[docs/testing.md](docs/testing.md) and [poc/README.md](poc/README.md).
## 🗺️ Roadmap ## 🗺️ Roadmap
- [x] Fork Vesktop and keep the good parts - [x] Fork Vesktop and keep the good parts
- [x] Global shortcuts / keybinds base - [x] Validated core bridge (fixed actions, strict validation, structured errors)
- [ ] Extract a true headless core (no Electron window) - [x] Headless client driven through the core bridge
- [ ] Gateway + REST session daemon - [x] Gateway state, message send/read/fetch, reactions, voice state read
- [ ] MCP server with the tool surface above - [x] Trigger log, trust tiers, conversation context, continuation window
- [x] Response policy, hard rate limits, persistent action log
- [x] MCP server with the live text tool surface
- [x] Reaction polls and chat command help
- [ ] Notification parsing: edits, deletes, replies, references
- [ ] Reply-to-puppet as a trigger
- [ ] Per-user rate limits and command cooldowns
- [ ] Setup command with reaction-based multiple choice
- [ ] MCP event delivery (poll, stateful session, or local event stream)
- [ ] Collector account for voice membership fallback
- [ ] Voice join/leave and invite-link joins
- [ ] Outbound audio pipeline - [ ] Outbound audio pipeline
- [ ] Inbound audio capture pipeline - [ ] Inbound audio capture pipeline
- [ ] Video stream pipeline - [ ] Video stream pipeline
- [ ] Proxy mode + event bus - [ ] Proxy mode + event bus
- [ ] Policy engine, audit log, rate limiting
- [ ] Container image (`veskslop:slop-latest`) - [ ] Container image (`veskslop:slop-latest`)
- [ ] Documentation that is not a README
- [ ] Achieve AGI (stretch goal) - [ ] Achieve AGI (stretch goal)
## 🧨 Disclaimer ## 🧨 Disclaimer
@@ -235,6 +243,8 @@ layer. All logic lives in an external daemon.
Start here: Start here:
- [CURRENT.md](CURRENT.md) — live session state and how to resume
- [TODO.md](TODO.md) — the ordered backlog
- [docs/INDEX.md](docs/INDEX.md) — all design documents - [docs/INDEX.md](docs/INDEX.md) — all design documents
- [AGENTS.md](AGENTS.md) — rules for agents and contributors - [AGENTS.md](AGENTS.md) — rules for agents and contributors
- [poc/README.md](poc/README.md) — daemon run commands - [poc/README.md](poc/README.md) — daemon run commands