Installation

Mercury requires Node.js 20+. Install with npm:

npm i -g @cosmicstack/mercury-agent

Or run without installing:

npx @cosmicstack/mercury-agent

First-Time Setup

Run mercury for the first time. The onboarding wizard asks for:

All config is stored in ~/.mercury/ — nothing in your project directory.

Masked keys

When reconfiguring with mercury doctor, existing API keys are shown masked like sk-x••••4f2a. Press Enter to keep the current value, or paste a new key to replace it.

Starting Mercury

Recommended: mercury up

The easiest way to run Mercury persistently. Installs the system service if needed, starts the daemon, and ensures it's running.

mercury up

If Mercury is already running, mercury up just confirms it and shows the PID. If the service isn't installed yet, it installs it first, then starts the daemon.

Foreground (interactive)

mercury start

Runs in the foreground with a readline prompt. Press Ctrl+C to exit. All conversation happens in your terminal with real-time text streaming and markdown rendering.

Background (daemon)

mercury start -d

Runs in the background. Telegram becomes your primary interface since there's no terminal for input. Logs go to ~/.mercury/daemon.log. The process includes built-in crash recovery with exponential backoff.

When running in daemon mode, you can stop it with:

mercury stop

Verbose logging

Add --verbose to any start command to see debug logs on stderr:

mercury start --verbose

Full Command Reference

Command Description
mercury up Recommended. Install service + start daemon + ensure running
mercury Start the agent (same as mercury start)
mercury start Start in foreground mode
mercury start -d Start in background (daemon mode)
mercury restart Restart a background Mercury process
mercury stop Stop a background Mercury process
mercury logs Show last 100 lines of daemon logs
mercury status Show config, providers, daemon PID, and budget
mercury doctor Reconfigure settings — press Enter to keep current values
mercury setup Re-run the setup wizard (same as doctor)
mercury help Show the full manual (tools, commands, config paths)
mercury service install Install as system service (auto-start on boot)
mercury service uninstall Uninstall the system service
mercury service status Show system service status
mercury --verbose Start with debug logging on stderr

Doctor (Reconfigure)

mercury doctor re-runs the setup wizard with your current values pre-filled. Press Enter on any field to keep it unchanged, or type a new value to replace it.

mercury doctor

In-Chat Commands

Type these during a conversation with Mercury — they work on both CLI and Telegram. They do not consume API tokens.

Command Description
/help Show the full manual
/status Show agent name, provider, budget, and channels
/tools List all currently loaded tools
/skills List installed skills
/stream Toggle Telegram text streaming (on/off)
/stream off Disable streaming — responses arrive as 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

Daemon Mode

Mercury can run in the background so Telegram and scheduled tasks keep working after you close the terminal.

The easy way: mercury up

mercury up

This one command does everything: installs the system service if needed, starts the background daemon, and confirms Mercury is running. If it's already running, it just shows you the PID.

Start in background

mercury start -d

This spawns a detached child process, writes a PID file to ~/.mercury/daemon.pid, and redirects output to ~/.mercury/daemon.log.

Stop

mercury stop

Sends SIGTERM (process.kill on Windows) to the background process and removes the PID file.

Restart

mercury restart

Stops the running daemon (if any) and starts a fresh one. Useful when something isn't working right and you need a clean restart.

View logs

mercury logs

Shows the last 100 lines of ~/.mercury/daemon.log.

Check status

mercury status

Shows whether the daemon is running, its PID, and the log file path.

Crash recovery

When started with --daemon (internal flag used by start -d and system services), Mercury wraps the agent in a watchdog. If it crashes, it restarts automatically with exponential backoff (1s, 1.25s, 1.56s...). After 10 crashes within 60 seconds, it exits to prevent crash loops.

System Service (Auto-Start on Boot)

Install Mercury as a system service so it starts automatically on boot and restarts on crash.

mercury service install

This detects your platform and generates the appropriate service config.

Platform Method Requires Admin Auto-Start Crash Recovery
macOS LaunchAgent plist No On login KeepAlive (restart on crash)
Linux systemd user unit No* On login Restart=on-failure, 5s delay
Windows Task Scheduler (schtasks) No On logon Built-in watchdog

