mercury-agent

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, Discord, Slack, Signal, or Web. ~50 built-in tools, Mercury Code, the Mercury Bots fleet, Kanban boards, extensible skills, SQLite-backed Second Brain memory.

🔖 Current Stable: v1.3.2 — Steady Mercury

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 22+ (required since 1.3.1 — binaries carry their own runtime):

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 channels). 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 /, swapped-flag rm -fr variants, and friends never execute). Folder-level read/write scoping per channel, per sender role. Pending approval flow with arrow-key pickers in the TUI. Ask Me or Allow All per session. Members on shared channels can't install skills — escalation paths stay with admins.
• 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. Token Saver Mode engages automatically under pressure and trims context (tuned via /saver). /budget to check, reset, or override.
• Mercury Code — A full-screen, repo-aware coding environment (mercury code or /code): plan + execute in one AUTO flow, live plan checklist, background sub-agents, /code agent delegation, honest completion banners with per-file diffs.
• Mercury Bots fleet — Persistent specialist bots with their own persona, provider, scoped memory, and permissions. Onboard and steer from the TUI (/bots), the web cockpit, the HTTP API, or chat. They run fail-closed, never block the main agent, and hand work back through a deliverables inbox.
• Five messaging channels — CLI, Telegram, Discord, Slack, and Signal (end-to-end encrypted via signal-cli).
• Always on — Run as a background daemon on any OS. Auto-restarts on crash with a crash-flag report. Starts on boot. Cron scheduling, heartbeat monitoring, and proactive notifications.
• Extensible — Install community skills from the registry with a single command. Schedule skills as recurring tasks. Based on the Agent Skills specification. A default web-search skill is seeded on first run in ~/.mercury/skills/web-search/SKILL.md.

New in this line: Mercury Code (completion contract, AUTO mode, live plan checklists, stall watchdog, compact-on-pressure, live thinking preview, wheel-scrollable transcripts), Discord / Slack / Signal channels, the Mercury Bots fleet with a web cockpit, Mercury Cloud pairing, SSRF guards on outbound fetches, randomized initial web-dashboard passwords, and secret redaction in logs.

Channels

All channels share one tool registry, permission system, and Second Brain — configure more than one and they route notifications by priority (Signal → Telegram → Discord → Slack → CLI).

CLI Shortcuts

• Ctrl+P → switch to Plan mode · Ctrl+X → Execute mode · Esc/Ctrl+Q → exit workspace · Ctrl+V → toggle progress view (/view fallback)
• /menu opens the arrow-key command picker.

Spotify in the TUI

Keyboard shortcuts: N next, P previous, +/- volume, Z now playing. Inline album art is safe-gated: enable with MERCURY_SPOTIFY_ART=1; renders only in local iTerm sessions and falls back to text-only elsewhere.

Mercury Code

Mercury Code is Mercury's full-screen programming environment — it turns the agent into a senior engineer embedded in your repo.

mercury code [dir]    # open Mercury Code in a directory
/code                 # enter Mercury Code from the running agent

• AUTO mode (default) — plan and build in one flow. Large/consequential changes get one confirmation before code is written; everything else just happens.
• Completion contract — every task ends in a verdict: verified completion (evidence-gated: a build/test/typecheck must actually run) or an honest pause naming its blocker. Tasks can't fake success or die silently.
• Live plan checklist — every step visible as pending → active → done.
• Background delegation — /code agent hands coding work to a sub-agent while you keep chatting.
• Guardrails — stall watchdog (3 min → pulse, 8 min → resume), compact-on-pressure memory handling, write-truncation recovery, provider fallback mid-task.
• Workspace IDE — /ws to browse files, stage, commit (Mercury co-authors), and undo changes; /code diff shows colored working-tree diffs.

Mercury Bots

Bots are persistent, persona-scoped specialists that live alongside the main agent. Each has its own character, provider/model, scoped memory, and tool permissions — configured once at onboarding, then fully automatic. Bots fail closed (a missing permission is a denial, not a mid-run question), run as async work in the same process, and never block the main agent.

