DeltaChat Apps

Agent Zero plugin providing typed actions for webxdc apps in DeltaChat chats. A single dispatcher tool routes calls to per-app tool modules that encapsulate each app's wire format.

• Communicates with: deltachat plugin via HTTP API (localhost:8765)

Quick Start

# Install Python deps
/opt/venv-a0/bin/pip install requests

# Install Node.js deps (plugin-local)
npm install --prefix /a0/usr/plugins/deltachat_apps yjs

# Deploy plugin
./deploy.sh deploy

# Restart Agent Zero (required for Python tool changes)

DeltaChat daemon must be running: supervisorctl start deltachat-daemon

Key Directories

Directory	Purpose
tools/	Dispatcher tool (A0 Tool class) and PoC files
prompts/	Agent system prompt for the dispatcher tool
config/	App registry mapping app names to metadata
apps/	Per-app directories with tool logic, helpers, and manuals
apps/grocery-list/	Grocery List app integration (Yjs CRDT, auto-categorization)

Key Files

• tools/deltachat_apps.py - Dispatcher tool class DeltaChatApps, routes actions to app modules
• prompts/agent.system.tool.deltachat_apps.md - Tool prompt injected into agent system prompt
• config/registry.json - App registry: app_name to webxdc_name, actions, version
• hooks.py - Dependency installation (pip: requests, npm: yjs)
• deploy.sh - rsync deploy script to /a0/usr/plugins/deltachat_apps/
• plugin.yaml - Plugin manifest (name, title, version)
• apps/grocery-list/tool.py - Grocery List app logic (8 actions, plain Python module)
• apps/grocery-list/helper.mjs - Node.js Yjs CRDT helper for Grocery List
• apps/grocery-list/SKILL.md - AI manual for Grocery List actions and args
• apps/grocery-list/categories.json - 845 keywords for auto-categorization (11 categories)
• apps/grocery-list/manifest.json - Grocery List app metadata
• tools/grocery_board.py - PoC file (preserved, not deployed)
• tools/grocery_board_helper.mjs - PoC helper (preserved, not deployed)

Tech Stack

Python 3.12+ | Node.js 22 | Yjs CRDT | DeltaChat HTTP API | Agent Zero Plugin System

Architecture

Agent
  │
  ▼
deltachat_apps (Dispatcher Tool)
  │
  ├── installed_apps → reads config/registry.json
  ├── help → reads apps/<name>/SKILL.md
  └── call → verifies message_id via webxdc_info API
        │
        ▼
      apps/<app_name>/tool.py (dynamic importlib load)
        │
        ├── _get_updates() → GET /api/v1/webxdc/{id}/updates
        ├── _call_helper() → node apps/<name>/helper.mjs (stdin JSON)
        │     │
        │     └── Yjs CRDT: apply updates → modify state → encode V2 update
        │
        └── _send_update() → POST /api/v1/webxdc/{id}/send-update

Notes

• App tools are plain Python modules with execute(action, message_id, args) — never inherit from A0 Tool class
• The dispatcher loads app tools dynamically via importlib.util — no static imports
• Node.js helpers receive JSON via stdin and output JSON via stdout
• args is a JSON array string: ["action_name", "arg1", "arg2"]
• Python code changes require A0 process restart (sys.modules cache); WebUI changes only need browser reload
• PoC files (grocery_board.py, grocery_board_helper.mjs) are preserved but not deployed
• See AGENTS.md for detailed guidance for AI coding agents.