Skip to content

CAN-Aidoo/Can-claw

BranchesTags

Repository files navigation

🤖 Canclawd

A powerful, local-first AI assistant running on Telegram. Built with TypeScript, powered by OpenRouter, and packed with 28+ agentic tools.

Telegram: @Canclawdbot

✨ Features

Category Feature Description
🧠 Memory SQLite Memory Persistent facts, preferences, and context
🧠 Memory Knowledge Graph Interconnected entities with relationships
🧠 Memory Context Pruning Auto-summarize when approaching token limits
🧠 Memory Multimodal Memory Extract info from images, audio, video, docs
🧠 Memory Self-Evolving Memory Decay, merge duplicates, auto-reorganize
🧠 Memory Markdown Memory Human-readable .md files in data/memory/
🧠 Memory Supabase + pgvector Cloud semantic search (optional)
⚡ Tools Shell Commands Execute commands with safety allowlists
⚡ Tools File Operations Read, write, list, search, delete files
⚡ Tools Browser Automation Navigate, click, type, screenshot, extract
⚡ Tools Web Search DuckDuckGo search (no API key needed)
⚡ Tools Scheduled Tasks Cron-based recurring tasks
⚡ Tools Webhook Triggers HTTP endpoints that route to the agent
⚡ Tools MCP Tool Bridge Connect to MCP servers, discover tools dynamically
⚡ Tools Skills System Markdown-defined capabilities loaded at startup
📡 Channels Telegram Primary channel (always active)
📡 Channels WhatsApp Via Baileys (optional)
📡 Channels Discord Via discord.js (optional)
📡 Channels Slack Via Bolt SDK (optional)
📡 Channels Gmail Via Google APIs (optional)
🎙 Voice Transcription Groq Whisper (speech-to-text)
🎙 Voice TTS ElevenLabs (text-to-speech)

🚀 Quick Start

Prerequisites

  • Node.js ≥ 20
  • npm (comes with Node.js)

1. Clone & Install

git clone https://github.com/your-username/canclawd.git
cd canclawd
npm install

2. Configure Environment

cp .env.example .env

Edit .env and fill in the required values:

# Required
TELEGRAM_BOT_TOKEN=your-telegram-bot-token
OPENROUTER_API_KEY=your-openrouter-api-key
ALLOWED_USER_IDS=your-telegram-user-id

💡 Get your Telegram bot token from @BotFather 💡 Get your OpenRouter API key from openrouter.ai 💡 Get your Telegram user ID from @userinfobot

3. Run

# Development (with hot-reload)
npm run dev

# Production
npm run build
npm start

🛠 Tools Setup Guide

All tools work through the Telegram chat — you talk to the bot naturally, and it decides which tools to use. You do not run tools from your terminal.

Shell Commands

The agent can execute shell commands on your machine when you ask.

How to use (talk to the bot):

  • "Run git status in the project directory"
  • "What's my current disk usage?"
  • "Run npm outdated"

Safety: Commands are validated against an allowlist. Dangerous commands like rm -rf / are blocked. To customize:

# Add extra allowed commands (comma-separated)
SHELL_ALLOWLIST=docker,kubectl,terraform

# Change timeout (default: 30 seconds)
SHELL_TIMEOUT=60000

Default allowed commands: ls, dir, cat, echo, pwd, node, npm, npx, git, python, pip, curl, grep, find, mkdir, cp, mv, tar, zip, and more.

File Operations

Read, write, list, and search files through the agent.

How to use:

  • "List files in the data directory"
  • "Read the contents of package.json"
  • "Create a file called notes.txt with today's meeting notes"
  • "Search for all TypeScript files containing 'logger'"

Safety: Path allowlisting restricts access to specific directories.

# Directories the agent can access (comma-separated, default: ./data,./skills,.)
FILE_ALLOWED_DIRS=./data,./skills,./src

# Max file size for reads/writes (default: 1MB)
FILE_MAX_SIZE=1048576

Browser Automation

Navigate web pages, take screenshots, click buttons, and extract content.

