mercury-agent

Home > Security > mercury-agent

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

ai-agent ai-assistant llm typescript

Why this rank:Strong adoptionRecent releaseHealthy release cadence

Description

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

README

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

Runs 24/7 from CLI or Telegram. 21 built-in tools. Extensible skills. Asks before it acts.

Quick Start

npx @cosmicstack/mercury-agent

Or install globally:

npm i -g @cosmicstack/mercury-agent
mercury

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

To reconfigure later (change keys, name, settings):

mercury doctor

Why Mercury?

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

Permission-hardened — Shell blocklist (sudo, rm -rf /, etc. never execute). Folder-level read/write scoping. Pending approval flow. Skill elevation with granular allowed-tools. No surprises.
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.
Multi-channel — CLI with real-time streaming. Telegram with HTML formatting, file uploads, and typing indicators.
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.

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 (Enter to keep current values)
`mercury setup`	Re-run the setup wizard
`mercury status`	Show config and daemon status
`mercury help`	Show full manual
`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

Built-in Tools

Category	Tools
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`

Channels

Channel	Features
CLI	Readline prompt, real-time text streaming, markdown rendering, file display
Telegram	HTML formatting, file uploads (photos, audio, video, documents), typing indicators, `/budget` commands

Scheduler

Recurring: schedule_task with cron expressions (0 9 * * * for daily at 9am)
One-shot: schedule_task with delay_seconds (e.g. 15 seconds)
Tasks persist to ~/.mercury/schedules.yaml and restore on restart
Responses route back to the channel where the task was created

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

Provider Fallback

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

DeepSeek — default, cost-effective
OpenAI — GPT-4o-mini and others
Anthropic — Claude and others

Architecture

TypeScript + Node.js 20+ — ESM, tsup build, zero native dependencies
Vercel AI SDK v4 — generateText + streamText, 10-step agentic loop, provider fallback
grammY — Telegram bot with typing indicators and file uploads
Flat-file persistence — No database. YAML + JSON in ~/.mercury/
Daemon manager — Background spawn + PID file + watchdog crash recovery
System services — macOS LaunchAgent, Linux systemd, Windows Task Scheduler

License

Disclaimer

This is AI - it can break sometimes, please use this at your own risk.

Suggestions and Contributions

For suggestions, contributions, or any inquiries, please reach out to us at support@cosmicstack.org.

Release History

