CoClaw: Your AI-Powered Telegram Terminal in Your Pocket 🤖

Date: March 21, 2026
Category: Artificial Intelligence, Tutorials
Read Time: 6 min

---

The Problem: Context Switching Hell

You're deep in debugging a production issue. Your terminal is open. Your IDE is open. Slack is pinging. Your Telegram is notified about a deploy. And your brain is frantically switching contexts between three screens and five apps.

What if your AI assistant lived where you already are—in Telegram?

Meet CoClaw: A personal Telegram bot powered by the GitHub Copilot SDK that remembers everything you've told it, executes shell commands on your machines, reads and writes files, and searches the web—all from your phone.

No more switching apps. No more forgetting context. Just ask your bot.

---

What Makes CoClaw Different?

1. It Lives in Telegram 💬

Unlike standalone AI tools, CoClaw meets you where you actually chat. Your phone is already in your pocket. Your bot is already there.

You (Telegram):        "Check if our API is down"
CoClaw (Bot):          [Runs curl against prod]
                       "API responding 200. All good."
                       [Takes 3 seconds]

2. It Remembers Everything 🧠

CoClaw uses semantic embeddings to extract facts from every conversation and stores them in SQLite. When you ask a new question, it searches your entire history using vector similarity—not keywords.

Example:

• Three months ago you told CoClaw: "Our Azure storage account has read replicas in US East and Europe West"
• Today you ask: "What Azure regions do we use?"
• CoClaw automatically finds that fact, injects it into context, and gives you a complete answer without you remembering what you said before.

3. It Can Execute Commands 🚀

CoClaw runs shell commands directly on your machine:

You:       "/run npm run build && npm run test"
CoClaw:    [Executes on your laptop]
           "Build succeeded. 247 tests passing."

This is powerful (and intentionally dangerous). You control what commands CoClaw can run.

4. Sessions Survive Restarts 💾

Every conversation is tied to your Telegram chat ID. Even if the bot crashes, when it comes back up, it knows exactly where you were.

---

The Architecture: Elegant Simplicity

┌─────────────┐
│  Telegram   │  You send messages
└──────┬──────┘
       │
┌──────▼──────────────────────────────────────────┐
│     grammy Bot Library                           │
│  (Lightweight Telegram client)                   │
└──────┬──────────────────────────────────────────┘
       │
┌──────▼──────────────────────────────────────────┐
│     CopilotManager (Node.js)                     │
│  • Session persistence                           │
│  • Tool registration                             │
│  • Memory augmentation                           │
└──────┬──────────────────────────────────────────┘
       │
┌──────▼──────────────────────────────────────────┐
│     @github/copilot-sdk                          │
│  Powers the AI behind the bot                    │
└──────┬──────────────────────────────────────────┘
       │
┌─────────────┬──────────────┬────────────┐
│             │              │            │
▼             ▼              ▼            ▼
Web        Shell       File I/O      Memory
Search     Commands    Ops           Database

The beauty: CoClaw is written in TypeScript with ~500 lines of core logic. The heavy lifting is done by the Copilot SDK. You're just gluing components together intelligently.

---

The Memory System: Semantic Intelligence

Here's where CoClaw gets really interesting.

Every time you chat, CoClaw:

1. Extracts facts from both your message and the response

   • "We're migrating to Postgres from MySQL"
   • "Postgres migration will take ~3 days"
   • "Team is JP, Priya, and Soren"

2. Embeds those facts using transformer models (CPU-optimized)

   • These are NOT OpenAI embeddings
   • They run locally in the bot (no external API calls)
   • Fast (~100ms per embedding)

3. Stores them semantically in SQLite with vector similarity scores

   • Facts are categorized: infrastructure, security, cost, deployment, etc.
   • When you ask something new, the bot searches by semantic meaning

4. Injects context before asking Copilot

   User asks:        "How long is the migration?"
   Bot searches:     [Finds 3 related facts about migration]
   Bot to Copilot:   "Here's recent context: {facts}. 
                      Now answer: How long is the migration?"
   Copilot answers:  "~3 days, as you mentioned earlier..."
   

Why this matters: Your bot doesn't just answer one question in isolation. It understands your entire conversation history and builds a coherent picture.

---

Real-World Usage Patterns

Pattern 1: The "Give Me Status" Check

You:     "What's the status of the Azure security scanner?"
CoClaw:  [Searches memory for 'security scanner', 'Azure']
         "You last worked on it March 17. There were 3 open issues:
          1. Custom script upload feature
          2. Performance lag on large tenant scans
          3. Need better reporting"
         [Without you remembering details]

Pattern 2: The "Remind Me" Pattern

You:     "What did I configure last week?"
CoClaw:  [Searches vector embeddings]
         "You set up:
          • Copilot CLI aliases (/diff, /chronicle)
          • Azure Entra scanner custom scripts
          • New memory system (you were excited about this)"

Pattern 3: The "Do Something" Pattern

You:     "Run the test suite and tell me failures"
CoClaw:  /run npm test
         [Executes locally]
         "12 tests failing. Mostly in auth module. 
          Want me to search your notes on recent auth changes?"

---

Technical Highlights Under the Hood

1. Session Persistence ✅

• Sessions stored in .sessions/sessions.json
• Uses promise-based serialization to prevent race conditions
• Survives bot restarts perfectly

2. Memory Performance ✅

• Embedding model pre-loaded at startup (50-100x faster than lazy loading)
• LRU cache with 500-entry limit prevents memory bloat
• SQLite keeps memory footprint under 10MB

3. Type Safety ✅

• Pure TypeScript (no as any anywhere)
• Full Zod schema validation for config
• IDE autocomplete throughout

4. Production Hardened ✅

• Graceful shutdown with signal handlers
• Automatic retry on API failures
• Comprehensive error logging

---

Getting Started

CoClaw is open-source. Try it in 5 minutes:

bashCopy
# 1. Clone
git clone https://github.com/jptrsn/CoClaw
cd CoClaw

# 2. Install
npm install

# 3. Set up Copilot CLI (once)
copilot auth login

# 4. Configure
cp .env.example .env
# Add your Telegram bot token to .env

# 5. Run
npm run dev

Then message your bot on Telegram:

"What files are in ./src?"
"Search Azure in my memory"
"Run npm test"
"Give me memory stats"

---

What's Next?

The CoClaw team has exciting things planned:

• Knowledge Base Integration: Connect to Notion, Confluence, wikis
• Code Analysis: Deep understanding of your repos (stack traces, errors)
• Multi-Bot Clustering: Deploy multiple bots for high availability
• Guardrails: Smarter limits on what commands can execute

---

Why This Matters

AI assistants are everywhere now. But most of them are desktop tools, cloud services, or separate apps. They force you to adapt to them.

CoClaw inverts that. It comes to you. It remembers your context. It has superpowers (web search, shell access, file I/O), but it's lightweight and fast.

In other words: CoClaw is what happens when you design an AI assistant for how developers actually work—fragmented, context-switching, always on the move.

---

Try CoClaw today. Your Telegram bot is waiting.

---

Resources

• 📖 Full Documentation
• 🚀 Quick Start Guide
• 🧠 Memory System Deep Dive
• 📊 Executive Summary

---

Questions? Features requests? Bugs? Open an issue on GitHub or message the team.

Happy coding! 🚀