Setup (optional — only install if you need it):

npm install playwright
npx playwright install chromium

How to use:

  • "Go to https://example.com and take a screenshot"
  • "Navigate to GitHub and extract the trending repositories"
  • "Click the login button on that page"

The browser auto-closes after 2 minutes of inactivity.

Web Search

Search the web using DuckDuckGo — no API key required.

How to use:

  • "Search the web for TypeScript best practices 2025"
  • "Find information about Node.js 22 new features"
  • "Look up the latest news about AI"

Returns top results with titles, snippets, and URLs.

Scheduled Tasks

Schedule recurring tasks using cron expressions.

How to use:

  • "Schedule a daily reminder at 9am to check my emails"
  • "Create a task that runs every Monday to generate a weekly report"
  • "List all scheduled tasks"
  • "Pause the morning reminder task"

Cron expression format: minute hour day-of-month month day-of-week

Example Schedule
0 9 * * * Every day at 9:00 AM
0 9 * * 1-5 Weekdays at 9:00 AM
*/30 * * * * Every 30 minutes
0 0 1 * * First day of every month

Bot command: /tasks — view all scheduled tasks

Webhook Triggers

Create HTTP endpoints that trigger the agent when called.

How to use:

  • "Create a webhook called 'github' for GitHub push notifications"
  • "Set up a webhook endpoint for my CI/CD pipeline"
# Webhook server port (default: 3100)
WEBHOOK_PORT=3100

Test a webhook:

curl -X POST http://localhost:3100/webhook/github \
  -H "Content-Type: application/json" \
  -d '{"event": "push", "repo": "canclawd"}'

Bot command: /webhooks — view all registered webhooks

The health endpoint is always available at http://localhost:3100/health.

MCP Tool Bridge

Connect to Model Context Protocol servers to dynamically add tools.

Setup: Create mcp-servers.json in the project root:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./data"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "your-github-token"
      }
    }
  }
}
# Path to MCP config (default: ./mcp-servers.json)
MCP_CONFIG_PATH=./mcp-servers.json

The bridge connects via stdio, discovers all available tools, and registers them as mcp_<server>_<tool> for the LLM.

Skills System

Skills are markdown files that define reusable capabilities. The agent loads them on startup and can apply them when triggered.

Setup: Add .md files to the skills/ directory:

---
name: code_review
description: Review code for best practices and security issues
triggers: [review, code review, check code, audit code]
---

# Code Review Skill

When the user asks you to review code, follow this approach:

## Step 1: Security Check
Look for SQL injection, XSS, hardcoded secrets...

## Step 2: Code Quality
Check error handling, type safety, naming conventions...

Frontmatter fields:

Field Required Description
name Yes Skill identifier
description Yes Short description
triggers No Keywords that activate the skill

How to use:

  • "Review this code" (triggers the code_review skill automatically)
  • "List all skills"
  • "Reload skills" (after adding new .md files)

Bot command: /skills — view all loaded skills

# Skills directory (default: ./skills)
SKILLS_DIR=./skills

📡 Channel Setup

Telegram (Required)

Always active. Get your bot token from @BotFather.

WhatsApp (Optional)

WHATSAPP_ENABLED=true

Scan the QR code that appears in the terminal on first run.

Discord (Optional)

DISCORD_TOKEN=your-bot-token
DISCORD_CLIENT_ID=your-client-id
DISCORD_GUILD_ID=your-guild-id

Slack (Optional)

SLACK_BOT_TOKEN=xoxb-your-token
SLACK_SIGNING_SECRET=your-secret
SLACK_APP_TOKEN=xapp-your-token

Gmail (Optional)

GMAIL_CLIENT_ID=your-client-id
GMAIL_CLIENT_SECRET=your-client-secret
GMAIL_REFRESH_TOKEN=your-refresh-token

🧠 Memory Setup

SQLite (Default)

Works out of the box. Data stored in data/memory.db.

Markdown Memory

Human-readable .md files in data/memory/. Git-friendly.

MEMORY_MARKDOWN_DIR=./data/memory

