Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI or Telegram.
# Add to your Claude Code skills
git clone https://github.com/cosmicstack-labs/mercury-agentGuides for using ai agents skills like mercury-agent.
Last scanned: 4/28/2026
{
"issues": [
{
"type": "npm-audit",
"message": "node-cron: Vulnerability found",
"severity": "medium"
},
{
"type": "npm-audit",
"message": "uuid: uuid: Missing buffer bounds check in v3/v5/v6 when buf is provided",
"severity": "medium"
}
],
"status": "PASSED",
"scannedAt": "2026-04-28T06:28:52.636Z",
"semgrepRan": false,
"npmAuditRan": true,
"pipAuditRan": true
}No comments yet. Be the first to share your thoughts!
30 days in the Featured rail
One-liner install (no Node.js required) — downloads the latest standalone binary for your OS:
# macOS / Linux
curl -fsSL https://mercuryagent.sh/install.sh | sh
# Windows
irm https://mercuryagent.sh/install.ps1 | iex
Or via npm if you already have Node.js 20+:
npx @cosmicstack/mercury-agent
Or install the npm package globally:
npm i -g @cosmicstack/mercury-agent
mercury
First run triggers the setup wizard (name, provider, optional Telegram). After setup, Mercury opens the Ink TUI startup screen and asks for your permission mode (Ask Me or Allow All) before chat starts.
To reconfigure later (change keys, name, settings):
mercury doctor
mercury doctor --platform
Every AI agent can read files, run commands, and fetch URLs. Most do it silently. Mercury asks first — and remembers what matters.
sudo, rm -rf /, etc. never execute). Folder-level read/write scoping. Pending approval flow. Ask Me or Allow All per session. No surprises.soul.md, persona.md, taste.md, heartbeat.md). No corporate wrapper./budget command to check, reset, or override.Mercury now seeds a default web-search skill on first run in ~/.mercury/skills/web-search/SKILL.md.
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
| 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 for input.
| Command | Description |
|---------|-------------|
| mercury up | Recommended. 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 setup (name, providers, channels, permissions defaults) |
| mercury doctor --platform | Show cross-platform terminal/daemon compatibility diagnostics |
| mercury setup | Re-run the setup wizard |
| mercury status | Show config and daemon status |
| mercury help | Show full manual |
| mercury upgrade | Upgrade to latest version |
| mercury telegram list | List approved and pending Telegram users |
| mercury telegram approve <code\|id> | Approve a pairing code or pending request |
| mercury telegram reject <id> | Reject a pending Telegram access request |
| mercury telegram remove <id> | Remove an approved Telegram user |
| mercury telegram promote <id> | Promote a Telegram member to admin |
| mercury telegram demote <id> | Demote a Telegram admin to member |
| mercury telegram reset | Clear all Telegram access and start fresh |
| 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 |
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 |
| /permissions | Change permission mode (Ask Me / Allow All) |
| /view | Toggle progress view (balanced/detailed) |
| /view balanced | Set compact progress view |
| /view detailed | Set full progress view |
| /code agent <task> | Delegate a coding task to a sub-agent in background |
| /ws exit | Exit workspace IDE mode back to general chat |
| /tasks | List scheduled tasks |
| /memory | View and manage second brain memory |
| /unpair | Telegram: reset all access |
| Category | Tools |
|----------|-------|
| Filesystem | read_file, write_file, create_file, edit_file, list_dir, delete_file, send_file, approve_scope |
| Shell | run_command, cd, approve_command |
| Messaging | send_message |
| 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 |
Mercury can pull community-contributed skills from the registry at skills.mercuryagent.sh (126+ skills, no auth required).
mercury skills search prompt # search the registry
mercury skills browse ai-ml # browse by category
mercury skills view ai-ml/prompt-engineering # render SKILL.md in the terminal
mercury skills view ai-ml/prompt-engineering --web # open the registry page
mercury skills install ai-ml/prompt-engineering # install to ~/.mercury/skills/
mercury skills list # show installed skills
mercury skills update # refresh all installed skills
mercury skills remove ai-ml/prompt-engineering
mercury skills doctor # check install root + registry
Installed skills land at ~/.mercury/skills/<category>/<slug>/SKILL.md and are
picked up by the agent on the next boot — they're treated identically to
built-in skills.
Review before you ship. Skills are community-contributed and unaudited. Run
mercury skills view <id>before installing.
Overrides: --registry <url> (or MERCURY_SKILLS_REGISTRY) for self-hosted
registries, MERCURY_SKILLS_INSTALL_ROOT for an alternate install path,
--json for machine-readable output.
Also installable from:
http://127.0.0.1:6174/skills has a registry installer (paste category/slug) and a URL installer side by side./skills, /skills search <q>, /skills view <id>, /skills install <id> (admin-only). Every result includes the registry URL so you can review before installing.See the Skills reference for the full command surface, frontmatter spec, and