Features

2 min read

nclaw provides a rich set of features that make Claude Code accessible and useful through Telegram.

Session Persistence

Each chat/topic maintains its own Claude session. Conversations are preserved across messages, so you can pick up where you left off. Session data is stored per-chat in the configured NCLAW_DATA_DIR.

Telegram Topics

Each topic in a group chat is a separate project with its own working directory. One group chat with topics becomes a multi-project workspace — each topic gets isolated context, history, and files.

File Handling

Inbound Files

Send any file type to Claude through Telegram:

  • Documents — PDFs, spreadsheets, text files
  • Photos — screenshots, diagrams, images
  • Audio — voice messages, audio files
  • Video — screen recordings, video files
  • Stickers — image stickers

Files are downloaded to the chat directory and referenced in Claude’s prompts. They’re cached by unique ID and size to avoid re-downloading.

Outbound Files

Claude can send files back to you. When Claude generates a file (reports, code, exports), it’s delivered as a Telegram document.

Scheduled Tasks

Create recurring or one-time tasks using natural language:

Remind me to check the deployment every weekday at 9am
Every 30 minutes, check if the staging server is healthy
At 3pm today, generate a summary of today's git commits

Tasks support three schedule types:

  • Cron — standard cron expressions for complex schedules
  • Interval — repeat every N minutes/hours
  • One-time — run once at a specified time

Tasks persist in SQLite and reload on startup. Each task can continue the existing chat session or run in a fresh isolated context.

Webhooks

Register HTTP endpoints that forward incoming requests to Claude:

Create a webhook that receives GitHub push events and summarizes the changes
Set up a webhook for my package tracking updates
Listen for smart home alerts and notify me about unusual activity

When an external service calls the webhook URL, the request (method, headers, query params, body) is forwarded to Claude in the originating chat. The HTTP endpoint returns 200 immediately; Claude processes the request asynchronously. Webhooks persist across restarts.

Requires NCLAW_WEBHOOK_BASE_DOMAIN to be set. Webhook URLs follow the pattern https://{BASE_DOMAIN}/webhooks/{UUID}.

Rich Runtime

The Docker image includes git, gh CLI, Chromium, Go, Node.js, and Python/uv. The assistant can install additional packages on the fly as needed — for example, apk add ffmpeg to process video, npm install -g prettier to format code, or pip install pandas to analyze data.

Message Formatting

Responses render using Telegram’s HTML formatting with plain-text fallback. Long messages are automatically split at newline boundaries (max 4096 chars per message) to stay within Telegram’s limits.

Configuration Skills