clawdie-ai/docs/REQUIREMENTS.md

NanoClaw Requirements

Original requirements and design decisions from the project creator.

---

Why This Exists

This is a lightweight, secure alternative to OpenClaw (formerly ClawBot). That project became a monstrosity - 4-5 different processes running different gateways, endless configuration files, endless integrations. It's a security nightmare where agents don't run in isolated processes; there's all kinds of leaky workarounds trying to prevent them from accessing parts of the system they shouldn't. It's impossible for anyone to realistically understand the whole codebase. When you run it you're kind of just yoloing it.

NanoClaw gives you the core functionality without that mess.

---

Philosophy

Small Enough to Understand

The entire codebase should be something you can read and understand. One Node.js process. A handful of source files. No microservices, no message queues, no abstraction layers.

Security Through True Isolation

Instead of application-level permission systems trying to prevent agents from accessing things, agents run in actual FreeBSD jails. The isolation is at the OS level. Agents can only see what's explicitly mounted. Bash access is safe because commands run inside the jail, not on the host.

Built for One User

This isn't a framework or a platform. It's working software for specific needs. The active branch supports the channels and integrations it actually uses, rather than every possible messaging platform.

Customization = Code Changes

No configuration sprawl. If you want different behavior, modify the code. The codebase is small enough that this is safe and practical. Very minimal things like the trigger word are in config. Everything else - just change the code to do what you want.

AI-Native Development

I don't need an installation wizard - the coding agent guides the setup. I don't need a monitoring dashboard - I ask the agent what's happening. I don't need elaborate logging UIs - I ask the agent to read the logs. I don't need debugging tools - I describe the problem and the agent fixes it.

The codebase assumes you have an AI collaborator. It doesn't need to be excessively self-documenting or self-debugging because Claude is always there.

Skills Over Features

When people contribute, they shouldn't just pile more channels into core. They should contribute a skill or refactor that transforms the codebase cleanly. Users fork the repo, customize it, and end up with code that does exactly what they need.

---

RFS (Request for Skills)

Skills we'd love contributors to build:

Communication Channels

Skills to add or switch to different messaging platforms:

• /add-telegram - Add Telegram as an input channel
• /add-slack - Add Slack as an input channel
• /add-discord - Add Discord as an input channel
• /add-sms - Add SMS via Twilio or similar
• /convert-to-telegram - Replace the primary messaging channel with Telegram entirely

Runtime

The project targets FreeBSD jails as the only supported agent runtime.

Platform Support

FreeBSD is the only supported deployment platform.

---

Vision

A personal AI assistant accessible via messaging channels, with minimal custom code.

Core components:

• PI coding agent as the default core agent runtime
• FreeBSD jails for isolated agent execution
• Telegram as the primary I/O channel
• Persistent memory per conversation and globally
• Scheduled tasks that run Claude and can message back
• Web access for search and browsing
• Browser automation via agent-browser

Implementation approach:

• Use existing tools (messaging connectors, PI coding agent, MCP servers)
• Minimal glue code
• File-based systems where possible (AGENTS.md for memory, folders for groups)

---

Architecture Decisions

Message Routing

• A router listens to the configured messaging channel and routes messages based on configuration
• Only messages from registered groups are processed
• Trigger: @Andy prefix (case insensitive), configurable via ASSISTANT_NAME env var
• Unregistered groups are ignored completely

Memory System

• Per-group memory: Each group has a folder with its own AGENTS.md
• Global memory: Root AGENTS.md is read by all groups, but only writable from "main" (self-chat)
• Files: Groups can create/read files in their folder and reference them
• Agent runs in the group's folder, automatically inherits both AGENTS.md files

Session Management

• Each group maintains a conversation session (via the agent runtime)
• Sessions auto-compact when context gets too long, preserving critical information

Jail Isolation

• All agents run inside FreeBSD jails
• Each agent invocation spawns a jail-backed worker with mounted directories
• Jails provide filesystem isolation - agents can only see mounted paths
• Bash access is safe because commands run inside the jail, not on the host
• Browser automation via agent-browser runs inside the jail

Scheduled Tasks

• Users can ask Claude to schedule recurring or one-time tasks from any group
• Tasks run as full agents in the context of the group that created them
• Tasks have access to all tools including Bash (safe in container)
• Tasks can optionally send messages to their group via send_message tool, or complete silently
• Task runs are logged to the database with duration and result
• Schedule types: cron expressions, intervals (ms), or one-time (ISO timestamp)
• From main: can schedule tasks for any group, view/manage all tasks
• From other groups: can only manage that group's tasks

Group Management

• New groups are added explicitly via the main channel
• Groups are registered in SQLite (via the main channel or IPC register_group command)
• Each group gets a dedicated folder under groups/
• Groups can have additional directories mounted via jailConfig

Main Channel Privileges

• Main channel is the admin/control group (typically self-chat)
• Can write to global memory (groups/AGENTS.md)
• Can schedule tasks for any group
• Can view and manage tasks from all groups
• Can configure additional directory mounts for any group

---

Integration Points

Telegram

• Using the Telegram Bot API via grammy
• Messages stored in SQLite, polled by router
• Bot token verification during setup

Scheduler

• Built-in scheduler runs on the host, spawns jails for task execution
• Custom nanoclaw MCP server (inside the jail) provides scheduling tools
• Tools: schedule_task, list_tasks, pause_task, resume_task, cancel_task, send_message
• Tasks stored in SQLite with run history
• Scheduler loop checks for due tasks every minute
• Tasks execute the agent SDK in jailed group context

Web Access

• Built-in WebSearch and WebFetch tools
• Standard PI coding agent capabilities

Browser Automation

• agent-browser CLI with Chromium in the jail
• Snapshot-based interaction with element references (@e1, @e2, etc.)
• Screenshots, PDFs, video recording
• Authentication state persistence

---

Setup & Customization

Philosophy

• Minimal configuration files
• Setup and customization done via the agent
• Users clone the repo and run the agent to configure
• Each user gets a custom setup matching their exact needs

Skills

• /setup - Install dependencies, verify Telegram token, configure scheduler, start services
• /customize - General-purpose skill for adding capabilities (new channels like Telegram, new integrations, behavior changes)
• /update - Pull upstream changes, merge with customizations, run migrations

Deployment

• Runs on local Mac via launchd
• Single Node.js process handles everything

---

Personal Configuration (Reference)

These are the creator's settings, stored here for reference:

• Trigger: @Andy (case insensitive)
• Response prefix: Andy:
• Persona: Default Claude (no custom personality)
• Main channel: Private admin chat used for control and setup

---

Project Name

NanoClaw - A reference to Clawdbot (now OpenClaw).