Version	Changes	Urgency	Date
v1.4.2	## ☿ Mercury Agent v1.4.2 Web search finds things again, with no key and with any model, and the research prompt now asks only when you actually want a research article. ### Web search - Three sources that answer. `web_search` asks [Parallel's public search](https://search.parallel.ai/mcp) first (keyless, built for agents, about a second, with excerpts and dates), then DuckDuckGo's html page, then its lite page. Bing's web feed, which had started returning unrelated pages, and the engines	High	10/24/2026
v1.4.0	## ☿ Mercury Agent v1.4.0 — Pluggy Mercury Mercury gets plugins. Install what you need with `/plugins install <id>`: each plugin runs in its own process, comes from a checksum-verified catalog, and asks for exactly the access it needs. Two official plugins ship today on macOS, Windows and Linux: - WhatsApp: chat with Mercury, and talk to it on voice calls. It can call you, or listen to you on the go. - Optimus: Mercury uses your computer. It sees the screen, moves, scrolls and types li	High	10/23/2026
v1.3.8	- No more cyan bar beside a streaming reply. The attach TUI (what `mercury` opens) drew the live reply with a cyan `│` strip that disappeared once the reply settled. The live tail now renders exactly like the settled block — same `MERCURY:` header, indent and markdown. - Working/step indicators animate. The attach TUI showed a frozen `⠋ working…` and static `→` steps; they now run on the shared 100 ms ticker like the main TUI.	High	10/12/2026
v1.3.2	- Launch pad on `mercury`. The default launch attaches to the daemon (ADR-024) and the attach screen had dropped the launch pad — the wordmark, provider/skills/web/budget rows and tip the main TUI opens with. It is back, fed by real runtime state, above the session picker. - `/stop` then a command. `/stop` aborts asynchronously; a slash command typed before the turn finished unwinding was answered "Agent is busy…". The launcher now waits for the stop to complete (up to 5 s) and runs the	High	10/11/2026
v1.3.0	# Release v1.3.0 ## ☿ Mercury Agent v1.3.0 — Mercury Bots Mercury stops being one agent and becomes a fleet. This release introduces Mercury Bots — persistent, persona-scoped agents that run outside your conversation: each with its own persona, private sandbox workspace, skill library, permission scopes, token budget, and a durable job queue. Onboard a researcher, a writer, a watchtower — chain them into multi-level fleets where a lead bot recruits and manages its own crew. They work	High	10/7/2026
v1.2.7	The release where one key reaches 350+ models. AI/ML API joins Mercury as a first-class provider, alongside two quiet reliability fixes from the community. ## Highlights ### AI/ML API provider — 350+ chat models on one key - New named provider (`AIMLAPI_API_KEY`) with the full setup flow: `mercury setup` validates your key by fetching its live chat catalogue and offers a model pick (recommendation: `anthropic/claude-sonnet-4.6`) - Model discovery is surface-aware: AI/ML API lists chat, ima	High	9/14/2026
v1.2.5	The release where 1.2.4's promises actually ship. The squash merge into main silently dropped the newest Release/1.23 work — the native-scrollback TUI, the flicker fix, the chat delivery contract, and even `mercury attach`'s command registration — so the shipped package had the code but not the features. All of it is restored and verified here. ## Highlights ### Native scrollback — wheel scroll and copy-paste are the terminal's own - Finalized messages print once into the terminal's na	High	9/10/2026
v1.2.3	The release where Mercury Code stops dying and starts telling the truth. The completion pipeline was rebuilt around a completion contract: every task ends in a verdict — a verified completion with evidence, or an honest pause that names its blocker and resumes. Tasks can no longer fake success, die silently, or loop forever. ## Highlights ### Completion contract - Every task end is classified (`text-stop` / `steps-exhausted` / `interrupted` / `truncated` / `aborted`) — budget exhaustion is	High	9/8/2026
v1.2.2	## Mercury Agent v1.2.2 ### Highlights - Mercury Cloud — Terminal pairing flow, JWT + refresh token auth, long-lived agent API key for self-recovery, Cloud WebSocket runtime status tracking, and shared memory pool search. - Cross-platform CI fixes — Windows file-mode and path-join fixes, Termux (Android) support for optional `better-sqlite3`, and lazy-loading native addons so `--help` works without them. - Runtime activation hardening — `activateCloudRuntime` restored as the single	High	8/10/2026
v1.1.13	Three new channels — Discord, Slack, and Signal — bring Mercury to where you already are, with end-to-end encryption, organization access models, and real-time streaming. Plus long-running loop fixes, CLI heartbeat improvements, and crash recovery.	High	6/18/2026
v1.1.12	# Release v1.1.12 ## ☿ Mercury Agent v1.1.12 — Daemon hotfix Hotfix on top of [v1.1.11](https://github.com/cosmicstack-labs/mercury-agent/releases/tag/v1.1.11). The standalone single-file binaries introduced in 1.1.11 could not start in the background — which meant Telegram never came online for anyone who installed Mercury via the one-line installer (the recommended path for web servers). ### What Was Broken `src/cli/daemon.ts` spawned the daemon child as: ``` spawn(process.execPath, [proc	High	6/1/2026
v1.1.11	# Release v1.1.11 ## ☿ Mercury Agent v1.1.11 Token Saver Mode, full Skill System, and standalone binaries. The biggest release since the 1.1.x line began — Mercury now ships as a single executable on every major OS, learns new tricks via user-defined skills, and gives you a live status bar with token usage at the bottom of every session. ### What's New - Token Saver Mode (#69) — opt-in mode that aggressively trims session context so long-running agents don't bleed tokens. Pairs with	High	5/31/2026
v1.1.9	Release `1.1.9` introduces the Mercury Web Dashboard — a full React SPA at `localhost:6174` — alongside a persistent Kanban board system, an in-browser Workspace IDE with Git and AI commit messages, a dual-layer (conscious + subconscious) Second Brain, intelligent skill batching, and a cross-platform build pipeline. > Note: Version `1.1.8` was published briefly and then unpublished before reaching wide distribution due to a dependency-tree issue (a transitive `next` dep	High	5/19/2026
v1.1.6	Mercury v1.1.6 is a substantial CLI/TUI and workflow upgrade focused on reliability, long-running task handling, coding workspace ergonomics, and clearer operator controls. ## What’s happening in this release This release improves how Mercury behaves as a daily driver in terminal-first workflows: - better startup + input handling stability - IDE-like workspace flow for coding sessions - stronger background execution for long tasks/sub-agents - richer Spotify control surface in CLI - session-lev	High	5/6/2026
v1.1.5	## What's Changed ### Fixed: Onboarding no longer blocks users without Ollama The onboarding flow had a critical UX problem: if a user didn't have Ollama running locally or an API key handy, they'd get stuck in infinite loops with no way to skip. This release makes onboarding smooth and forgiving. Key changes: 1. Ollama Local is now skippable — If Ollama isn't running, you can skip it entirely or manually enter a model name. No more infinite retry loops. 2. **All provider setups all	High	5/2/2026
v1.1.0	## What's Changed ### DeepSeek v4 Compatibility - New dedicated DeepSeek provider (`@ai-sdk/deepseek`) — replaces the OpenAI-compatible workaround with a proper SDK integration that correctly handles DeepSeek's reasoning mode (`deepseek-reasoner`). - Thinking mode support — DeepSeek reasoner models now pass `thinking: { type: 'enabled' }` via `providerOptions`, ensuring `reasoning_content` is included in the response and round-tripped back to the API (fixes the `The reasoning_content in	High	4/26/2026
v0.4.0	## ☿ Mercury Agent v0.4.0 Persistent working directory, Ollama support, Telegram messaging, and more. ### Highlights - `cd` tool — Change directories persistently. All subsequent file, shell, and git operations use the new working directory. No more lost `cd` between commands. - Relative path support — All 8 filesystem tools and all 6 git tools now resolve relative paths against the current working directory instead of `process.cwd()`. - `run_command` learns `cd` — Running `cd	High	4/22/2026
v0.3.4	## Changes ### Simplified GitHub Setup (3 steps instead of 4) - Removed the email field — `Co-authored-by: Mercury <mercury@cosmicstack.org>` is now the default. No need to ask users for an email. - Default co-author email — `mercury@cosmicstack.org` is hardcoded as the default in config. Users can override via `GITHUB_EMAIL` env var if they want, but 99% won't need to. - Numbered prompts — Setup now shows clear step numbers (1. username, 2. PAT, 3. default repo) - **URL parsing fo	High	4/21/2026
v0.3.2	## Bug Fixes ### Critical: GitHub tools now actually make API calls The previous implementation had three bugs causing the LLM to fabricate GitHub API responses: 1. `getCurrentRepo()` was required but failed in daemon/Telegram mode — When Mercury isn't running inside a git repo directory (daemon mode, Telegram), the auto-detection of `owner/repo` from `git remote` failed silently. The LLM then fabricated success responses instead of reporting errors. 2. **`github_api` used `checkShellCom	High	4/21/2026
v0.3.1	## Bug Fixes - GITHUB_TOKEN now loads from `~/.mercury/.env` — previously, dotenv only read from the project directory, so tokens saved during `mercury doctor` were never picked up. Now both `.env` locations are loaded. - GitHub tools now appear in the LLM's system prompt — when `GITHUB_TOKEN` is configured, the agent tells the LLM it can create PRs, review PRs, manage issues, and use the GitHub API. Without this, the LLM didn't know GitHub tools existed. Full Changelog: https://gi	High	4/21/2026
v0.3.0	## What's New ### GitHub Companion Mercury now connects to GitHub as your coding companion — co-authored commits, PR management, issue tracking, and full API access. Co-Authored Commits Every Mercury-assisted `git_commit` now automatically appends `Co-authored-by: Mercury <mercury@cosmicstack.org>`. Mercury's avatar appears alongside yours in GitHub commit history. 5 New GitHub Tools (registered only when `GITHUB_TOKEN` is set): - `create_pr` — Create pull requests with title, body,	High	4/21/2026
v0.2.7	## What's Changed - Removed `figlet` dependency — ASCII art banner is now hardcoded (no runtime dep) - Eliminates the `commander@14` transitive dependency warning from figlet - No more `EBADENGINE` warnings on Node 18 Full Changelog: https://github.com/cosmicstack-labs/mercury-agent/compare/v0.2.6...v0.2.7	High	4/21/2026
v0.2.6	## What's Changed ### Scope Approval Fix - `checkFsAccess` no longer auto-blocks with a hidden prompt — returns denial immediately so the LLM can call `approve_scope` explicitly - `approve_scope` tool: Allow = session-only temp scope, Always = persists to permissions.yaml - Shell path traversal denials now reference `approve_scope` tool in error message ### Node 18 Compatibility - Removed `@grammyjs/stream` dependency (required Node >=22, wasn't used) - Downgraded `commander` from v14	High	4/21/2026
v0.2.4	## What's Changed - Version now read from `package.json` at runtime via `import.meta` — no more manual version bumps in source - Ensures `mercury --version` and banner always match the published npm version Full Changelog: https://github.com/cosmicstack-labs/mercury-agent/compare/v0.2.3...v0.2.4	High	4/21/2026
v0.2.3	## What's Changed - Version strings in banner and CLI are now read dynamically from package.json — no more hardcoding - Previous release (v0.2.2) showed "v0.2.1" in the banner due to hardcoded strings Full Changelog: https://github.com/cosmicstack-labs/mercury-agent/compare/v0.2.2...v0.2.3	High	4/21/2026
v0.2.5	## What's New ### Interactive Scope Approval with `approve_scope` Tool When Mercury hits a filesystem permission denial, it no longer tells the user to manually edit config files. Instead: 1. Automatic prompt: The permission system now automatically asks the user via inline keyboard (Telegram) or readline (CLI) when a file access is outside allowed scopes 2. `approve_scope` tool: If the initial prompt was missed or denied, the LLM can now use the `approve_scope` tool to request access	High	4/21/2026
v0.2.2	## What's New ### Telegram Inline Keyboard for Permission Approvals Shell commands and file operations that need approval on Telegram now show inline keyboard buttons (Allow / Always / Deny) instead of requiring text responses. This makes the permission flow on Telegram much more intuitive and mobile-friendly. - Allow — approves this one request - Always — approves this command permanently (persists to permissions.yaml) - Deny — blocks the command ### Other Changes - Build +	High	4/21/2026
v0.2.1	## Mercury v0.2.1 Bug fix release for Windows users. ### Fixes - File permission denied on Windows — `findScope()` used hardcoded `/` as path separator. On Windows, paths use `\`, so files inside subdirectories of an allowed scope were incorrectly denied. Now uses `path.sep` (platform-native separator). Zero impact on macOS/Linux. - Windows absolute paths bypassed cwd check — `hasPathBeyondCwd()` only recognized Unix-style paths (`/usr`, `~/`, `../`). Windows drive letters (`C:\`) and	High	4/21/2026
v0.2.0	## Mercury v0.2.0 The biggest feature drop since launch. Mercury now runs 24/7 as a background daemon on every platform — no PM2, no forever, no NSSM required. ### Daemon Mode - `mercury start -d` — run in background with PID file + log redirect - `mercury stop` / `mercury restart` — process lifecycle management - Built-in watchdog: auto-restarts on crash with exponential backoff (max 10 restarts/60s) ### `mercury up` One command to make Mercury persistent. Installs the system service, starts	High	4/20/2026

Dependencies & License Audit

Loading dependencies...

Similar Packages

TomoriBotA highly customizable personal AI assistant for Discord featuring smart agentic AI features such as memory, personas, tool usage, and more! ｜長期記憶やペルソナ、ツール連携を完備。次世代の「自律型AIエージェント」Discordボット！v0.8.1.00

karpathy-llm-wikiThe Self-Growing Karpathy LLM Wiki — grown by an AI agent yoyo from Karpathy's founding promptmain@2026-10-25

serverlessclawOfficial ServerlessClaw: The authoritative autonomous AI agent swarm for AWS. Zero idle cost, self-evolving, and infinite scale. Powered by OpenClaw.main@2026-10-25

openclaw-engramLocal-first memory plugin for OpenClaw AI agents. LLM-powered extraction, plain markdown storage, hybrid search via QMD. Gives agents persistent long-term memory across conversations.v10.0.21

remnicLocal-first memory plugin for OpenClaw AI agents. LLM-powered extraction, plain markdown storage, hybrid search via QMD. Gives agents persistent long-term memory across conversations.v10.0.21

More in Security

vm0the easiest way to run natural language-described workflows automatically

cuaOpen-source infrastructure for Computer-Use Agents. Sandboxes, SDKs, and benchmarks to train and evaluate AI agents that can control full desktops (macOS, Linux, Windows).

azure-ai-inferenceMicrosoft Azure AI Inference Client Library for Python

azure-appconfigurationMicrosoft App Configuration Data Client Library for Python