[opensourcedex]

mercury-agent is a free, open source ai interaction & interfaces project written in TypeScript and released under MIT. It has 3,153 GitHub stars, 340 forks and 60 open issues, and was last pushed 29 hours ago. On this registry it ranks #53 of 76 tracked projects in AI Interaction & Interfaces, with 5 head-to-head comparisons available. It gained 15 stars over the last 3 tracked days.

What is mercury-agent?

What it is

mercury-agent is an open-source AI agent written in TypeScript and licensed under MIT. It lives in the AI & Machine Learning / AI Interaction & Interfaces ecosystem, with topics ai-agent, ai-assistant, and llm. The project provides a soul-driven agent that uses tools, keeps memory, and connects through CLI, Telegram, or Web.

The concrete problem it addresses is silent tool use and lost context. Many agents can read files, run commands, and fetch URLs without approval or durable memory. mercury-agent asks before actions, scopes file access, enforces token budgets, and stores memory in SQLite.

Key capabilities

  • Permission-hardened tool use blocks commands such as sudo and rm -rf /, scopes folder read and write access, supports pending approval, and offers Ask Me or Allow All per session.
  • Second Brain memory uses SQLite with FTS5 search, supports 10 memory types, performs auto-extraction, conflict resolution, and auto-consolidation, and learns preferences, goals, and habits without manual entry.
  • Personality is defined through user-owned markdown files, including soul.md, persona.md, taste.md, and heartbeat.md, rather than a corporate wrapper.
  • Token-aware operation enforces a daily budget, switches to auto-concise output above 70%, and exposes /budget to check, reset, or override the limit.
  • Always-on operation runs as a background daemon, auto-restarts on crash, starts on boot, supports cron scheduling, heartbeat monitoring, proactive notifications, CLI and Telegram streaming, and community skills based on the Agent Skills specification.

Who uses it and how

  • Developers and operators install the binary or npm package, run the setup wizard, and choose a permission mode in the Ink TUI before chat starts.
  • Self-hosters run mercury up to install a system service, start the daemon, and use Telegram as the primary channel while CLI output becomes log-only.
  • Users needing persistent context rely on Second Brain memory, Kanban boards, scheduled skills, and heartbeat monitoring for recurring workflows.

Getting started

Install with curl -fsSL https://mercuryagent.sh/install.sh | sh for macOS or Linux, irm https://mercuryagent.sh/install.ps1 | iex for Windows, or npm with npx @cosmicstack/mercury-agent and npm i -g @cosmicstack/mercury-agent. Then run mercury to trigger the setup wizard for name, provider, and optional Telegram configuration.

When to use it — and when not to

Use mercury-agent when a self-hosted AI agent needs permission gates, persistent memory, token budgets, and multi-channel access from CLI, Telegram, or Web. Do not choose it when a long release history or a listed contributor base is required, because the repository is new and shows 60 open issues. A self-hoster must operate the binary or npm package, the background service, the SQLite memory store, and provider or Telegram configuration.

project readme (upstream, from github) — read inline

Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access.

Remembers what matters. Asks before it acts. Runs 24/7 from CLI, Telegram, or Web. 31 built-in tools, Kanban boards, extensible skills, SQLite-backed Second Brain memory.

npm license node

🔖 Current Stable: v1.2.3

English | 简体中文

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 Reject a pending Telegram access request
mercury telegram remove Remove an approved Telegram user
mercury telegram promote Promote a Telegram member to admin
mercury telegram demote 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 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 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                         # c

readme truncated — read the full docs on github

Frequently asked questions

Is mercury-agent free to use?

mercury-agent is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does mercury-agent do?

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

What is mercury-agent written in?

mercury-agent is primarily written in TypeScript. Its source is publicly available at https://github.com/cosmicstack-labs/mercury-agent, and it has 3,153 GitHub stars.