Nanoclaw-py: Personal AI Agent in 500 Lines

Build a Personal AI Agent in ~500 Lines of Python

Nanoclaw-py is a lightweight, single-user AI agent powered by Anthropic's Claude Code SDK that runs on Telegram. It combines natural language understanding with practical capabilities—file operations, command execution, web search, and task scheduling—all implemented in approximately 500 lines of Python. This project demonstrates how to build a functional AI agent without unnecessary complexity.

Purpose and Significance

Nanoclaw-py bridges the gap between AI capability and practical accessibility. Rather than deploying enterprise-grade multi-user systems, it focuses on a personal-scale agent that learns from interactions, persists state across sessions, and integrates seamlessly into existing Telegram workflows. The project is part of ApeCode.ai's learning series, making it ideal for developers exploring agentic AI patterns without framework overhead.

Core Features

• Natural Language Interface: Powered by Claude Code SDK; understands complex, multi-step instructions without rigid command syntax
• File Operations: Read, write, and edit files within a persistent workspace directory
• Command Execution: Run Bash commands and Python scripts directly; output streams back to Telegram
• Web Search: Built-in WebSearch and WebFetch MCP tools for real-time information retrieval
• Task Scheduling: Cron, interval, and one-time task scheduling with proactive notifications via Telegram
• Long-Term Memory: CLAUDE.md file persists user preferences, facts, and context across sessions
• Conversation Archiving: Daily markdown archives stored in conversations/ folder, searchable by the agent
• Session Continuity: Automatic state restoration after restart; session ID persisted in data/state.json

Architecture Overview

The codebase is organized into nine focused modules totaling 533 lines. The entry point (__main__.py) initializes the Telegram bot and scheduler. The agent.py module (210 lines) orchestrates Claude Code SDK calls and manages six MCP tools for task scheduling and messaging. The bot.py handles Telegram message routing, while db.py manages SQLite persistence for scheduled tasks. Supporting modules handle environment configuration, long-term memory management, task scheduling via APScheduler, and daily conversation archiving.

MCP Tools

The agent interacts with Telegram and the scheduler through Model Context Protocol tools:

• send_message: Proactively send messages during long operations or scheduled task execution
• schedule_task: Create cron, interval, or one-time scheduled tasks
• list_tasks, pause_task, resume_task, cancel_task: Manage scheduled task lifecycle

Getting Started

Prerequisites: Python 3.12+, uv package manager, Claude Code CLI, Telegram Bot Token (from @BotFather), and Anthropic API Key.

Installation: Clone the repository, run uv sync to install dependencies, copy .env.example to .env, and populate TELEGRAM_BOT_TOKEN, OWNER_ID, and ANTHROPIC_API_KEY. Launch with uv run python -m nanoclaw and message your Telegram bot to begin.

Configuration

Required environment variables include TELEGRAM_BOT_TOKEN, OWNER_ID (your Telegram user ID), and ANTHROPIC_API_KEY. Optional settings include ANTHROPIC_BASE_URL for custom API endpoints (proxies, gateways, or LiteLLM), ASSISTANT_NAME for custom bot identity, and SCHEDULER_INTERVAL to adjust task-check frequency (default 60 seconds). The project supports enterprise API routing via any Anthropic Messages API–compatible endpoint.

Data Persistence

The agent maintains five persistent data locations: workspace/ (file operations), workspace/CLAUDE.md (long-term memory), workspace/conversations/ (daily chat archives), store/nanoclaw.db (SQLite task storage), and data/state.json (session continuity). All directories are created automatically on first run.

Who This Is For

• AI/ML Developers: Learning agentic patterns and Claude Code SDK integration without framework bloat
• Python Learners: Studying modular agent architecture in a digestible, ~500-line codebase
• Automation Enthusiasts: Building personal productivity tools that understand natural language
• Telegram Power Users: Extending Telegram with AI-driven task automation and scheduling
• Educational Projects: Part of ApeCode.ai's learning series; ideal for teaching agentic AI concepts

Security Considerations

This project is designed for personal, private deployment only. The agent runs in bypassPermissions mode and can execute arbitrary commands. The OWNER_ID restriction ensures only you can access it. Do not expose publicly or share credentials, as it poses significant security risks. For multi-user or production scenarios, implement proper authorization layers and audit logging.

Notable Design Decisions

Single-user architecture prioritizes simplicity and learning clarity over multi-tenant complexity. Session persistence survives restarts and /clear commands, enabling truly long-term agent interactions. Scheduled tasks are stored in SQLite rather than in-memory, ensuring reliability across application lifecycle. The project deliberately avoids heavyweight frameworks, making it easy to understand, modify, and extend.

Commands

• /start – Display welcome message and capability overview
• /clear – Clear current session and start fresh (long-term memory in CLAUDE.md persists)
• Any text – Chat with the AI; natural language instructions are understood and executed

Frequently Asked Questions

How do I get my Telegram user ID? Message @userinfobot on Telegram; it returns your user ID immediately.

Why is this single-user only? Educational focus and security: bash execution privileges make public exposure dangerous. This design ensures safe learning without multi-user complexity.

Do scheduled tasks survive restarts? Yes. Tasks are persisted in SQLite and automatically resumed on startup.

Can I use a custom API endpoint or proxy? Yes. Set ANTHROPIC_BASE_URL to any Anthropic Messages API–compatible endpoint.

Is long-term memory preserved across /clear? Yes. CLAUDE.md survives /clear commands, preserving user preferences and facts.

Resources

• GitHub Repository: ApeCodeAI/nanoclaw-py
• Original Inspiration: nanoclaw by gavrielc (WhatsApp version)
• Anthropic Documentation: Claude API and Code SDK reference
• Telegram Bot API: Telegram Bot Platform
• Learning Series: Part of ApeCode.ai AI agent curriculum

License: MIT (open source)

Source: GitHub repository ApeCodeAI/nanoclaw-py, updated February 2026. Translated and adapted from bilingual documentation.