Alef Agent

A personal AI assistant on Telegram, powered by coding CLIs. Alef Agent uses Claude Code, Gemini CLI, Codex, Cursor, OpenRouter, Ollama, and OpenCode as interchangeable backends — giving you a multi-model AI assistant accessible from any device.

Send text, voice, photos, documents, or videos. Switch backends with /claude, /gemini, /codex, /cursor, /ollama, /openrouter, or /opencode. Spawn sub-agents across different CLIs to work in parallel. Schedule recurring tasks. Run multi-model council debates. Generate images. Execute shell commands. All state persists in SQLite.

What Can It Do

• Multi-backend AI — Switch between Claude, Gemini, Codex, Cursor, Ollama, OpenRouter, and OpenCode mid-conversation. Each backend supports per-model thinking levels. Gemini models include "Auto" as a selectable thinking level alongside Low and High.
• Agent orchestration — Spawn sub-agents using native CLI tools (Claude Agent, Codex spawn_agent, Gemini @subagent) or Alef Agent's cross-backend orchestration. /agents mode switches between native (fast, same-backend) and orchestrated (cross-backend, inbox, whiteboard, task board). Auto mode detects intent and picks the right one.
• Agent templates — Define reusable agent personas as markdown files (~/.alef-agent/agents/*.md). Security reviewers, content writers, researchers — spawn them by name.
• Scheduling — Cron jobs, one-shot tasks, and intervals. Per-job backend, model, and delivery (Telegram, webhook, or silent).
• Memory — Hybrid vector + keyword search. The agent remembers what you tell it across sessions, with salience decay.
• Voice — Send voice messages, get voice replies. Groq Whisper for transcription. Choose from ElevenLabs, Grok (xAI), or macOS for synthesis.
• 50+ CLI commands — Full system management from terminal. Every command supports --json for scripting.
• MCP support — Model Context Protocol servers extend the agent with external tools and data.
• Cross-channel awareness — Actions from CLI are visible to Telegram and vice versa via the activity log.
• Ollama — Local AI inference via Ollama servers for summarization, intent classification, and full chat. Zero-cost fallback. /ollama to manage servers and models. When multiple servers are online, /model shows a server-picker step with model counts per server.
• OpenRouter — API-based backend for accessing 200+ models. Model search, per-model pricing, credential rotation.
• OpenCode — Self-hosted agentic coding backend. opencode serve auto-launches on first use and stops after 10 minutes of inactivity. Full identity injection (SOUL.md/USER.md), MCP access, and dynamic model catalog from all configured providers. /opencode to switch; alef opencode models <query> to search and add models.
• Council debates — Multi-model structured debates via /council. Quick (1 round), ranked (peer ranking), or full (synthesis by chairman). Anonymous deliberation reduces model bias.
• Smart routing — /model auto classifies message complexity and picks the optimal model + thinking level per request. Trivial → cheapest, complex → best.
• Image generation — /imagine <prompt> generates images via Gemini API. Also available via [GENERATE_IMAGE:prompt] in agent responses.
• Shell access — !command runs shell commands. !!command for raw output. //<command> passes directly to the active backend CLI.
• Side quests — sq:question while the agent is busy starts a parallel conversation without interrupting the current task.
• Self-learning — /evolve enables a reflection engine that tracks feedback signals and proposes improvements to the agent's identity and behavior files.
• Interactive history — /history shows a day-grouped timeline with drill-down, time filters, backend filters, and full-text search.

Supported Backends

| Backend | CLI | Models | |---------|-----|--------| | Claude | claude | Opus 4.6, Sonnet 4.6, Haiku 4.5 | | Gemini | gemini | 3.1 Pro Preview, 2.5 Pro, 3 Flash, 3.1 Flash Lite | | Codex | codex | GPT-5.4, GPT-5.3 Codex, GPT-5.2 Codex, GPT-5.1 Codex Max, GPT-5.4 Mini | | Cursor | agent | auto (default), Opus 4.6, Sonnet 4.6, GPT-5.4, GPT-5.3 Codex, Grok 4.20, Gemini 3.1 Pro, Composer 2 + thinking variants | | Ollama | local | Any model available on connected Ollama servers | | OpenRouter | API | 200+ models via OpenRouter API (search with /model search) | | OpenCode | opencode | 146+ models across all configured providers (auto-launched on demand) |

Prerequisites

• Node.js 20+
• At least one backend CLI installed:
  • Claude Code — npm install -g @anthropic-ai/claude-code
  • Gemini CLI — npm install -g @google/gemini-cli
  • Codex — npm install -g @openai/codex
  • Cursor CLI — curl https://cursor.com/install -fsSL | bash
• Telegram bot token from @BotFather

Install

npm install -g alef-agent

Upgrade

npm install -g alef-agent@latest    # Update to latest version
alef-agent --version                # Verify
alef-agent service restart          # Restart to pick up changes

No config changes or migrations needed.

Setup

alef-agent setup

The wizard walks you through:

1. Creating a Telegram bot and pasting the token
2. Setting your chat ID (security — only you can use the bot)
3. Configuring backend credentials (all optional — configure what you use)
4. Optional features: voice, web dashboard, video analysis
5. Installing as a background service

Config saved to ~/.alef-agent/.env.

Run

The setup wizard offers to install Alef Agent as a background service. If you skipped that step:

alef-agent service install     # Install + start as background service

alef-agent service restart     # Restart (pick up config changes)
alef-agent service stop        # Stop the daemon
alef-agent service status      # Check if running
alef-agent start               # Run in foreground (for debugging)

CLI

alef-agent status              # System status
alef-agent doctor --fix        # Health checks + auto-repair
alef-agent logs -f             # Follow logs
alef-agent chat send "hello"   # Talk to the AI from terminal
alef-agent tui                 # Interactive terminal chat
alef-agent backend set gemini  # Switch backend
alef-agent agents spawn --runner claude --task "review code"
alef-agent cron list           # Scheduled jobs
alef-agent --ai                # Generate AI skill file

| Group | Description | |-------|-------------| | service | start, stop, restart, status, install, uninstall | | status / doctor / logs | Diagnostics and monitoring | | chat / tui | Terminal AI chat | | backend / model / thinking | Backend and model management | | memory | list, search, add, forget, history | | cron / schedule | Scheduler (create, cancel, pause, resume, run) | | agents / tasks / runners | Agent orchestration | | config | Runtime configuration | | usage / cost | Cost tracking and limits | | permissions / tools / verbose | Permission and tool management | | skills / mcps | Skills and MCP servers | | db | Database stats, backup, prune |

Read commands work offline (direct DB access). Write commands require the daemon.

Telegram Commands

Core

| Command | Description | |---------|-------------| | /menu (/m) | Home screen keyboard | | /help | All commands | | /status | Backend, model, session, usage | | /newchat | Start fresh (summarizes current session) | | /summarize | Save session to memory without resetting | | /stop | Cancel running task (also: type stop alone as plain text) |

Backend & Model

| Command | Description | |---------|-------------| | /backend | Switch backend via keyboard | | /claude /gemini /codex /cursor | Quick switch | | /model | Switch model + thinking level | | /thinking | Adjust thinking/reasoning level | | /summarizer | Session summarization model |

Scheduling

| Command | Description | |---------|-------------| | /schedule <desc> | Create a scheduled task | | /jobs | List jobs | | /run <id> | Trigger now | | /runs | Run history | | /editjob <id> | Edit a job | | /pause / /resume / /cancel | Job lifecycle | | /health | Scheduler health |

Agents

| Command | Description | |---------|-------------| | /agents | List sub-agents | | /agents mode | Set agent mode (auto/native/claw) | | /agents history | Native sub-agent activity (24h) | | /tasks | Task board | | /stopagent <id> | Cancel one agent | | /stopall | Cancel all agents | | /runners | Available CLI runners |

Settings

| Command | Description | |---------|-------------| | /cwd <path> | Set working directory | | /permissions | Permission mode (yolo/safe/readonly/plan) | | /tools | Configure allowed tools | | /voice | Toggle voice replies | | /voice_config | Configure voice provider and voice | | /response_style | Set the AI response style (concise/normal/detailed) | | /verbose | Tool visibility level | | /limits | Usage limits per backend (alias for /usage) |

Advanced

| Command | Description | |---------|-------------| | /council (/debate) | Multi-model structured debate | | /imagine <prompt> | Generate an image | | /evolve | Self-learning dashboard | | /reflect | Force immediate reflection analysis | | /optimize | Identity and skill audit | | /info | Current chat context (chatId, topic, session) | | /history (/hist) | Interactive message history timeline | | /ollama | Manage Ollama servers and models | | /chats | Multi-chat management | | !command | Execute shell command | | !!command | Raw shell output | | //command | Pass to active backend CLI | | sq:question | Side quest (parallel while busy) |

Memory & Context

| Command | Description | |---------|-------------| | /memory | List memories | | /remember <text> | Save a memory | | /forget <keyword> | Remove memories | | /history | Past session summaries | | /cost | API cost breakdown (alias for /usage) | | /skills | Browse skills | | /mcp | MCP servers |

Architecture

Telegram → TelegramChannel → router (handleMessage)
  ├── command → handleCommand
  ├── voice → Groq Whisper STT → askAgent → TTS (ElevenLabs/Grok/macOS)
  ├── photo/document/video → handleMedia → askAgent
  └── text → askAgent → sendResponse
                         └── [SEND_FILE:/path] → channel.sendFile

askAgent() delegates to the active backend adapter, which constructs CLI args, spawns the subprocess, and parses NDJSON output. All state lives in SQLite with FTS5 full-text search.

Agent Orchestration

"Have Claude review the code while Gemini researches the API docs"
  → spawn_agent(runner: "claude", name: "code-reviewer", role: "reviewer")
  → spawn_agent(runner: "gemini", name: "api-researcher", role: "researcher")
  → Agents communicate via inbox, share data on whiteboard
  → Results flow back to the main agent

Sub-agents support named agents with personas, 9 role presets, file-based templates, per-agent model/tool overrides, task dependencies, idle detection, and cost tracking.

Agent Templates

Define reusable agents in ~/.alef-agent/agents/*.md:

---
name: security-reviewer
description: Reviews code for security vulnerabilities
runner: claude
role: reviewer
model: claude-sonnet-4-6
---
You are a senior security engineer...

The main agent discovers templates via list_templates and spawns them by name.

Adding a CLI Runner

No code changes needed:

1. Tell Alef Agent: "Onboard cursor CLI as a sub-agent"
2. The agent discovers capabilities, writes a JSON config to ~/.alef-agent/runners/
3. Available immediately via /runners

Adding a Channel

1. Implement the Channel interface in src/channels/<name>.ts
2. Implement getCapabilities() for supported features
3. Register in src/index.ts

Notifications broadcast to all channels. Health monitored with auto-reconnection.

Environment Variables

Set in ~/.alef-agent/.env (created by alef-agent setup):

| Variable | Required | Description | |----------|----------|-------------| | TELEGRAM_BOT_TOKEN | Yes | From @BotFather | | ALLOWED_CHAT_ID | Yes | Comma-separated chat IDs | | CLAUDE_CODE_USE_VERTEX | For Claude | Set to 1 | | CLOUD_ML_REGION | For Claude | e.g., us-east5 | | ANTHROPIC_VERTEX_PROJECT_ID | For Claude | GCP project ID | | GROQ_API_KEY | No | Voice transcription | | ELEVENLABS_API_KEY | No | Voice replies (ElevenLabs) | | XAI_API_KEY | No | Voice replies (Grok/xAI) | | GEMINI_API_KEY | No | Video analysis | | DASHBOARD_ENABLED | No | 1 for web dashboard on port 3141 | | EMBEDDING_PROVIDER | No | ollama (default), gemini, openai, off | | ALEF_AGENT_HOME | No | Config directory (default: ~/.alef-agent) | | CURSOR_API_KEY | No | Cursor backend API key | | ALEF_AGENT_DASHBOARD_HOST | No | Dashboard bind address (default: 0.0.0.0) | | REFLECTION_CODEBASE_RECOMMENDATIONS | No | 1 to enable codebase change proposals |

Documentation

• Quick Start — Zero to working bot in 10 minutes
• User Guide — Full reference for all features
• Roadmap — Planned features

License

MIT