kirlts/witral: Infrastructure for your mind. A plugin-based system to route data from Messaging Apps directly to Local/Cloud Storage.

Witral

Witral is a self-hosted, modular ingestion framework designed to capture ephemeral data from messaging platforms and transform it into structured Markdown files.

It acts as a bridge between high-velocity communication streams (messaging services) and permanent storage systems (local file systems, Cloud Sync), creating a "fire-and-forget" pipeline for capturing information without context switching.

While agnostic in design, the default configuration serves as robust infrastructure for Personal Knowledge Management (PKM) workflows (Obsidian, Logseq) by turning chat groups into command-line interfaces for your notes.

Both the Baileys plugin (for WhatsApp integration) and the Google Drive storage plugin (for cloud sync) are included as optional modules.

Core Features

⚡ Fire-and-Forget Capture: Uses a low-friction double-comma syntax (,,tag) to route messages from chat directly to specific folders.
Platform Agnostic: Modular architecture separates Ingestion (Source) from Storage (Destination).
Included Source Plugin: WhatsApp (via Baileys).
Included Storage Plugins: Local File System, Google Drive.
Deterministic Output: Generates standard Markdown files.
Self-Hosted & Private: Runs entirely in a Docker container on your machine or server.

Prerequisites

Docker installed and running.
Linux
macOS
Windows

The installation script (start.sh) will automatically verify your Docker environment before proceeding.

Quick Start

Witral offers an interactive wizard for the initial setup.

Clone the repository:

git clone https://github.com/kirlts/witral
cd witral

Make the script executable:

chmod +x scripts/start.sh

Run the installer:

./scripts/start.sh

What happens next?

The script will launch the Interactive Wizard, guiding you through:

Installing and configuring a Messaging Service: (e.g., scanning the QR code to authenticate whatsapp in the case of Baileys).
Group Configuration: Selecting which chat groups Witral should monitor.
Tag Setup: Defining your routing tags (e.g., note, todo, project).
Cloud Sync: (Optional) Authenticating with a Cloud Sync service (Google Drive support included).

Once completed, the service will automatically start in the background.

Usage

Capture Syntax

Witral listens for the ,, trigger by default in monitored groups.

1. Basic Capture (New File)

Creates a timestamped file in the tag’s folder.

Input: ,,idea Rewrite the ingestor logic
Output: vault/tags/idea/27-10-2023 - 14-30.md containing the text (format: DD-MM-YYYY - HH-MM.md).

2. Dynamic Title Capture

Loading more...