mercury-agent

Name: mercury-agent
Author: cosmicstack-labs

Verified

Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI or Telegram.

2,952stars

315forks

TypeScript

Installation

# Add to your Claude Code skills
git clone https://github.com/cosmicstack-labs/mercury-agent

Getting Started

Guides for using ai agents skills like mercury-agent.

Caveman: Cut Claude Token Use by 65%
How agent-side prompt compression works, when to use it, and when not to.
What is an AI Skills Marketplace?
Definitions, how marketplaces work, and how to choose between them in 2026.
Getting Started with AI Skills

Security ReportVerified

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
}

README.md

Frequently Asked Questions

What is mercury-agent?

mercury-agent is an open-source ai agents skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by cosmicstack-labs. Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI or Telegram. It has 2,952 GitHub stars.

Is mercury-agent safe to use?

Yes. mercury-agent passed SkillsLLM's automated security scan — a dependency vulnerability audit plus prompt-injection heuristics — with no high-severity issues. You can read the full report in the Security Report section on this page.

How do I install mercury-agent?

Clone the repository with "git clone https://github.com/cosmicstack-labs/mercury-agent" and add it to your Claude Code skills directory (see the Installation section above).

What programming language is mercury-agent written in?

mercury-agent is primarily written in TypeScript. It is open-source under cosmicstack-labs on GitHub, so you can review or fork the full source.

Are there alternatives to mercury-agent?

Yes. SkillsLLM lists many other AI Agents skills you can browse and compare side by side. Open the AI Agents category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh mercury-agent against similar tools.

Agentic AI for Beginners

Build your first AI agent from scratch - tool use, ReAct pattern, memory, deployment

41 minBeginner

Comments (0)

to leave a comment.

No comments yet. Be the first to share your thoughts!

Related Skills

superpowers

by obra

An agentic skills framework & software development methodology that works.

234,966

openclaw101 Auto-Empirical-Research-Skills

Quick Start

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

Why Mercury?

Every AI agent can read files, run commands, and fetch URLs. Most do it silently. Mercury asks first — and remembers what matters.

Permission-hardened — Shell blocklist (sudo, rm -rf /, etc. never execute). Folder-level read/write scoping. Pending approval flow. Ask Me or Allow All per session. No surprises.
Second Brain — Persistent, structured memory with SQLite + FTS5 full-text search. 10 memory types, auto-extraction, conflict resolution, auto-consolidation. Mercury learns your preferences, goals, and habits without manual entry.
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.
Live streaming — Real-time token streaming on CLI with cursor-save/restore and markdown re-rendering. Telegram streaming with editable status messages.
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.

Mercury now seeds a default web-search skill on first run in ~/.mercury/skills/web-search/SKILL.md.

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 for input.

CLI Commands

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

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
`/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

Built-in Tools

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`

Installing Skills

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:

Web dashboard — http://127.0.0.1:6174/skills has a registry installer (paste category/slug) and a URL installer side by side.
Telegram — /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