mercury-agent

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

• undefinedPermission-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.
• undefinedSoul-driven — Personality defined by markdown files you own (soul.md, persona.md, taste.md, heartbeat.md). No corporate wrapper.
• undefinedToken-aware — Daily budget enforcement. Auto-concise when over 70%. /budget command to check, reset, or override.
• undefinedMulti-channel — CLI with real-time streaming. Telegram with HTML formatting, file uploads, and typing indicators.
• undefinedAlways on — Run as a background daemon on any OS. Auto-restarts on crash. Starts on boot. Cron scheduling, heartbeat monitoring, and proactive notifications.
• undefinedExtensible — Install community skills with a single command. Schedule skills as recurring tasks. Based on the Agent Skills specification.

Daemon Mode

undefinedOne command to make Mercury persistent:undefined

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
undefinedmacOSundefined	LaunchAgent (~/Library/LaunchAgents/)	No
undefinedLinuxundefined	systemd user unit (~/.config/systemd/user/)	No (linger for boot)
undefinedWindowsundefined	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 for input.

CLI Commands

Command	Description
mercury up	undefinedRecommended. Install service + start daemon + ensure running
mercury	Start the agent (same as mercury start)
mercury start	Start in foreground
mercury start -d	Start in background (daemon mode)
mercury restart	Restart the background process
mercury stop	Stop a background process
mercury logs	View recent daemon logs
mercury doctor	Reconfigure (Enter to keep current values)
mercury setup	Re-run the setup wizard
mercury status	Show config and daemon status
mercury help	Show full manual
mercury service install	Install as system service (auto-start on boot)
mercury service uninstall	Uninstall system service
mercury service status	Show system service status
mercury --verbose	Start with debug logging

In-Chat Commands

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

Command	Description
/help	Show the full manual
/status	Show agent config, budget, and usage
/tools	List all loaded tools
/skills	List installed skills
/stream	Toggle Telegram text streaming
/stream off	Disable streaming (single message)
/budget	Show token budget status
/budget override	Override budget for one request
/budget reset	Reset usage to zero
/budget set <n>	Change daily token budget

Built-in Tools

Category	Tools
undefinedFilesystemundefined	read_file, write_file, create_file, edit_file, list_dir, delete_file, send_file
undefinedShellundefined	run_command, approve_command
undefinedGitundefined	git_status, git_diff, git_log, git_add, git_commit, git_push
undefinedWebundefined	fetch_url
undefinedSkillsundefined	install_skill, list_skills, use_skill
undefinedSchedulerundefined	schedule_task, list_scheduled_tasks, cancel_scheduled_task
undefinedSystemundefined	budget_status

Channels

Channel	Features
undefinedCLIundefined	Readline prompt, real-time text streaming, markdown rendering, file display
undefinedTelegramundefined	HTML formatting, file uploads (photos, audio, video, documents), typing indicators, /budget commands

Scheduler

• undefinedRecurring: schedule_task with cron expressions (0 9 * * * for daily at 9am)
• undefinedOne-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

Configuration

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

Path	Purpose
~/.mercury/mercury.yaml	Main config (providers, channels, budget)
~/.mercury/soul/*.md	Agent personality (soul, persona, taste, heartbeat)
~/.mercury/permissions.yaml	Capabilities and approval rules
~/.mercury/skills/	Installed skills
~/.mercury/schedules.yaml	Scheduled tasks
~/.mercury/token-usage.json	Daily token usage tracking
~/.mercury/memory/	Short-term, long-term, episodic memory
~/.mercury/daemon.pid	Background process PID
~/.mercury/daemon.log	Daemon mode logs

Provider Fallback

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

• undefinedDeepSeek — default, cost-effective
• undefinedOpenAI — GPT-4o-mini and others
• undefinedAnthropic — Claude and others

Architecture

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

License

MIT © Cosmic Stack

---

Disclaimer

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

---

Suggestions and Contributions

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