psibot

<div align="center">
  <img src="psibot_logo.jpg" alt="psibot" width="500">
  <h1>🦉 psibot: Always-On AI Agent for Telegram</h1>
  <p><strong>Your own personal AI assistant that runs 24/7 on your Mac. Powered by Claude Agent SDK + your Max subscription. $0 API costs.</strong></p>
  <p>
    <img src="https://img.shields.io/badge/Claude_Agent_SDK-Opus_4.6-d4a574" alt="Claude Agent SDK">
    <img src="https://img.shields.io/badge/cost-$0_API_fees-brightgreen" alt="$0 API costs">
    <img src="https://img.shields.io/badge/Telegram-bot-26A5E4?logo=telegram&logoColor=white" alt="Telegram bot">
    <img src="https://img.shields.io/badge/runtime-Bun-f9f1e1?logo=bun" alt="Bun">
    <img src="https://img.shields.io/badge/TypeScript-5.7+-3178C6?logo=typescript&logoColor=white" alt="TypeScript">
    <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
  </p>
</div>

A persistent, multimodal AI assistant that runs on your own hardware as a macOS daemon. Chat through Telegram with voice, images, and text. Manage scheduled tasks through a web dashboard. Let it work autonomously while you sleep.

**Built on the [Claude Agent SDK](https://github.com/anthropics/claude-agent-sdk)** &mdash; authenticates via OAuth with your existing Claude Max subscription. No API keys, no per-token billing, no surprise costs. If you're already paying for Max, psibot is effectively free to run.

> **How is this different from [OpenClaw](https://github.com/openclaw/openclaw)?** OpenClaw is a general-purpose AI assistant framework. psibot is purpose-built for a single user running Claude on their own Mac &mdash; optimized for Telegram, designed as an always-on daemon, and requires zero API spend beyond your existing Max plan.

## ✨ Key Features

**$0 API Costs** &mdash; Uses your Claude Max subscription via OAuth. No API keys, no per-token billing. Run Opus, Sonnet, and Haiku across all agents at no additional cost.

**Always-On Daemon** &mdash; Runs as a macOS LaunchAgent. Survives reboots, handles wake/sleep cycles, stays connected to Telegram 24/7, and runs autonomous tasks on a schedule.

**Telegram-Native** &mdash; First-class Telegram bot with voice messages, photo understanding, text-to-speech replies, and inline command menus. Not a web wrapper &mdash; a real bot experience.

**Multimodal AI** &mdash; Generates and edits images (Gemini), speaks with a neural voice (Edge TTS), transcribes voice messages (parakeet STT), and analyzes YouTube videos with semantic search.

**Persistent Memory** &mdash; Maintains knowledge files, daily logs, and structured memory across sessions. Learns about you over time and remembers context between conversations.

**Autonomous Subagents** &mdash; Spawns specialized agents: a coder (isolated git worktrees), a researcher (browser automation), an image generator, and an audio processor &mdash; each on the optimal model.

**Intelligent Inbox** &mdash; Captures content from Chrome bookmarks, Reddit saves, GitHub stars, and Telegram messages. A multi-phase heartbeat pipeline triages items with value-extraction, enriches them with web research, detects thematic clusters, and surfaces a prioritized digest with action buttons.

**On-Demand Research** &mdash; `/research` for quick scans (GLM + web search) or `/research deep` for full Claude-powered analysis. Research notes are saved to NotePlan with bidirectional wikilinks connecting related topics.

**Progressive Autonomy** &mdash; Learns from your feedback on digest items. Starts manual, earns trust through consistent agreement, and gradually auto-archives or auto-researches items matching learned patterns. Resets to manual on any override.

**Scheduled Tasks** &mdash; Cron-based job scheduling with budget controls. Periodic maintenance, reminders, or any recurring prompt with configurable quiet hours.

**MCP Tool Ecosystem** &mdash; Extensible via Model Context Protocol servers. Built-in tools for memory, browser automation, Telegram media, git worktrees, YouTube analysis, and more. Supports a secondary GLM backend (Z.AI) with web search, page reading, and GitHub repo analysis MCP servers.

**Web Dashboard** &mdash; HTMX + SSE streaming interface for real-time chat, job management, memory browsing, and log viewing.

<table align="center">
  <tr align="center">
    <th><p align="center">🎨 Image Editing</p></th>
    <th><p align="center">🌐 Browser Automation</p></th>
    <th><p align="center">🔊 Agentic Audio</p></th>
  </tr>
  <tr>
    <td align="center"><p align="center"><img src="image_editing.gif" width="300"></p></td>
    <td align="center"><p align="center"><img src="agent_browser.gif" width="300"></p></td>
    <td align="center"><p align="center"><img src="agentic_audio.gif" width="300"></p></td>
  </tr>
  <tr>
    <td align="center">Generate &bull; Edit &bull; Send</td>
    <td align="center">Navigate &bull; Read &bull; Research</td>
    <td align="center">Transcribe &bull; Speak &bull; Listen</td>
  </tr>
</table>

## 💡 Why Claude Agent SDK + Max?

Most AI agent frameworks (OpenClaw, nanobot, etc.) require API keys and charge per-token. If you're already paying for Claude Max, that's wasted money. psibot takes a different approach:

| | API-based agents | psibot (Max subscription) |
|---|---|---|
| **Authentication** | API key management | OAuth via `claude` CLI |
| **Cost model** | Pay per token | Fixed monthly subscription |
| **Bill risk** | Uncapped, usage-dependent | Zero additional cost |
| **Model access** | Depends on tier/budget | Opus, Sonnet, Haiku &mdash; all included |
| **Setup** | Generate keys, set budgets, monitor spend | `claude login` and go |

## 🏗️ Architecture

<p align="center">
  <img src="architecture.png" alt="psibot architecture" width="800">
</p>

## 🚀 Quick Start

### Prerequisites

- macOS (Apple Silicon or Intel)
- Xcode Command Line Tools (`xcode-select --install`)
- [Claude CLI](https://github.com/anthropics/claude-code) (`npm install -g @anthropic-ai/claude-code`) &mdash; authenticated with `claude login`
- A [Telegram bot token](https://core.telegram.org/bots#botfather)

### Automated Setup

The setup script handles everything from a fresh clone: Homebrew, Bun, dependencies, `.env` configuration, CLI linking, and daemon installation.

```bash
git clone https://github.com/DmacMcgreg/psibot.git
cd psibot
bash scripts/setup.sh
```

The script will:
1. Install Homebrew (if missing), then `bun`, `sqlite`, and `yt-dlp`
2. Install `uv` (Python tool runner)
3. Run `bun install` for node packages
4. Create `.env` from template and prompt for your Telegram bot token and user IDs
5. Link the `psibot` CLI and install the macOS LaunchAgent daemon
6. Optionally install `edge-tts`, `mlx-audio`, and `tailscale`

After setup, start the daemon:

```bash
psibot start
```

### Uninstall

To fully remove psibot (daemon, CLI, and optionally data/dependencies):

```bash
bash scripts/uninstall.sh
```

### Manual Setup

<details>
<summary>If you prefer to set things up manually</summary>

#### 1. Clone and install

```bash
git clone https://github.com/DmacMcgreg/psibot.git
cd psibot
bun install
bun link          # Makes the 'psibot' command available globally
```

#### 2. Configure

```bash
cp .env.example .env
```

Edit `.env` with your settings:

```env
TELEGRAM_BOT_TOKEN=123456:ABC-DEF...
ALLOWED_TELEGRAM_USER_IDS=123456789
PORT=3141
DEFAULT_MODEL=claude-opus-4-6
```

#### 3. Run

```bash
# Development (with hot reload)
bun run dev

# Production
bun run start
```

#### 4. Deploy as daemon (macOS)

```bash
psibot install   # Install LaunchAgent
psibot start     # Start the daemon
psibot status    # Check status
psibot logs      # Tail logs
```

</details>

### Optional Dependencies

| Tool | Purpose | Install |
|------|---------|---------|
| [uv](https://github.com/astral-sh/uv) | Python tool runner for audio tools | `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
| [mlx-audio](https://github.com/lucasnewman/mlx-audio) | STT (parakeet) on Apple Silicon | 

[truncated…]