📚 Documentation
Every feature, every setting.
Everything the app does and every setting it has — written for the version you're running. From the menu bar to the skills registry, this is the whole manual.
On this page
Quick start The menu bar app Settings, explained Model tab Telegram tab Per-bot pages App tab Skills & Features Skill Registry Updates Data & privacy TroubleshootingQuick start
- Install. Download the .dmg, drag Telebot AI into Applications. The build isn't notarized yet, so if macOS shows a warning, right-click (Control-click) the app and choose Open — once.
- Create a bot. Message @BotFather on Telegram, run /newbot, and copy the token. One token per bot — you can run several.
- Add the token. Open Telebot AI from the menu bar, open Settings, and paste the token into a bot's Token field. It's saved the moment you type — there's no Save button.
- Connect a brain. In the Model tab, set the server URL (http://localhost:11234 for mlx-serve, http://localhost:11434 for Ollama) and model name, or use any OpenAI-compatible cloud API. Hit Test to check the connection.
- Start the bot. Back in the menu bar, choose Start bot. Message your bot on Telegram — it answers from that moment on.
New to local models? Read the guide — it covers mlx-serve, Ollama and LM Studio, and how much RAM each model needs.
The menu bar app
Telebot AI lives in your menu bar (⌘ icon). The menu gives you:
- Start / Stop / Restart — per bot and all at once. Bots run as LaunchAgents: always on, out of your way.
- Open Settings — the settings window.
- Logs — tail the bot's log to see what it's doing or debug a problem.
- Quit — stops everything (and disables the LaunchAgents until you start again).
Settings, explained
The settings window has a sidebar with two kinds of pages:
- Defaults — Model, Telegram, App, Skills & Features, Skill Registry, About, Updates. Values every bot inherits.
- Bots — one page per bot. Every field shows what this bot actually uses: a value overrides the default, an empty field inherits it (the explainer under each row says so). That's why there are no "Use global" checkboxes — an empty field is "use global".
Everything auto-saves as you type or toggle. Settings live in ~/.mlx-serve/config.json.
Defaults → Model
| Setting | What it does |
|---|---|
| Server URL | The OpenAI-compatible endpoint. Local servers need no key. |
| API key | Empty for local servers (mlx-serve, Ollama, LM Studio). The eye button shows or hides it. |
| Model name | Which model on that server, e.g. deepseek-v4-flash-free. |
| Test | Checks the connection with the current values — useful before saving anything. |
| Backup models | Tried in order when the primary fails or throttles. Each has its own nickname, URL, key and model, plus Test, reorder and remove. Add is disabled until the last row is complete. |
Defaults → Telegram
| Setting | What it does |
|---|---|
| Allowed chat IDs | Comma-separated user/group IDs that may talk to the bot. Empty = anyone. |
| Daily briefing time | When the bot sends its daily briefing — 24-hour hour/minute dropdowns (e.g. 08:00). |
| Briefing prompt | What the briefing should cover — e.g. "weather, my reminders for today, and any price alerts". |
| Max reply tokens | Safety ceiling for replies; long answers split into multiple messages. |
| Context per chat | How many recent messages the bot holds per chat as context. |
| Memories per user | Long-term memories recalled per user, per message the bot answers. |
| Memory database size (per user) | Max stored memories per user; the oldest are evicted beyond this. |
| Research report tokens | Budget for /research and /insiders reports. |
| API timeout (s) | Seconds before a slow provider is abandoned — free-tier queues can stall for a minute+. |
| Soul file | The persona the bots run with. .md files in this folder (soul*.md, *persona*.md) appear in every bot's Soul dropdown. |
| Bot trigger words | Comma-separated words that make the bot answer in groups (besides @mention, reply or command) — e.g. "momo, jarvis, hey bot". |
| Video/audio clip trigger words | Words that make the bot grab an attached video or audio as a clip — e.g. "clip this, save this". |
Per-bot pages
Each bot in the sidebar has its own page. Empty fields inherit the defaults; the explainer under each row states what it inherits.
| Setting | What it does |
|---|---|
| Token | The bot's @BotFather token (eye button to reveal). Changing it renames the bot's sidebar entry. |
| Nickname | Used in status, logs and the sidebar — e.g. "Trading". |
| Allowed chat IDs / Trigger words / Clip words | This bot's overrides of the matching defaults. |
| Server URL, API key, Model | The dropdown offers the providers configured in Defaults → Model, plus any custom value. Own backup models can be added per bot. |
| Daily briefing time / Briefing prompt | Per-bot briefing with a "Use global" button that clears the override. |
| Mode | Researcher, Assistant, Coder, Chef or None — empty uses the default mode. |
| Soul file | This bot's persona override, chosen from the soul/persona files found on disk. |
| Skills | Opens the per-bot skill sheet — disable skills for this bot on top of the defaults, or reset to default. |
Defaults → App
| Setting | What it does |
|---|---|
| Show in Dock | Whether the menu bar app also appears in the Dock. |
| Launch at Login | Start Telebot AI when you log in. |
| Data directory | Where config, memory, reminders and logs live (default ~/.mlx-serve). |
| Open log / Open data folder | Jump straight to the log file or data folder in Finder. |
| Export settings | Save the full config (including API keys) to a file — for backups or moving Macs. |
| Import settings | Load a config file and apply it immediately. |
Skills & Features
The bot's abilities are model-driven skills — plain instructions the model follows with its tools, so you can describe what you want in plain language instead of memorizing commands. Each group has a master toggle; individual skills can be switched on or off.
| Group | Skills | Try saying |
|---|---|---|
| Research | stock-research, stocks-crypto, insider-trading, currency | "research TSLA", "price of BTC", "insider trades for AAPL", "how much is 50 USD in CAD?" |
| Daily | briefing, digest, reminders, habits, review, pomodoro, bookmarks, expenses | "/briefing", "digest this chat", "remind me at 5pm", "mark today's habit done", "weekly review", "/pomodoro 25", "track 25 lunch" |
| Media | media, voice, translation, feeds | "analyze this video", "read this aloud", "translate this to Chinese", "what's new in my feeds?" |
| Tools | memory | "what did we talk about yesterday?" |
| From registry | Skills you install from the registry | — |
Skill Registry
The registry tab lets you install ready-made skills from the public anthropics/skills catalog — PDF and document handling, spreadsheets, presentations, web-app testing, MCP server building, art and more. Load the catalog, pick a skill, and it appears in the Skills & Features tab like any other.
Updates
The Updates tab checks the landing site's manifest against your installed version and shows the latest release with a download link. Checks are quiet — offline or unreachable just means "up to date". To update: download the new .dmg and drag it over the old app in Applications. Settings, bots and memories live outside the app, so they carry over untouched.
Data & privacy
- Where things live: config, chat memory, reminders, skills and logs all stay in your data directory (default ~/.mlx-serve).
- What leaves your Mac: the Telegram API itself, whatever model server you point the bot at, and anonymous usage stats (app launches and menu actions). No chat content, no tokens, no personal data.
Troubleshooting
- "Apple cannot check it for malicious software" — expected: right-click (Control-click) the app in Applications → Open → Open again. One time, then it runs normally.
- The bot doesn't answer. Open Settings → the bot's page: is the token right? Then Defaults → Model → Test the provider. Then check the log (menu bar → Logs, or App tab → Open log).
- Replies are slow or the bot goes quiet. Free-tier providers can stall for a minute+ — raise the API timeout, and add backup models so the bot falls over when the primary throttles.
- Local server not responding. Make sure the server is actually running (mlx-serve, Ollama…) before testing in the Model tab.
- Updates say "up to date" oddly. The check is silent by design — if the manifest is unreachable it reports up to date.
- Something else? Send feedback — every message lands in the developer's Telegram and gets a real answer.
Download Telebot AI · Liking it? Buy me a coffee ☕