Witral: A self-hosted ingestion framework (WhatsApp -> Markdown + Drive Sync). Native compatibility with Obsidian and other PKMs

Share & showcase
1

I built Witral to solve a specific bottleneck in my workflow.

I found out about Obsidian a couple months ago, and I understood its potential. But I also knew that, personally, I wouldn’t consistently take the time to feed a “Second Brain” if it required me to stop what I was doing, open a specific app for it, and then write. That friction is small, but it’s enough to kill the habit for me after a week.

However, I’ve been sending messages to myself on WhatsApp for years. Reminders, media to watch later, fleeting thoughts, because it’s the app I usually have open 24/7. I just needed a way to capture and structure that chaotic stream, so it would be ready for Obsidian or just to have it stored and organized somewhere else.

Instead of pressuring myself to build a disciplined writing habit (which would be more than reasonable), I built this system so I would barely have to change my daily routine.

What is Witral?

“Witral” comes from the Mapudungun word for “Loom”. It weaves the loose threads of your daily conversations into a structured fabric of knowledge.

Witral runs as a lightweight Docker container on your server or local machine (Linux/WSL2). It connects to WhatsApp (via Baileys) and listens for tagged messages in specific groups to convert them into Markdown. It’s completely self-hosted, and easy to setup and manage through the provided scripts.

Note on Safety: You add the Witral bot to a group. Since Baileys is a third-party library, I strongly recommend using a secondary number or burner account for the bot to avoid any risk of your main number being banned by Meta.

How it works:

1. I’m walking down the street with a friend and remember I have to order something later. In a monitored group, I send: ,buy USB-C adapter for the monitor. (The kind of thing I wouldn’t bother writing down anywhere else other than Whatsapp).

2. Or I send: ,,project_x,,bypass-idea Find a bypass for the Gemini API rate limits once core functionality is developed, if I need to organize a more thought-out idea for a specific project.

3. Witral detects the ,, separator at the beginning of each message.

  • For the buy tag (configured in “Append Mode”), it adds the line to a single buy.md list, stored in the Vault/tags folder.

  • For the Project_X tag (configured in “New File Mode”), it generates a new file named bypass-idea.md containing Find a bypass for the Gemini API rate limits once core functionality is developed, stored in the Vault/tags/project_x/ folder.

  • (Optional) A built-in plugin then syncs these changes to my Google Drive automatically.

You don’t need to SSH into your server to manage the bot: Sending ,,menu in the chat triggers an interactive reply system, allowing you to add new monitored groups, create tags, or check system status directly from WhatsApp.

This project started as a simple “WhatsApp-to-Markdown” script, but during development, I decided to turn it into a modular framework, for extensibility and because it’s cooler this way.

Today it bridges WhatsApp to Local/Drive, but the plugin architecture allows expanding to other inputs (Telegram, Discord Bots, etc) or outputs (S3, Github, N8N) easily.

There are no AI components in Witral. The system deterministically captures exactly what you type.

I have it running 24/7 in a free-tier Oracle instance.

Prerequisites:

You only need Docker installed in a linux/WSL2 system. The included start.sh script handles the setup. For reference, I developed it entirely using Cursor IDE in Windows 11, running WSL2.

I’m releasing it as completely open source. I’m not selling anything. The highest validation for me is simply seeing it being used by others who face the same friction I did.

Repo: https://github.com/kirlts/witral

Quick Start:

git clone [https://github.com/kirlts/witral.git](https://github.com/kirlts/witral.git)
cd witral
chmod +x scripts/start.sh
./scripts/start.sh

The start.sh script launches an interactive wizard allowing you to enable the Baileys plugin, linking your WhatsApp session (via QR) and setting up your initial groups/tags. It also allows you to setup Google Drive sync

Once Running:

You can manage the system either via the interactive menu (typing ,,menu in a monitored whatsapp group), or by accessing the full CLI menu:

docker exec -it witral node dist/index.js

If you give it a try and find it useful, please let me know in this post or through a DM.

1 Like