Soul-driven. Token-efficient. Always on.
Your personal AI agent with 21 built-in tools, skill system, multi-channel access, and hardened permissions. Runs 24/7 from your terminal or Telegram.
Not another chatbot. An orchestrator that works for you.
Mercury isn't a blank slate. Its personality is defined by markdown soul files — soul.md, persona.md, taste.md, heartbeat.md — that you control. No corporate wrapper. Your agent, your rules.
Daily token budgets with enforcement. Only soul + persona injected per request (~400 tokens). Skill summaries loaded progressively. Auto-concise mode when budget exceeds 70%.
Cron scheduling, delayed tasks, and a heartbeat system that monitors budget and upcoming tasks. Mercury runs 24/7 and notifies you proactively via Telegram or CLI.
CLI with readline and text streaming. Telegram with typing indicators, HTML formatting, and file uploads. More channels coming: Signal, Discord, Slack, WhatsApp.
Install community skills with a single command. Skills auto-load into context, get elevated permissions, and can be scheduled as recurring tasks. Based on the Agent Skills specification.
Folder-level read/write scoping. Command blocklist (sudo, rm -rf, etc. — never executed). Pending approval flow. Skill elevation with granular allowed-tools. No surprises.
npm i -g @cosmicstack/mercury-agent
Or use npx @cosmicstack/mercury-agent — no install needed.
mercury
First run triggers the onboarding wizard. Enter your name, an API key, and optionally a Telegram bot token. Takes 30 seconds.
mercury start
Mercury wakes up, loads your soul files, restores scheduled tasks, and is live. Start talking.
A real Mercury session — tool calls, streaming, files, and scheduling.
Plus extensible skills, scheduling, and memory.
read_file — Read file contentswrite_file — Write to existing filecreate_file — Create new files (+ dirs)edit_file — Search & replace textlist_dir — List directory contentsdelete_file — Delete a filesend_file — Send file to user (Telegram upload)run_command — Execute shell commandsapprove_command — Permanently approve a commandgit_status — Working tree statusgit_diff — Show file changesgit_log — Commit historygit_add — Stage filesgit_commit — Create commitsgit_push — Push to remotefetch_url — Fetch & strip HTML to textinstall_skill — Install from URL or contentlist_skills — Show installed skillsuse_skill — Invoke a skillschedule_task — Cron or one-shot taskslist_scheduled_tasks — View all taskscancel_scheduled_task — Cancel a taskbudget_status — Check token budgetWe built Mercury because nothing else did all of this.
| Feature | Mercury | Open Interpreter | Claude Code |
|---|---|---|---|
| Soul / Persona System | 4 markdown files | Custom instructions | CLAUDE.md |
| Token Budget Enforcement | Daily budget + override | — | — |
| Multi-Channel (CLI + Telegram) | Both + more coming | All | All |
| Skill System (Agent Skills spec) | Install, invoke, schedule | — | — |
| Cron + Delayed Scheduling | Persisted, auto-restore | — | — |
| Permission Hardening | Blocklist + scope + approval | Confirmation prompts | Permission prompts |
| Proactive Notifications | Heartbeat + task alerts | — | — |
| Auto Fact Extraction | With dedup | — | — |
| Provider Fallback | Auto with last-successful | Manual config | Anthropic only |
| File Upload (Telegram) | Yes — auto type detection | — | — |
| Streaming Output (CLI) | Real-time text stream | Real-time text stream | Real-time text stream |
| Headless / 24-7 Mode | Built-in | — | — |
| Language / Runtime | TypeScript / Node.js | Python | TypeScript / Node.js |
| Open Source | MIT | LGPL-2.1 | Source-available |
Minimal runtime, maximum capability.
npm i -g @cosmicstack/mercury-agent && mercury
That's it. 60 seconds to your own AI agent.