Mercury Agent

---
name: mercury-agent-cosmicstack
description: Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel CLI/Telegram access
triggers:
  - set up mercury agent
  - run mercury ai agent
  - configure mercury telegram bot
  - add mercury agent to my project
  - mercury agent daemon mode
  - schedule tasks with mercury agent
  - extend mercury agent with skills
  - mercury agent token budget
---

# Mercury Agent

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

Mercury is a soul-driven AI agent that runs 24/7 from CLI or Telegram. It features 21 built-in tools, permission-hardened execution (asks before it acts), token budget enforcement, extensible skills, and daemon mode with system service integration.

---

## Installation

```bash
# One-shot via npx (no install required)
npx @cosmicstack/mercury-agent

# Global install
npm i -g @cosmicstack/mercury-agent
mercury

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

---

Key CLI Commands

# === Lifecycle ===
mercury up              # Recommended: install service + start daemon + ensure running
mercury                 # Start in foreground (same as mercury start)
mercury start           # Start in foreground
mercury start -d        # Start in background (daemon mode)
mercury restart         # Restart background process
mercury stop            # Stop background process

# === Diagnostics ===
mercury logs            # View recent daemon logs
mercury status          # Show config and daemon status
mercury doctor          # Reconfigure (Enter to keep current values)
mercury setup           # Re-run setup wizard
mercury help            # Show full manual
mercury --verbose       # Start with debug logging

# === System Service (auto-start on boot) ===
mercury service install    # Install as system service
mercury service uninstall  # Remove system service
mercury service status     # Check service status

---

Configuration

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

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

Example mercury.yaml

providers:
  - name: deepseek
    apiKey: $DEEPSEEK_API_KEY
    model: deepseek-chat
  - name: openai
    apiKey: $OPENAI_API_KEY
    model: gpt-4o-mini
  - name: anthropic
    apiKey: $ANTHROPIC_API_KEY
    model: claude-3-haiku-20240307

channels:
  telegram:
    token: $TELEGRAM_BOT_TOKEN

budget:
  dailyTokens: 100000
  conciseThreshold: 0.7  # Switch to concise mode at 70% usage

agent:
  name: Mercury
  soulDir: ~/.mercury/soul

Example permissions.yaml

filesystem:
  readPaths:
    - ~/projects
    - ~/Documents
  writePaths:
    - ~/projects
  requireApproval: false

shell:
  enabled: true
  requireApproval: true       # Always ask before running shell commands
  blocklist:
    - "sudo"
    - "rm -rf /"
    - "dd if="
    - "mkfs"

web:
  fetchEnabled: true
  requireApproval: false

---

In-Chat Commands

These work in both CLI and Telegram without consuming API tokens:

/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 delivery)
/budget                 Show token budget status
/budget override        Override budget limit for one request
/budget reset           Reset usage counter to zero
/budget set 50000       Change daily token budget to 50,000 tokens

---

Built-in Tools Reference

Category	Tool Names
Filesystem	read_file, write_file, create_file, edit_file, list_dir, delete_file, send_file
Shell	run_command, approve_command
Git	git_status, git_diff, git_log, git_add, git_commit, git_push
Web	fetch_url
Skills	install_skill, list_skills, use_skill
Scheduler	schedule_task, list_scheduled_tasks, cancel_scheduled_task
System	budget_status

---

Soul / Personality Files

Mercury's personality is defined by markdown files you own:

~/.mercury/soul/
  soul.md        # Core identity and values
  persona.md     # How Mercury presents itself
  taste.md       # Aesthetic preferences, communication style
  heartbeat.md   # Proactive behavior and background monitoring rules

Example soul.md

# Soul

You are Mercury — a precise, thoughtful assistant who values clarity over verbosity.
You ask before acting on anything that could have side effects.
You prefer surgical edits over rewrites.
You treat the user's time as precious.

Example heartbeat.md

# Heartbeat

Every hour, check:
- Are there any failing CI pipelines in ~/projects?
- Are there unread Telegram messages that need follow-up?

Notify proactively only if something requires attention.

---

Skill System

Mercury uses the Agent Skills specification.

# Install a community skill (ask Mercury directly)
# In chat: "install the github-summary skill"
# Mercury calls: install_skill({ name: "github-summary" })

# List installed skills
# In chat: "/skills"

# Use a skill
# In chat: "use the github-summary skill on cosmicstack-labs/mercury-agent"

Writing a Custom Skill

Skills are SKILL.md files with YAML frontmatter:

---
name: daily-standup
description: Generate a daily standup report from git activity
version: 1.0.0
allowed-tools:
  - git_log
  - git_diff
  - run_command
triggers:
  - generate standup
  - what did I do today
  - daily report
---

# Daily Standup Skill

Fetch today's git commits across all repos in ~/projects and format
a standup report: what was done, what's in progress, any blockers.

Steps:
1. `list_dir` on ~/projects to find repos
2. `git_log --since=yesterday --author=$(git config user.email)` per repo
3. Summarize changes grouped by repo
4. Output in standup format: Done / Doing / Blockers

---

Scheduler (Cron + One-Shot)

# In chat — schedule a recurring task:
"Every day at 9am, summarize my GitHub notifications"
# Mercury calls: schedule_task({ cron: "0 9 * * *", task: "..." })

# One-shot delayed task:
"In 15 minutes, remind me to review the PR"
# Mercury calls: schedule_task({ delay_seconds: 900, task: "..." })

# List scheduled tasks:
/tools → then ask "what tasks are scheduled?"
# Or: schedule_task → list_scheduled_tasks

# Cancel a task:
"Cancel the daily standup task"
# Mercury calls: cancel_scheduled_task({ id: "..." })

Tasks persist in ~/.mercury/schedules.yaml and survive restarts. Responses route back to the channel where the task was created.

---

Provider Fallback Pattern

Mercury tries providers in order and falls back automatically on failure:

# mercury.yaml — order matters, first = primary
providers:
  - name: deepseek       # Primary: cost-effective
    apiKey: $DEEPSEEK_API_KEY
    model: deepseek-chat
  - name: openai         # Fallback 1
    apiKey: $OPENAI_API_KEY
    model: gpt-4o-mini
  - name: anthropic      # Fallback 2
    apiKey: $ANTHROPIC_API_KEY
    model: claude-3-haiku-20240307

Set environment variables before starting:

export DEEPSEEK_API_KEY=your_key_here
export OPENAI_API_KEY=your_key_here
export ANTHROPIC_API_KEY=your_key_here
export TELEGRAM_BOT_TOKEN=your_token_here

mercury up

---

Telegram Setup

1. Create a bot via @BotFather → copy token
2. Run mercury doctor and paste the token when prompted
3. Run mercury up to start daemon
4. Open your bot in Telegram and start chatting

Telegram features: HTML formatting, file uploads (photos, audio, video, documents), typing indicators, streaming toggle, all / commands.

---

Daemon Mode & System Services

# Start persistent daemon (installs service on first run)
mercury up

# Platform-specific service locations:
# macOS:   ~/Library/LaunchAgents/org.cosmicstack.mercury.plist
# Linux:   ~/.config/systemd/user/mercury.service
# Windows: Task Scheduler entry "MercuryAgent"

# Check what's running
mercury status

# View live logs
mercury logs

# Crash recovery is automatic:
# - Watchdog detects crash → restarts with exponential backoff
# - Max 10 restarts/minute before cooldown

In daemon mode, Telegram is the primary interaction channel. CLI becomes log-only (no terminal input).

---

Architecture Notes

• TypeScript + Node.js 20+ — ESM modules, built with tsup, zero native dependencies
• Vercel AI SDK v4 — generateText + streamText, 10-step agentic loop
• grammY — Telegram bot framework
• Flat-file persistence — No database; YAML + JSON in ~/.mercury/
• Daemon manager — Background spawn + PID file + watchdog

---

Common Patterns

Pattern: Scoped file access for a project

# permissions.yaml
filesystem:
  readPaths:
    - ~/projects/my-app
  writePaths:
    - ~/projects/my-app/src
  requireApproval: false

Then in chat: "Refactor all TypeScript files in src/ to use async/await" — Mercury reads freely, writes to src/, asks before touching anything outside.

Pattern: Shell with approval for destructive ops

# permissions.yaml
shell:
  enabled: true
  requireApproval: true
  blocklist:
    - "sudo"
    - "rm -rf"
    - "DROP TABLE"
    - "> /dev/sda"

Mercury will propose the command and wait for your "yes" before executing.

Pattern: Daily digest via heartbeat

# ~/.mercury/soul/heartbeat.md

Every day at 8am:
- Run `git log --since=yesterday` across ~/projects
- Fetch my top 3 GitHub notifications
- Send a digest to Telegram summarizing overnight activity

Pattern: Override budget for a large task

# In chat when over budget:
/budget override
# Then immediately send your large request — budget is bypassed for one turn

---

Troubleshooting

Problem	Solution
mercury: command not found	Run npm i -g @cosmicstack/mercury-agent or use npx
Agent not responding	mercury status → mercury restart
Wrong API key	mercury doctor → update key → Enter to keep others
Telegram bot silent	Check token in mercury.yaml, ensure mercury up is running
Over token budget	/budget reset or /budget override for one request
Permission denied on file	Add path to readPaths/writePaths in permissions.yaml
Skill not found	Ask Mercury: "install the X skill" — it calls install_skill
Service not starting on boot	mercury service install then check mercury service status
Daemon crash loop	mercury logs to diagnose, fix config, then mercury up
Provider errors	Check env vars are exported; add fallback provider in mercury.yaml

Debug mode

mercury --verbose       # Prints full tool call traces, provider selection, token counts
mercury logs            # View daemon log file (last N lines)

Reset everything

mercury stop
rm -rf ~/.mercury
mercury setup           # Fresh wizard

---

License

MIT © Cosmic Stack

Disclaimer: This is AI — it can break sometimes. Use at your own risk.