Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access.

Runs 24/7 from CLI or Telegram. 21 built-in tools. Extensible skills. Asks before it acts.

npx @cosmicstack/mercury-agent

Or install globally:

npm i -g @cosmicstack/mercury-agent
mercury

First run triggers the setup wizard — enter your name, an API key, and optionally a Telegram bot token. Takes 30 seconds.

To reconfigure later (change keys, name, settings):

mercury doctor

Every AI agent can read files, run commands, and fetch URLs. Most do it silently. Mercury asks first.

• Permission-hardened — Shell blocklist (sudo, rm -rf /, etc. never execute). Folder-level read/write scoping. Pending approval flow. Skill elevation with granular allowed-tools. No surprises.
• Soul-driven — Personality defined by markdown files you own (soul.md, persona.md, taste.md, heartbeat.md). No corporate wrapper.
• Token-aware — Daily budget enforcement. Auto-concise when over 70%. /budget command to check, reset, or override.
• Multi-channel — CLI with real-time streaming. Telegram with HTML formatting, file uploads, and typing indicators.
• Always on — Run as a background daemon on any OS. Auto-restarts on crash. Starts on boot. Cron scheduling, heartbeat monitoring, and proactive notifications.
• Extensible — Install community skills with a single command. Schedule skills as recurring tasks. Based on the Agent Skills specification.

One command to make Mercury persistent:

mercury up

This installs the system service (if not installed), starts the background daemon, and ensures Mercury is running. Use this as your go-to command.

If Mercury is already running, mercury up just confirms it and shows the PID.

mercury restart      # Restart the background process
mercury stop         # Stop the background process
mercury start -d     # Start in background (without service install)
mercury logs         # View recent daemon logs
mercury status       # Show if daemon is running

Daemon mode includes built-in crash recovery — if the process crashes, it restarts automatically with exponential backoff (up to 10 restarts per minute).

mercury up installs this automatically. You can also manage it directly:

mercury service install

mercury service status     # Check if service is running
mercury service uninstall  # Remove the system service

In daemon mode, Telegram becomes your primary channel — CLI is log-only since there's no terminal for input.

Type these during a conversation — they don't consume API tokens. Work on both CLI and Telegram.

• Recurring: schedule_task with cron expressions (0 9 * * * for daily at 9am)
• One-shot: schedule_task with delay_seconds (e.g. 15 seconds)
• Tasks persist to ~/.mercury/schedules.yaml and restore on restart
• Responses route back to the channel where the task was created

All runtime data lives in ~/.mercury/ — not in your project directory.

Configure multiple LLM providers. Mercury tries them in order and falls back automatically:

• DeepSeek — default, cost-effective
• OpenAI — GPT-4o-mini and others
• Anthropic — Claude and others

• TypeScript + Node.js 20+ — ESM, tsup build, zero native dependencies
• Vercel AI SDK v4 — generateText + streamText, 10-step agentic loop, provider fallback
• grammY — Telegram bot with typing indicators and file uploads
• Flat-file persistence — No database. YAML + JSON in ~/.mercury/
• Daemon manager — Background spawn + PID file + watchdog crash recovery
• System services — macOS LaunchAgent, Linux systemd, Windows Task Scheduler

MIT © Cosmic Stack

This is AI - it can break sometimes, please use this at your own risk.

For suggestions, contributions, or any inquiries, please reach out to us at support@cosmicstack.org.