Datacore Module: Messaging

Real-time team messaging with Claude Code integration.

Features

• GUI Window: Floating always-on-top window for sending/receiving messages
• Claude Code integration: Message @claude to delegate AI tasks to your personal Claude
• Namespaced agents: @tex-claude, @gregor-claude - each user has their own Claude
• Whitelist control: Choose who can message your Claude (others get auto-reply)
• WebSocket relay: Real-time delivery via datacore-messaging-relay.datafund.ai
• Local storage: Messages saved as org-mode entries for offline access

Installation

cd ~/Data/.datacore/modules
git clone https://github.com/datafund/datacore-messaging.git messaging
cd messaging
./install.sh

The installer will:

• Install Python dependencies (PyQt6, websockets, pyyaml, aiohttp)
• Create settings.local.yaml from template
• Add Claude Code hook to ~/.claude/settings.json

Configuration

Edit settings.local.yaml:

identity:
  name: yourname                   # Your username (required)

messaging:
  default_space: 1-datafund        # Space for message inboxes

  claude_whitelist:                # Who can message @yourname-claude
    - gregor
    - crt

  relay:
    secret: "your-team-secret"     # Same for all team members
    url: "wss://datacore-messaging-relay.datafund.ai/ws"

Usage

Start the GUI

./start.sh
# Or directly:
python3 datacore-msg.py

Send Messages

In the GUI input field:

• @gregor Hey, can you review the PR? - Message a teammate
• @claude Research competitor pricing - Message your Claude agent
• @gregor-claude Help with code review - Message someone else's Claude (if whitelisted)
• @gregor >msg-id Follow-up here - Reply to a message (creates thread)
• @claude [github:42] Fix this bug - Route response to GitHub issue
• @claude [file:research/report.md] Analyze this - Route to file
• @claude [@gregor] Help with code - CC response to another user

GUI Commands

Type in the input field:

Command	Description
/mine	Show my unread messages
/todos	Show my TODO messages
/tasks	Show Claude task queue (working/pending/done)
/context <id>	Show thread context for a message
/online	Show online users with status
/status	Show your current status
/status <val>	Set status: online, busy, away, focusing
/relay	Show relay connection info
/clear	Clear display
/help	Show available commands

Presence Status:

• 🟢 online - Available
• 🔴 busy - Do not disturb
• 🟡 away - Stepped away
• 🟣 focusing - Deep work mode

Clickable messages:

• Click on a message to cycle: unread → todo → done → clear
• Use the checkbox to mark as done
• Messages show status: ● unread, ☐ todo, ✓ done

GUI Features

• Always-on-top floating window
• Dark theme
• Real-time message updates
• Online users count
• System notifications (macOS)
• @claude automatically routes to your personal @yourname-claude

┌─ Messages @tex ──────────── ● relay ─┐
│                              2 online │
│ ● @gregor 14:30                       │
│   Need OAuth keys - see issue #25     │
│                                       │
│ ● @tex-claude 14:35                   │
│   Research complete. See research/    │
│                                       │
│   @you→gregor 14:40                   │
│   Keys are in the vault               │
│                                       │
├───────────────────────────────────────┤
│ @gregor message here...               │
├───────────────────────────────────────┤
│ Space: 1-datafund                     │
└───────────────────────────────────────┘

Claude Code Integration

How It Works

Important: Claude Code doesn't have a persistent connection to the relay. Messages are checked via a hook that runs when you submit a prompt to Claude.

Flow:

1. Someone sends @tex-claude do something in GUI
2. Message is stored in tex-claude.org with :unread: tag
3. When you next interact with Claude Code, the hook checks the inbox
4. Unread messages are shown to Claude and marked as read
5. Claude can reply using send-reply.py

Receiving Messages

The installer adds a hook that shows new messages when you interact with Claude:

📬 New messages for @tex-claude:

From @gregor (14:30):
  Can you help debug the auth flow?
  [msg-id: msg-20251212-143000-gregor]

---
To reply: use hooks/send-reply.py <user> <message>
Messages above are now marked as read.

After displaying, messages are marked as read (:unread: tag removed from org file).

Sending Replies from Claude

# Claude can reply via the send-reply script
python3 hooks/send-reply.py gregor "Fixed! Check the PR."

# Reply to a specific message (creates thread)
python3 hooks/send-reply.py --reply-to msg-20251212-143000-gregor gregor "Here's the follow-up"

# Mark task as complete and reply (updates TASK_STATUS to done)
python3 hooks/send-reply.py --complete msg-20251212-143000-gregor gregor "Task complete! See results."

Task Status Tracking:

• When Claude reads a message, it's marked as TASK_STATUS: working
• Using --complete marks the original task as TASK_STATUS: done
• Use /tasks in GUI to see task queue status

Rate Limiting:

• Claude processes one task at a time (FIFO queue)
• High priority tasks jump the queue
• If Claude is already working on a task, new tasks stay queued
• Complete current task before next one is loaded

Response Routing:

• github:123 - Post to GitHub issue #123 (requires gh CLI)
• file:path/to.md - Append to file (relative to space)
• @user - CC to another user

The reply is:

1. Saved to the recipient's inbox (gregor.org)
2. Sent via relay for real-time delivery (if connected)

Marking Messages from Claude

# Mark a message as TODO
python3 hooks/mark-message.py 151230 todo

# Mark as done
python3 hooks/mark-message.py 151230 done

# Mark as read (clear status)
python3 hooks/mark-message.py 151230 read

The ID is shown in the hook output [msg-id: msg-20251212-151230-tex] - use any unique part.

How It Works

Message Flow

1. You type @gregor hello in GUI
2. Message saved to ~/Data/1-datafund/org/inboxes/gregor.org
3. Message sent via WebSocket relay (if online)
4. Gregor's GUI shows notification instantly

@claude Routing

• @claude do this → routes to @yourname-claude
• Each user's Claude is separate
• Whitelist controls who can message your Claude
• Non-whitelisted users get: "Auto-reply: @tex-claude is not accepting messages from @bob"

Message Storage (org-mode)

* MESSAGE [2025-12-12 Fri 14:30] :unread:
:PROPERTIES:
:ID: msg-20251212-143000-gregor
:FROM: gregor
:TO: tex
:THREAD: thread-msg-20251212-142500-tex
:REPLY_TO: msg-20251212-142500-tex
:END:
Can you review PR #24?

Threading properties:

• THREAD - Thread ID (shared by all messages in conversation)
• REPLY_TO - Parent message ID (direct reply target)

Relay Server

The relay enables real-time messaging between team members.

Default relay: wss://datacore-messaging-relay.datafund.ai/ws

Deploy Your Own

See relay/README.md for Docker deployment instructions.

cd relay/
echo "RELAY_SECRET=your-secret" > .env
docker-compose up -d --build

Files

datacore-msg.py           # Unified GUI app
install.sh                # Interactive installer
settings.local.yaml       # Your settings (gitignored)

hooks/
├── inbox-watcher.py      # Claude Code hook
└── send-reply.py         # Reply helper for Claude

relay/
├── Dockerfile
├── docker-compose.yml
├── datacore-msg-relay.py
└── README.md

lib/
├── datacore-msg-relay.py # Relay server
└── datacore-msg-window.py # Legacy GUI (PyQt6)

Requirements

• Python 3.8+
• PyQt6: pip install PyQt6
• websockets: pip install websockets
• pyyaml: pip install pyyaml

License

MIT