Zero Ichi

A WhatsApp bot built with Neonize

---

Table of Contents

• Requirements
• Installation
• Running the Bot
• Configuration
• Commands
• Features
• Agentic AI
• Adding Custom Commands
• Dashboard
• Development

---

Requirements

• Python 3.11+
• uv
• Node.js 20+ (for dashboard)

---

Installation

pip install uv

git clone https://github.com/MhankBarBar/zero-ichi
cd zero-ichi
uv sync

back to top

---

Running the Bot

uv run main.py

First-time setup:

1. A QR code will appear in the terminal
2. Open WhatsApp on your phone
3. Go to Settings > Linked Devices > Link a Device
4. Scan the QR code

back to top

---

Configuration

The bot uses config.json with JSON Schema validation for autocomplete and validation.

Quick Setup

{
  "$schema": "./config.schema.json",
  "bot": {
    "name": "my_bot",
    "prefix": "/",
    "login_method": "qr"
  }
}

Key Options

Option	Default	Description
bot.name	zero_ichi_bot	Session identifier (database filename)
bot.prefix	/	Command prefix (supports regex)
bot.login_method	qr	Login method: qr or `pair_code
bot.owner_jid	—	Bot owner's JID

Environment Variables

Store sensitive config in .env:

AI_API_KEY=your_api_key_here

Copy .env.example to .env and fill in your values.

Set yourself as owner: /config owner me

back to top

---

Commands

General

Command	Description
/help	Show all commands
/ping	Check bot latency
/menu	Show command menu

Admin (Group Only)

Command	Description
/kick @user	Kick a user
/add <number>	Add user to group
/mute @user	Mute a user
/unmute @user	Unmute a user
/promote @user	Promote to admin
/demote @user	Demote from admin
/admins	List group admins

Group Management

Command	Description
/invite	Get group invite link
/revoke	Revoke invite link
/groupinfo	Show group information
/setname <name>	Change group name
/setdesc <desc>	Change group description
/tagall [msg]	Mention all members

Content

Command	Description
/save <name> <text>	Save a note
/notes	List saved notes
/clear <name>	Delete a note
/filter <trigger> <response>	Create auto-reply
/filters	List all filters
/stop <trigger>	Remove a filter
/sticker	Convert image to sticker

Moderation

Command	Description
/warn @user [reason]	Warn a user
/warns @user	Check user warnings
/resetwarns @user	Clear warnings
/blacklist <word>	Add word to blacklist
/antilink	Configure anti-link

Owner Only

Command	Description
/config	Manage bot configuration
/config ai	Configure agentic AI
/antidelete	Toggle/configure anti-delete
/eval <code>	Execute Python code
/aeval <code>	Execute async Python code
/addcommand	Add command via code
/delcommand <name>	Delete dynamic command
/listdynamic	List dynamic commands

back to top

---

Features

Anti-Delete

Reveals deleted messages by re-sending them.

/antidelete on
/antidelete forward me

Notes System

Save and retrieve text/media notes using #notename:

/save greeting Hello, welcome!
#greeting  ->  "Hello, welcome!"

Filters

Auto-reply when specific words are detected:

/filter hello Hi there!

Blacklist

Auto-delete messages containing blacklisted words:

/blacklist badword

Anti-Link

Detect and handle links in group chats:

/antilink on
/antilink action delete
/antilink whitelist add youtube.com

Warnings

Warn users with configurable limits and actions:

/warn @user Spamming
/warnconfig limit 5
/warnconfig action kick

back to top

---

Agentic AI

The bot includes an AI assistant powered by OpenAI (or other providers). The AI can process messages and execute bot commands on your behalf.

Configuration

Set your API key in .env:

AI_API_KEY=sk-your-openai-key

Configure via WhatsApp:

/config ai              # Show AI status
/config ai on           # Enable AI
/config ai off          # Disable AI
/config ai mode reply   # Trigger modes: always, mention, reply

Mode	Description
always	AI responds to every message
mention	AI responds when mentioned
reply	AI responds when replying to bot

back to top

---

Adding Custom Commands

Method 1: Create a File

Create commands/<category>/<name>.py:

from core.command import Command, CommandContext

class HelloCommand(Command):
    name = "hello"
    description = "Say hello"
    usage = "/hello"
    
    async def execute(self, ctx: CommandContext) -> None:
        await ctx.client.reply(ctx.message, "Hello!")

Method 2: Dynamic Command (Owner Only)

Send via WhatsApp:

/addcommand
from core.command import Command, CommandContext

class GreetCommand(Command):
    name = "greet"
    description = "Greet someone"
    usage = "/greet"
    
    async def execute(self, ctx):
        await ctx.client.reply(ctx.message, "Greetings!")

back to top

---

Dashboard

Web dashboard for administration. See the dashboard README for details.

# Terminal 1: Start the bot
uv run main.py

# Terminal 2: Start the dashboard
cd dashboard && bun dev

Open http://localhost:3000

back to top

---

Development

Commands

uv run ruff format .    # Format code
uv run ruff check .     # Lint check

Project Structure

zero-ichi/
├── main.py             # Main entry point
├── dashboard_api.py    # FastAPI backend
├── config.json         # Bot configuration
├── commands/           # Command modules
├── core/               # Core modules
├── dashboard/          # Next.js admin dashboard
├── data/               # Per-group data storage
└── logs/               # Log files

back to top