Mercury: A permission-hardened, persistent AI agent for CLI and Telegram

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.

Quick Start

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

Why Mercury?

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.

Daemon Mode

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.

Other daemon commands

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).

System Service (auto-start on boot)

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

mercury service install

| Platform | Method | Requires Admin | |----------|--------|---------------| | macOS | LaunchAgent (~/Library/LaunchAgents/) | No | | Linux | systemd user unit (~/.config/systemd/user/) | No (linger for boot) | | Windows | Task Scheduler (schtasks) | No |

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 fo