Lystbot README

Smart lists and reminders that your AI can actually use.

LystBot is not another AI list app. There's no built-in AI. No chatbot. No "AI-powered suggestions."
Instead, LystBot gives your AI - whether it's OpenClaw, Hermes, Claude Code, ChatGPT, Copilot, Grok Bot, or another agent - a direct line to your lists and reminders.
Your AI controls the lists and reminders. The app is the window to the real world.

🚀 Getting Started

1. Get the App

Open the app, create your first list, and grab your API key from Settings → AI Agents.

2. Connect Your AI Agent

Head over to the agent setup page for step-by-step instructions:

👉 lystbot.com/agents

Three ways to connect, depending on your setup:

3. That's it

npx lystbot login YOUR_API_KEY
lystbot add "Groceries" "Oat milk, Bananas, Coffee"

Your agent adds items. Your phone updates instantly. Done.

🧠 How It Works

Most "AI list apps" shove a chatbot inside the app. LystBot does the opposite: your AI lives where it already lives, and LystBot is the app it controls.

You → talk to your AI → AI calls LystBot API → your phone updates instantly

No new AI to learn. No prompts inside the app. Just connect your existing AI and it manages your groceries, packing lists, todos, reminders - anything.

• 🤖 "Add eggs to my shopping list" actually works - from any AI you already use
• 📱 Your phone is the display - your AI writes, you see it instantly
• 🔑 Clean separation - the app is for humans, the API is for agents
• 🔄 Real-time sync - your AI adds milk, your partner sees it immediately

✨ Features

🗒️ Smart Lists - Create, organize, and share lists with anyone

🤝 Real-time Sharing - Invite others via share codes, collaborate live

📱 Cross-Platform - iOS and Android, with CLI and API access

⭐ Favorites - Quick-access items you use all the time

🗂️ Categories - Structure lists into sections, move items between categories, keep uncategorized items in Other

📎 Attachments - Attach images and links to items, from the app, the CLI, or an MCP agent

⏰ Reminders - Let your AI create, update, disable, and delete one-time or recurring reminders

🔔 Push Notifications - Know when your AI or your family changes a list

🌐 Open API - Full REST API so any AI agent can read, write, and manage lists, categories, and reminders

🤖 Agent Integrations

LystBot works with any AI that can make HTTP requests. Here's how to connect yours:

Personal Agents & Autonomous Frameworks

Coding Agents & IDEs

Voice Assistants & Chat AI

Don't see your agent? If it can call an API, it can use LystBot. Check the API docs.

💻 CLI

The LystBot CLI lets you manage lists from the terminal. Built for AI agents like OpenClaw that work best with command-line tools, and for anyone who likes to script things.

Install & Login

npx lystbot login <YOUR_API_KEY>

Commands

# Lists
lystbot lists                              # Show all lists
lystbot show "Groceries"                   # Show a list with items
lystbot create "Packing List" --emoji "🧳" # Create a new list
lystbot delete "Old List" --force          # Delete a list

# Items
lystbot add "Groceries" "Milk, Eggs, Bread"  # Add items (comma-separated)
lystbot add "Groceries" "250g Mehl; 3x Milch; 3 Bananen" # Parse unit and count prefixes
lystbot add "Groceries" "Mehl" --quantity 2 --unit "500g" # Explicit fields
lystbot check "Groceries" "Milk"             # Check off an item
lystbot uncheck "Groceries" "Milk"           # Uncheck an item
lystbot remove "Groceries" "Milk"            # Remove an item

# Attachments
lystbot attach-image "Groceries" "Milk" ./photo.jpg     # Attach a local image
lystbot attach-url "Groceries" "Milk" "https://example.com" "Recipe"  # Attach a link
lystbot attachments "Groceries" "Milk"                  # Show attachments
lystbot detach <attachment-id>                          # Delete an attachment

# Categories
lystbot categories "Groceries"                 # List categories (incl. Other)
lystbot category add "Groceries" "Fruits"      # Create a category
lystbot add "Groceries" "Bananas" --category "Fruits"   # Add into a category
lystbot move "Groceries" "Bananas" --category other      # Move to Other/uncategorized

# Reminders
lystbot reminders                                      # Show all reminders
lystbot reminder <id>                                  # Show one reminder
lystbot remind "Take vitamins" --at "2026-05-08 09:00" --timezone "Europe/Berlin"
lystbot reminder-update <id> --title "Take supplements"
lystbot reminder-update <id> --at "2026-05-09 09:00" --enabled
lystbot reminder-update <id> --disabled
lystbot reminder-delete <id> --yes

# Sharing
lystbot share "Groceries"                  # Generate a share code
lystbot join ABC123                        # Join a shared list

# Agent identity
lystbot profile --name "TARS" --emoji "🤖" # Set your bot's display name

Full reference: CLI docs

🔌 MCP Server

LystBot ships with a built-in MCP server. Works with Claude Desktop, Claude Code, Cursor, Windsurf, Cline, and any MCP-compatible client.

First, authenticate (all setups need this):

npx lystbot login <YOUR_API_KEY>

Claude Desktop

Add this to your config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "lystbot": {
      "command": "npx",
      "args": ["lystbot", "mcp"]
    }
  }
}

Restart Claude Desktop. Done.

Claude Code

One command:

claude mcp add lystbot -- npx lystbot mcp

That's it. Claude Code can now manage your lists.

Cursor / Windsurf / Cline

Add the same config to your editor's MCP settings:

{
  "mcpServers": {
    "lystbot": {
      "command": "npx",
      "args": ["lystbot", "mcp"]
    }
  }
}

Available Tools

add_items understands 250g Mehl, 3x Milch, plain counts such as 3 Bananen / 3 bananas, and container forms such as 2 Flaschen Wein. Agents can instead send [{"text":"Mehl","quantity":2,"unit":"500g"}]; weight belongs in unit, not quantity 250.

🏗️ Architecture

┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│  Your Phone  │  │   Your AI    │  │  MCP Client  │  │     CLI      │
│  (LystBot    │  │  (OpenClaw,  │  │  (Claude,    │  │  (npx        │
│   App)       │  │   ChatGPT)   │  │   Cursor)    │  │   lystbot)   │
└──────┬───────┘  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘
       │                 │                 │                 │
       │ X-Device-UUID   │ Bearer Token    │ MCP Protocol    │ Bearer Token
       │                 │                 │                 │
       └────────┬────────┴────────┬────────┴────────┬────────┘
                │                 │                 │
         ┌──────▼─────────────────▼─────────────────▼──────┐
         │               LystBot API                       │
         │            (REST/JSON + MCP)                     │
         └─────────────────────────────────────────────────┘

📚 Documentation

• 📡 API Reference - Full endpoint docs with curl examples
• 💻 CLI Reference - All commands and flags
• 🔌 MCP Server - npx lystbot mcp (see setup above)

🤝 Contributing

We'd love your help! Whether it's:

• 🐛 Bug reports and feature requests via Issues
• 🔧 CLI improvements and new commands
• 📖 Documentation fixes

Fork it, branch it, PR it.

📄 License

MIT - see LICENSE for details.

Built with ❤️ by TourAround UG