• Onboard via the guided wizard: /bots in the TUI, the web cockpit, or POST /api/bots
• Fleet nesting — leads and crews; bundles export/import a whole fleet (personas + manifests + permissions)
• Surfaces — /bots TUI panel, web cockpit with live SSE activity and a deliverables inbox (outputs//), local HTTP API, and Mercury Cloud relay
• Ops hygiene — per-bot journal, DLQ replay, retention caps on disk, mercury bots doctor for fleet health

Full design and decision log: BOTS-ARCHITECTURE.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. If Mercury is already running, mercury up just confirms it and shows the PID.

Crash recovery: a crash flag (~/.mercury/.crash-flag) records ungraceful exits and reports on next startup; the watchdog restarts crashed daemons with exponential backoff (up to 10 restarts per minute) and escalates to a hard stop with last-gasp logging.

Other daemon commands

mercury restart      # Restart the background process
mercury stop         # Stop a background process
mercury start -d     # Start in background (without service install)
mercury attach       # Attach this terminal to an already-running runtime
mercury logs         # View recent daemon logs
mercury status       # Show if daemon is running

In daemon mode, Telegram becomes your primary channel — CLI input goes through mercury attach instead, which gives you the full TUI (chat, streaming, /-commands) against the existing runtime.

CLI Commands

In-Chat Commands

Type these during a conversation — they don't consume API tokens. Highlights (full list: /help):

Built-in Tools

~50 tools are registered dynamically based on enabled capabilities:

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///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 before installing.

Overrides: --registry (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 , /skills view , /skills install (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 API endpoints.

Web Dashboard

Mercury includes a built-in web UI at http://127.0.0.1:6174 (port via MERCURY_PORT or web.port):

mercury doctor   # Enable web during setup

Or set in ~/.mercury/mercury.yaml:

web:
  enabled: true
  port: 6174

Features: chat with SSE streaming, Kanban boards, Mercury Bots cockpit (fleet roster, onboarding wizard, deliverables inbox), Second Brain visualization, Workspace IDE, provider/skill/permission/schedule management, usage tracking, dark/light theme, WebSocket relay for Mercury Cloud.

The first-run web password is randomly generated and displayed once so you can log in and change it (a hardcoded default from a public repo would be a known credential the moment the source ships). Reset later with mercury web-reset-password. Credentials are written 0600, and the dashboard binds to localhost only.

Kanban Boards

Persistent task boards with agent execution. Create boards, add cards, and let Mercury process them autonomously.

• Cards — title, description, status (todo/doing/done/blocked), priority, labels, comments, attachments, dependencies
• Smart execution — Mercury processes cards sequentially, updating status and leaving result comments
• Cascade execution — process dependent cards in dependency order (web fleet step mirrors the TUI)
• Token budget — per-card token tracking with auto-pause when exhausted
• Storage — SQLite with per-board context, variables, and instructions

Access via Web Dashboard or API (/api/boards/*).

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

Second Brain

Mercury builds a structured, persistent memory that grows with every conversation. Enabled by default, it automatically extracts, stores, and recalls facts about you.

• 10 memory types — identity, preference, goal, project, habit, decision, constraint, relationship, episode, reflection
• Automatic extraction — after each conversation, Mercury pulls 0–3 facts with confidence, importance, and durability scores
• Relevant recall — before each message, the top matching memories (bounded budget) are injected into context
• Auto-consolidation — every 60 min, Mercury builds a profile summary, active-state summary, and generates reflections from patterns
• Conflict resolution — opposing memories are resolved by confidence (higher wins) or recency (newer wins)
• Auto-pruning — active-scope memories go stale after 21 days; inferred memories decay; low-confidence durable memories are dismissed after 120 days
• Graceful on constrained devices — when native better-sqlite3 isn't available (old Node, Termux), Mercury degrades cleanly instead of crashing
• User controls — /memory for overview, search, pause, resume, and clear
• Disable — SECOND_BRAIN_ENABLED=false env var or memory.secondBrain.enabled: false in config

All data stays on your machine in ~/.mercury/memory/second-brain/second-brain.db (SQLite + FTS5). No cloud.

Configuration

All runtime data lives in ~/.mercury/ — not in your project directory.

Mercury Cloud

Mercury can pair with Mercury Cloud for hosted chat, cross-instance relay, and cloud models:

mercury cloud connect    # terminal pairing
mercury cloud status
mercury cloud disconnect

Your local agent stays the source of truth — the cloud connection relays commands and bot activity; mercury cloud disconnect removes the pairing.

Provider Fallback

Configure multiple LLM providers. Mercury tries them in order and falls back automatically, remembering the last successful provider:

Plus community-driven compat providers (LiteLLM, GitHub Copilot model endpoints) discoverable via mercury doctor.

Custom endpoints — anything OpenAI-compatible works via OPENAI_COMPAT_BASE_URL + a model name; no first-class provider needed.

Architecture

• TypeScript + Node.js 22+ — ESM, tsup build
• Vercel AI SDK v6 — generateText + streamText, agentic step loop, provider fallback, OpenAI-compat routing
• grammY — Telegram bot with typing indicators, editable streaming, auto-retry, and file uploads
• discord.js / @slack/bolt / signal-cli — Discord, Slack (Socket Mode), and E2E-encrypted Signal bridges
• Hono + @hono/node-server — local web dashboard, REST API, SSE activity feeds, WS cloud relay
• SQLite + FTS5 — Second brain and Kanban boards with full-text search, conflict resolution, auto-consolidation
• JSONL — Short-term, long-term, and episodic conversation memory
• Bot manager — persona-scoped fleet with queues, journals, retention caps, and fail-closed permissions
• Daemon manager — background spawn + PID file + watchdog crash recovery + crash flags
• System services — macOS LaunchAgent, Linux systemd, Windows Task Scheduler (standalone-binary aware)
• ink + React — terminal UI with static transcripts, live regions, mouse-scroll filtering
• pino — structured logging with secret redaction

Build From Source

You can build Mercury yourself from source — either the standard Node bundle (for npm link / local development) or a standalone executable that bundles the entire runtime, so end-users don't need Node.js installed at all.

Prerequisites

• Node.js ≥ 20 (for the build toolchain)
• Bun ≥ 1.3 (only required for standalone binaries; install with curl -fsSL https://bun.sh/install | bash)

Standard build (ESM bundle)

git clone https://github.com/cosmicstack-labs/mercury-agent.git
cd mercury-agent
npm install
npm run build           # builds dist/ via tsup + post-build (UI, static assets)
npm start               # node dist/index.js

Standalone executable (no Node.js required for end users)

Mercury can be compiled into a single self-contained binary using bun build --compile. The resulting file embeds the Bun runtime and the full Mercury bundle.

npm run build:bin            # host platform only
npm run build:bin:all        # clean release: all 5 targets plus web archive and checksums
npm run build:bin:force      # rebuild (overwrite existing binary for the same version)
npm run build:bin:all:force  # replace an existing release directory, then rebuild all targets
node scripts/verify-standalone-release.cjs  # verify an already-built publishable release

Output is versioned so older builds are never overwritten:

release/
├── latest                       → symlink to most-recent version
├── v1.3.1/
│   ├── mercury-macos-arm64
│   ├── mercury-macos-x64
│   ├── mercury-linux-x64
│   ├── mercury-linux-arm64
│   ├── mercury-win-x64.exe
│   ├── web.tar.gz
│   └── checksums.txt            (SHA-256 for downloadable binaries and web.tar.gz)
└── smoke/                       (host-only local builds; never publish)

The version is read from package.json. Host-only smoke builds are isolated from publishable releases. build:bin:all refuses to reuse a non-empty version directory; use build:bin:all:force to delete and recreate it so assets from different revisions cannot be mixed.

Cross-compilation: Bun produces the JavaScript binaries for every target from a single host. Native addons such as better-sqlite3 still require target-compatible packaging. sql.js is used by a narrow web API fallback; it is not a general substitute for all better-sqlite3-backed features.

macOS Gatekeeper: unsigned binaries trigger a warning on first launch. For distribution, sign with codesign --sign "Developer ID" release/v/mercury-macos-arm64 and notarize.

License

MIT © Cosmic Stack

Disclaimer

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

Contributing

We're open to contributions! Mercury is built to evolve, and we welcome help from the community. Whether it's fixing a bug, adding a tool, improving memory, or refining the soul — all quality contributions are appreciated.

🎯 Agentic Expertise — Must-Have for Contributors

Mercury isn't just another open-source project — it's a soul-driven agent that runs 24/7, manages permissions, remembers context, and interacts across channels. If you're contributing, you must think like an agent builder, not just a library contributor. These are non-negotiable principles every contributor should internalize:

Code Quality — Dos

Code Quality — Don'ts

Getting Started

1. Fork the repo
2. Run npm install
3. Make your changes
4. Run npm run lint && npm run build to verify it compiles (tests: npm test)
5. Test with mercury locally
6. Open a PR with a clear description of what you changed and why

PR Guidelines

• Keep PRs focused — one feature/fix per PR
• Include before/after behavior in the description
• Tag related issues if applicable
• Be responsive to review feedback

Need Help?

Open an issue or reach out at mercury@cosmicstack.org. We're friendly.

Community

1. Discord — Join the Mercury Agent Discord for real-time chat, support, and community discussions.