Skip to main content
Once your assistant is set up, you can start having conversations from any registered messaging channel.

​
Understanding Trigger Words

NanoClaw uses a trigger word (default: @Andy) to know when you’re talking to it. Messages must start with the trigger word. 
@Andy what's the weather?
@andy help me write an email
@ANDY search for AI news
The trigger word is case-insensitive but must be at the start of your message.

​
Customizing the Trigger Word

You can change the trigger word anytime: 
@Andy change the trigger word to @Bob
Or set the ASSISTANT_NAME environment variable:
.env
ASSISTANT_NAME=Bot
Then restart the service.

​
Registering Groups

​
Main Channel (Self-Chat)

Your main channel is your private self-chat on your messaging platform. The /setup command automatically registers this as your main control channel. The main channel has special privileges:
  • Can write to global memory (shared across all groups)
  • Can manage all groups and scheduled tasks
  • Can configure directory mounts for any group
  • Has access to all tools (same as other groups)
In the main channel, you don’t need the trigger word for most commands - the assistant processes all messages by default.

​
Adding New Groups

From your main channel, you can register additional chats:
1

Get the group/chat name

Find the exact name of the WhatsApp group, Telegram chat, Discord channel, or Slack channel you want to add.
2

Register from main channel

In your main channel (self-chat), send:
@Andy add group "Family Chat"
Replace "Family Chat" with your group’s exact name.
3

Confirm registration

The assistant will:
  1. Find the group by name
  2. Create a folder at groups/{channel}_{group-name}/
  3. Create a CLAUDE.md memory file for that group
  4. Confirm registration

​
Managing Groups

From the main channel: 
@Andy list groups
@Andy remove group "Work Team"
@Andy join the "Dev Team" group
Only register groups you trust. Agents have access to mounted directories and can run bash commands (safely sandboxed in containers).

​
Basic Commands

​
In Any Group

@Andy what's the weather in San Francisco?
@Andy search for the latest AI developments
@Andy summarize this article: https://example.com/article

​
Main Channel Only

@Andy add group "Family Chat"
@Andy remove group "Old Group"
@Andy list groups

​
Real Examples

​
Example 1: Scheduled Reporting

@Andy every weekday morning at 9am, check my Obsidian vault for today's tasks and send me a prioritized list
The assistant will:
  1. Create a scheduled task with cron expression 0 9 * * 1-5
  2. Every weekday at 9am, run as a full agent with access to your mounted Obsidian folder
  3. Read tasks, prioritize them, and send you a message

​
Example 2: Git History Review

@Andy every Friday at 5pm, review the git history for the past week and update the README if there's drift
The assistant will:
  1. Schedule a weekly task
  2. Run git log for the past week
  3. Compare with README.md
  4. If there’s drift, update the README and commit the changes

​
Example 3: Dynamic Reminders

@Andy my friend's birthday is Monday
The proactive agent (if enabled) will:
  1. Detect the time-sensitive mention
  2. Automatically create a reminder
  3. Send you a reminder on Monday morning
No manual setup needed!

​
Example 4: Web Research

@Andy every Monday at 8am, compile news on AI developments from Hacker News and TechCrunch and message me a briefing
The assistant will:
  1. Search Hacker News and TechCrunch
  2. Filter for AI-related articles from the past week
  3. Summarize the most important developments
  4. Send you a formatted briefing

​
Conversation Catch-Up

NanoClaw’s conversation catch-up feature means the agent sees all messages since its last interaction, even if it wasn’t mentioned. Example: 
[2:32 PM] John: hey everyone, should we do pizza tonight?
[2:33 PM] Sarah: sounds good to me
[2:35 PM] John: @Andy what toppings do you recommend?
The agent sees the full conversation and understands the context (pizza discussion) even though it was only mentioned in the last message.
This makes group conversations feel natural - you don’t need to repeat context every time you involve the assistant.

​
Understanding Sessions

NanoClaw uses sessions to maintain conversation continuity:
  • Each group has its own session
  • Sessions persist across restarts
  • The assistant remembers what you talked about
  • Session transcripts are stored in data/sessions/{group}/.claude/
Example: 
[Today 9:00 AM] You: @Andy search for the best pizza places in SF
[Today 9:01 AM] Andy: Here are the top-rated pizza places...

[Today 5:00 PM] You: @Andy which one had the best reviews?
[Today 5:01 PM] Andy: Based on our earlier search, Tony's Pizza had...
The assistant remembers the morning conversation and can reference it in the afternoon.

​
Memory Hierarchy

NanoClaw has a three-level memory system:
1

Global Memory

Location: groups/CLAUDE.md
  • Read by all groups
  • Written by main channel only
  • Contains preferences, facts, and context shared everywhere
Example:
@Andy remember globally I prefer dark mode
2

Group Memory

Location: groups/{channel}_{group-name}/CLAUDE.md
  • Read by that group only
  • Written by that group
  • Contains group-specific conversation context
Example:
@Andy remember for this group: we meet every Tuesday
3

Files

Location: groups/{channel}_{group-name}/*.md
  • Created during conversations
  • Available to that group
  • Examples: notes.md, research.md, todo.md
Example:
@Andy create a file called ideas.md with project brainstorm notes

​
Container Isolation

Every agent runs in an isolated Linux container with:
  • Filesystem isolation: Only sees mounted directories
  • Safe Bash access: Commands run inside container, not on your host
  • Per-group context: Each group has its own container with its own working directory
  • Process isolation: Container processes can’t affect your system
This means you can safely let the assistant run bash commands, install packages, or experiment - it’s all sandboxed.

​
What Agents Can Access

Every agent has access to:
  • groups/{name}/ → Working directory with CLAUDE.md and files
  • groups/CLAUDE.md → Global memory (read-only for non-main)
  • data/sessions/{group}/.claude/ → Session transcripts

​
Advanced Usage

​
Agent Swarms

NanoClaw is the first personal assistant to support agent swarms - teams of specialized agents that collaborate: 
@Andy spin up a team: one agent to research AI frameworks, another to draft a comparison table, and a third to review for accuracy
Agent swarms are supported by NanoClaw Pro — see the README for details on parallel agent execution.

​
Custom Skills

You can add capabilities with Claude Code skills: 
/add-telegram      # Add Telegram channel
/add-gmail         # Add Gmail integration
/add-voice-transcription  # Whisper for voice messages
/customize         # Guided customization
See Customization for more.

​
Debugging

Ask Claude Code to debug issues: 
/debug
Or ask directly: 
Why isn't the scheduler running?
What's in the recent logs?
Why did this message not get a response?

​
Next Steps

Scheduled Tasks

Create recurring jobs and reminders

Proactive Agent

Enable morning check-ins and dynamic reminders

Memory System

Deep dive into how memory works

Security

Understand container isolation and safety

Build docs developers (and LLMs) love

Get started for freeTalk to us