A Linux CLI tool for managing persistent event queues backed by SQLite, with consumer subscriptions and async dispatch via notifier.
- Initialize a directory as a thread with
thread init <path>— the path is the thread ID. - Push events with
thread push— stored in SQLite and appended toevents.jsonl. - Register consumers with
thread subscribe— each consumer has a handler command and an optional SQL filter. - On each push,
notifierschedules athread dispatch— which spawns handler commands for consumers with pending events (file-locked, so no duplicate runs). - Consumers call
thread popto fetch their events (NDJSON), passing back the last processed event ID for at-least-once delivery.
npm install -g @theclawlab/threadnpm run build && npm link# Initialize a thread
thread init /tmp/my-thread
# Register a consumer
thread subscribe \
--thread /tmp/my-thread \
--consumer worker-1 \
--handler "my-handler --thread /tmp/my-thread --consumer worker-1" \
--filter "type = 'message'"
# Push an event
thread push \
--thread /tmp/my-thread \
--source agent-007 \
--type message \
--content "hello"
# Check status
thread info --thread /tmp/my-thread
# Consumer pops events (typically called from within handler)
thread pop --thread /tmp/my-thread --consumer worker-1 --last-event-id 0| Command | Description |
|---|---|
thread init <path> |
Initialize a new thread directory |
thread push |
Push one event (or batch via stdin) |
thread pop |
Fetch pending events for a consumer (NDJSON) |
thread subscribe |
Register a consumer with a handler command |
thread unsubscribe |
Remove a consumer subscription |
thread info |
Show thread summary and consumer progress |
thread dispatch |
(Internal) Spawn handlers for consumers with pending events |
<thread-dir>/
├── events.db # SQLite (WAL mode)
├── events.jsonl # append-only event log for debugging
├── run/ # consumer lock files
└── logs/ # thread logs (auto-rotated at 10k lines)
- USAGE.md — full CLI reference, event structure, and examples