cakeagent

<p align="center">
  <img src=".github/banner.jpg" alt="CakeAgent" style="max-width: 600px; width: 100%;">
</p>

# 🍰 CakeAgent

[![Build](https://github.com/kossov-it/cakeagent/actions/workflows/build.yml/badge.svg)](https://github.com/kossov-it/cakeagent/actions/workflows/build.yml)
![Lines](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/kossov-it/cakeagent/main/.badges/lines.json)
![Files](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/kossov-it/cakeagent/main/.badges/files.json)
![Deps](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/kossov-it/cakeagent/main/.badges/deps.json)
![Size](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/kossov-it/cakeagent/main/.badges/size.json)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

A personal AI agent you can actually read — with just around 2,400 lines of code, 9 files, and 3 runtime dependencies.

CakeAgent connects Claude to Telegram and gives it tools, voice, scheduling, file access, web search, and code execution. New capabilities come from two ecosystems: **MCP** (runtime tool servers) and **skills.sh** (knowledge-driven CLI integrations). Ask "add Google Calendar" in chat and it installs itself.

Runs as a single Node.js process under a dedicated system user. No containers, no web UI, no open ports.

### Get started

```bash
curl -fsSL https://raw.githubusercontent.com/kossov-it/cakeagent/main/install.sh | sudo bash
```

The script creates a `cakeagent` system user, installs everything to `/opt/cakeagent`, asks for your Telegram bot token and Claude credentials, and starts the service. Once running, send your bot a message — it walks you through the rest (name, personality, voice, integrations).

To uninstall completely (user, service, data, everything):
```bash
sudo bash /opt/cakeagent/setup.sh uninstall
```

---

## Why this exists

Open-source AI assistants have a bloat problem. The popular ones ship 400K+ lines of code, 50+ dependencies, WebSocket control planes, and custom plugin marketplaces — then get hit with critical RCE vulnerabilities and tens of thousands of exposed instances. Their plugin ecosystems? Some have been found to leak credentials.

CakeAgent does almost nothing itself and lets the ecosystem do the rest. The entire orchestrator is around 2,300 lines. Integrations come from two open ecosystems — MCP (thousands of tool servers) and skills.sh (CLI knowledge packs). No custom plugin format, no marketplace.

| | CakeAgent | Popular alternatives |
|---|---|---|
| **Source code** | ~2,400 LOC, 9 files | 400K+ LOC, 50+ modules |
| **Dependencies** | 3 | 47+ direct |
| **Open ports** | 0 | WebSocket, HTTP API |
| **Telegram** | 274 LOC raw `fetch()` | Framework + adapter |
| **Integrations** | MCP + skills.sh | Custom plugin marketplace |
| **Security** | 5-layer defense, every tool call audited | Varies — some have critical RCEs |
| **CVEs** | 0 | Multiple critical RCEs |

---

## Install

Linux server with Node.js 18+ required.

```bash
git clone https://github.com/kossov-it/cakeagent.git
cd cakeagent
sudo bash setup.sh
```

The setup script:

1. Checks Node.js
2. Creates a `cakeagent` system user (nologin shell, home at `/opt/cakeagent`)
3. Installs dependencies and builds
4. Configures passwordless sudo (`apt-get`, `apt`, `dpkg`, `systemctl`, `setup.sh`) — hooks restrict usage
5. Asks for your **Telegram bot token** — [get one from @BotFather](https://t.me/BotFather)
6. Asks for your **Telegram user ID** — [get it from @userinfobot](https://t.me/userinfobot)
7. Asks for **Claude authentication** (see below)
8. Installs and starts the systemd service

### Claude authentication

| Method | Where to get it | Saved as |
|--------|-----------------|----------|
| **Subscription token** (recommended) | Install [Claude Code CLI](https://www.npmjs.com/package/@anthropic-ai/claude-code), run `claude setup-token`, copy the `sk-ant-oat...` token (valid 1 year) | `CLAUDE_CODE_OAUTH_TOKEN` in `.env` |
| **API key** | [console.anthropic.com/settings/keys](https://console.anthropic.com/settings/keys), copy the `sk-ant-api...` key | `ANTHROPIC_API_KEY` in `.env` |

### Uninstall

```bash
sudo bash /opt/cakeagent/setup.sh uninstall
```

Removes the systemd service, the `cakeagent` user, the sudoers entry, and `/opt/cakeagent` entirely.

---

## Architecture

```
┌──────────────┐     ┌───────────────┐     ┌───────────────┐
│   Telegram   │────▶│  Orchestrator │────▶│  Claude Agent │
│  (raw fetch) │◀────│  (index.ts)   │◀────│  SDK query()  │
└──────────────┘     └───────┬───────┘     └──────┬────────┘
                             │                    │
       ┌─────────────────────┼────────────────────┤
       │                     │                    │
┌──────┴──────┐       ┌──────┴──────┐      ┌──────┴──────────┐
│   SQLite    │       │    Voice    │      │ Security Hooks  │
│ (store.ts)  │       │  STT / TTS  │      │  (6 PreToolUse  │
└─────────────┘       └─────────────┘      │   + PreCompact) │
                                           └──────┬──────────┘
       ┌──────────────────────────────────────────┴┐
       │              Tool Layer                   │
       │                                           │
       │  ┌─────────────┐ ┌───────────┐ ┌───────┐  │
       │  │  19 Built-in│ │ External  │ │Skills │  │
       │  │  MCP Tools  │ │ MCP (.mcp)│ │(.sh)  │  │
       │  └─────────────┘ └───────────┘ └───────┘  │
       └───────────────────────────────────────────┘
```

Messages go through three layers. Most never reach the Claude API:

1. **Settings callbacks** (inline keyboard buttons) — handled directly in the orchestrator
2. **Commands** (`/status`, `/settings`, `/update`, etc.) — handled in the orchestrator
3. **Everything else** — sent to Claude as a prompt with conversation context and persistent memory

### Source files

```
src/index.ts          660  Orchestrator, routing, debounce, scheduler
src/tools.ts          450  19 MCP tools (in-process)
src/store.ts          295  SQLite: messages, schedules, groups, audit, skills
channels/telegram.ts  274  Telegram adapter (raw fetch, retry, HTML, replies)
src/hooks.ts          272  Security hooks (Bash, Read, Grep, Glob, Write/Edit, PreCompact, SubagentStart)
src/types.ts          159  Type definitions + validation constants
src/voice.ts          129  Whisper STT + Edge TTS
src/agent.ts          111  Claude Agent SDK wrapper + streaming + subagents
src/config.ts          48  .env parser
```

### First run

On your first message, CakeAgent detects empty memory and starts an onboarding conversation:

1. Asks your name and preferred language
2. Asks about personality (casual, formal, etc.)
3. Offers to set up group chats
4. Offers to enable voice (installs dependencies if you say yes)
5. Suggests MCP integrations (calendar, email, etc.)

Everything is saved to `settings.json` and `memory.md`. The agent remembers your preferences across restarts and session resets.

### Streaming

Responses are streamed as the agent works. If Claude produces intermediate text (thinking out loud, progress updates), you see it immediately in Telegram instead of waiting for the full response. The final result is only sent if it wasn't already streamed.

### Memory

The agent has persistent memory in `data/memory.md`. It's injected into every prompt automatically — the agent always sees it. When you say "remember that..." or "from now on...", the agent writes to memory. It also cleans up stale entries periodically via `rewrite_memory`.

Memory survives restarts and `/reset`. The `/reset` command only clears the Claude SDK session (conversation turns), not learned preferences.

---

## Integrations

CakeAgent extends through two open ecosystems, searched **in parallel** when you ask to connect a service:

```
You:       "Connect to Google Calendar"
CakeAgent:  Found MCP server and a skill. MCP is preferred (structured tools).
           

[truncated…]