*Linux boot-without-login requires loginctl enable-linger $USER (one-time, needs sudo).

Other service commands

mercury service status
mercury service uninstall

Platform-Specific Guide

mercury service install creates a LaunchAgent at ~/Library/LaunchAgents/com.cosmicstack.mercury.plist.

  • Auto-start: Loads on login via launchctl load
  • Crash recovery: KeepAlive SuccessfulExit = false restarts on crash
  • No sudo needed: User-level LaunchAgent, not system daemon
  • Logs: ~/.mercury/daemon.log and ~/.mercury/daemon-error.log

Manual management

launchctl load ~/Library/LaunchAgents/com.cosmicstack.mercury.plist
launchctl unload ~/Library/LaunchAgents/com.cosmicstack.mercury.plist

mercury service install creates a systemd user unit at ~/.config/systemd/user/mercury.service.

  • Auto-start: Enabled via systemctl --user enable mercury.service
  • Crash recovery: Restart=on-failure with 5s delay
  • No sudo needed: User-level service
  • Boot without login: Run sudo loginctl enable-linger $USER once
  • Logs: ~/.mercury/daemon.log or journalctl --user -u mercury

Manual management

systemctl --user start mercury
systemctl --user status mercury
systemctl --user stop mercury

mercury service install creates a Windows Task Scheduler task named MercuryAgent.

  • Auto-start: Triggers on user logon via schtasks
  • Crash recovery: Built-in watchdog with exponential backoff
  • No admin needed: Runs with limited privileges (/rl limited)
  • Logs: %USERPROFILE%\.mercury\daemon.log

Manual management

schtasks /query /tn "MercuryAgent" /fo list
schtasks /run /tn "MercuryAgent"
schtasks /delete /tn "MercuryAgent" /f

Built-in Tools

Mercury has 21 built-in tools it can use during conversations. These are not CLI commands — the agent decides when to call them.

Filesystem

Tool What it does Parameters
read_file Read file contents path
write_file Write to an existing file path, content
create_file Create a new file (creates parent dirs) path, content
edit_file Search and replace text in a file path, old_string, new_string
list_dir List directory contents path
delete_file Delete a file path
send_file Send file to user (Telegram upload) path

Shell

Tool What it does Parameters
run_command Execute a shell command command
approve_command Permanently approve a command type command (e.g. "curl")

Git

Tool What it does
git_status Working tree status
git_diff Show file changes
git_log Commit history
git_add Stage files
git_commit Create a commit
git_push Push to remote (needs approval)

Web, Skills, Scheduler, System

Tool What it does Category
fetch_url Fetch a URL and return content (HTML stripped) Web
install_skill Install a skill from URL or content Skills
list_skills List installed skills Skills
use_skill Invoke a skill by name Skills
schedule_task Schedule recurring (cron) or one-shot (delay) task Scheduler
list_scheduled_tasks View all scheduled tasks Scheduler
cancel_scheduled_task Cancel a scheduled task Scheduler
budget_status Check token budget usage System

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

Permissions

Mercury has a three-tier permission system for shell commands:

  1. Blocked — Commands like sudo, rm -rf /, mkfs are never executed
  2. Auto-approved — Safe commands like ls, cat, git status run without asking
  3. Pending approval — Unknown commands pause and ask you. Say "always" to permanently approve a command type

Edit ~/.mercury/permissions.yaml to customize. Skill elevation: skills with allowed-tools in their SKILL.md get automatic approval for those tools during execution.

Provider Fallback

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

When a provider fails, Mercury automatically tries the next one. It remembers the last successful provider and starts there on the next request.

Scheduling

Mercury can schedule tasks using cron expressions or one-shot delays.

Recurring tasks

Tell Mercury in conversation:

One-shot delays

Tasks persist to ~/.mercury/schedules.yaml and restore on restart. Responses route back to the channel (CLI or Telegram) where the task was created.

Skills

Skills are markdown-based extensions that live in ~/.mercury/skills/<name>/SKILL.md.

Installing

Tell Mercury in conversation:

Invoking

Scheduling a skill

Skills follow the Agent Skills specification. They get elevated permissions via allowed-tools and are loaded with progressive disclosure to save tokens.