Supabase + pgvector (Optional Cloud)

For semantic similarity search and cross-device persistence:

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your-anon-key

Then install the client:

npm install @supabase/supabase-js

Create the required tables in Supabase SQL editor:

-- Enable pgvector extension
create extension if not exists vector;

-- Memories table
create table memories (
  id text primary key,
  user_id bigint not null,
  category text not null,
  content text not null,
  tags text[] default '{}',
  importance float default 0.5,
  access_count int default 0,
  embedding vector(1536),
  created_at timestamptz default now(),
  last_accessed timestamptz default now(),
  metadata jsonb default '{}'
);

-- Semantic search function
create or replace function match_memories(
  query_embedding vector(1536),
  match_threshold float,
  match_count int,
  filter_user_id bigint
) returns table (
  id text, user_id bigint, category text, content text,
  tags text[], importance float, access_count int,
  embedding vector(1536), created_at timestamptz,
  last_accessed timestamptz, metadata jsonb
) language sql as $$
  select * from memories
  where user_id = filter_user_id
    and 1 - (memories.embedding <=> query_embedding) > match_threshold
  order by memories.embedding <=> query_embedding
  limit match_count;
$$;

-- Sessions table
create table sessions (
  id text primary key,
  user_id bigint not null,
  messages text not null,
  updated_at timestamptz default now()
);

🎙 Voice Setup

Transcription (Speech-to-Text)

Uses Groq's Whisper API:

GROQ_API_KEY=your-groq-api-key

Get a free key at console.groq.com.

Text-to-Speech

Uses ElevenLabs:

ELEVENLABS_API_KEY=your-elevenlabs-api-key
ELEVENLABS_VOICE_ID=21m00Tcm4TlvDq8ikWAM
VOICE_REPLY_MODE=auto  # auto | always | never

🤖 Bot Commands

Command Description
/start Welcome message with feature overview
/ping Uptime check
/model Current LLM model
/status Full system status
/memory Memory system status
/compact Compress session context
/tasks List scheduled tasks
/webhooks List webhook endpoints
/skills List loaded skills
/voice Toggle voice reply mode

📁 Project Structure

canclawd/
├── src/
│   ├── index.ts              # Entry point
│   ├── agent/
│   │   ├── index.ts          # Agentic loop
│   │   ├── types.ts          # Agent types
│   │   └── tools/
│   │       └── index.ts      # Tool registry (28+ tools)
│   ├── bot/
│   │   ├── index.ts          # Bot setup + commands
│   │   ├── handlers/
│   │   │   ├── message.ts    # Text message handler
│   │   │   └── voice.ts      # Voice message handler
│   │   └── middleware/
│   │       └── auth.ts       # User ID allowlist
│   ├── channels/             # Multi-channel adapters
│   ├── config/
│   │   └── index.ts          # Zod-validated config
│   ├── memory/               # 7 memory subsystems
│   │   ├── index.ts          # Central manager
│   │   ├── types.ts          # Shared types
│   │   ├── sqlite.ts         # SQLite CRUD
│   │   ├── knowledge-graph.ts
│   │   ├── context-pruner.ts
│   │   ├── multimodal.ts
│   │   ├── self-evolving.ts
│   │   ├── markdown.ts
│   │   └── supabase.ts
│   ├── tools/                # 8 tool modules
│   │   ├── shell.ts
│   │   ├── filesystem.ts
│   │   ├── browser.ts
│   │   ├── web-search.ts
│   │   ├── scheduler.ts
│   │   ├── webhooks.ts
│   │   ├── mcp-bridge.ts
│   │   └── skills.ts
│   ├── utils/
│   │   └── logger.ts
│   └── voice/
│       ├── index.ts
│       ├── transcribe.ts
│       └── tts.ts
├── data/                     # Runtime data (git-ignored)
├── skills/                   # Skill files (.md)
│   └── code_review.md
├── .env.example
├── package.json
└── tsconfig.json

📜 License

MIT

About

AI friendly Assistant

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages