Mercury Agent: An Open-Source Soul-Driven AI Agent with Permission-Hardened Tools

Most AI agents today are functionally identical: same generic assistant personality, same unfettered access to your system, same “one-size-fits-all” approach to autonomy. The Mercury Agent, built by cosmicstack-labs, flips that model on its head.

It is an open-source, soul-driven AI agent with permission-hardened tools, token budgets, multi-channel access, and 24/7 operation — all built in pure TypeScript on Node.js 20+ with zero native dependencies.

Let’s dig into what makes it genuinely different.

What Is Mercury Agent?

Mercury Agent is an AI agent framework that runs continuously from your terminal or Telegram. It comes with 21+ built-in tools — filesystem operations, shell commands, git integration, web scraping, skills management, and task scheduling — all wrapped in a permission-hardened security layer that prevents the agent from running dangerous operations.

Under the MIT License, it is free to use, modify, and deploy. Install it via npm, configure it with Markdown personality files, and you have a personalized AI assistant that operates around the clock.

npm install -g @cosmicstack/mercury-agent
mercury start

That is it. No Docker, no Python environment, no native dependencies.

Permission-Hardened Tools: Security as a First-Class Feature

Most autonomous agents suffer from the same vulnerability: they have unfettered access to your system. One hallucinated command and rm -rf / can destroy hours of work. Mercury Agent treats security as foundational rather than an afterthought.

Shell Blocklist

The agent maintains a blocklist of dangerous shell commands that it can never execute:

• sudo, su — privilege escalation
• rm -rf /, rm -rf ~ — destructive deletion
• dd, mkfs, fdisk — disk operations
• chmod 777, chown — permission changes
• kill, pkill — process termination
• :(){ :|:& };: — fork bombs

This blocklist is enforced at the tool level, before any command reaches the shell. Even if the AI model hallucinates a destructive command, the safety layer intercepts it.

Folder-Level Read/Write Scoping

Mercury Agent does not get blanket access to your entire filesystem. Instead, you configure:

• Read scope: which directories the agent can read
• Write scope: which directories the agent can modify

By default, the agent is confined to its working directory and explicitly permitted paths. This prevents accidental reads of sensitive configuration files or writes to system directories.

Pending Approval Flow

For operations that fall into a configurable “sensitive” category (deleting files, running network commands, modifying configuration), the agent enters a pending approval state. It waits for human confirmation before proceeding.

This means you can let the agent operate autonomously on routine tasks while maintaining a safety valve for anything risky.

Soul-Driven: Personality Beyond Prompt Engineering

Mercury Agent introduces the concept of soul-driven AI — a personality system defined entirely by Markdown files, not by hardcoded system prompts. This is where it diverges from the standard “assistant with instructions” pattern.

The Four Soul Files

The agent’s entire personality comes from four Markdown files:

Why Soul Files Matter

Traditional agent customization relies on a single system prompt that grows bloated and becomes difficult to maintain. By splitting personality across four dimensions, Mercury Agent makes each aspect independently editable and composable.

You can swap out persona.md to change communication style without affecting core identity. You can update taste.md to reflect evolving preferences without rewriting everything.

This modular approach also makes it easy to share personality configurations with the community. A “default” personality ships with the agent, but you can replace it with anything from a friendly mentor to a strict SRE bot.

Token-Aware: Budget Enforcement and Auto-Concise Mode

AI agent costs scale with token usage. Mercury Agent includes a token budget system that prevents surprise bills:

[tokens]
daily_budget = 500000         # 500k tokens per day
auto_concise_threshold = 0.7  # Enable concise mode at 70% usage

When the agent has consumed more than 70% of its daily budget, it automatically switches to auto-concise mode — generating shorter responses, truncating verbose output, and favoring efficiency over elaboration.

The budget resets daily. You can monitor usage in real time via the CLI dashboard:

mercury status
# Token usage: 320,450 / 500,000 (64.1%)
# Mode: normal

Multi-Channel: CLI and Telegram with Real-Time Streaming

Mercury Agent runs on two channels simultaneously, with the same personality and tool access on both.

CLI Mode

The CLI offers real-time streaming output — you see the agent’s reasoning and tool calls as they happen. This is ideal for development work, debugging, and situations where you want to observe the agent’s decision process.

mercury chat
# You: Deploy the staging branch to Railway
# Mercury: Let me check the current branch and run the deployment...
# [streaming output of git status, Railway CLI output, etc.]

Telegram Integration

The Telegram channel provides the same agent with full tool access, HTML-formatted responses, file upload support, and inline keyboards for interactive workflows.

mercury telegram --token YOUR_BOT_TOKEN

Once connected, you can message your Mercury agent from anywhere — on your phone, desktop, or while commuting. The agent processes your request and responds with formatted output, including file attachments when needed.

The Telegram mode is particularly powerful for:

• Mobile task management: “Schedule a deployment for 2 PM today”
• File retrieval: “Send me the latest server logs”
• Status checks: “What’s the CI pipeline status?”

Always-On Daemon: 24/7 Autonomous Operation

Mercury Agent runs as a persistent daemon on your system:

• Auto-restart: If the process crashes, it restarts automatically
• Start on boot: Can be configured to launch at system startup
• Cron scheduling: Built-in task scheduler for recurring operations
• Heartbeat monitoring: The heartbeat.md personality file drives periodic self-checks and status reports

This makes Mercury Agent suitable for production monitoring, scheduled maintenance tasks, and long-running automation pipelines that never require human intervention to stay alive.

Provider Fallback: Never Downtime

The agent supports multiple AI model providers with automatic fallback:

If the primary provider is down or rate-limited, Mercury Agent automatically rotates to the next available provider without interrupting your workflow. You can configure priority order and per-provider token budgets in mercury.config.toml.

21+ Built-In Tools

The agent ships with over 21 tools covering common automation needs:

Community Skills extend the agent further. A single command installs shared automation workflows:

mercury skill install deploy-to-railway
mercury skill install daily-server-audit

Skills are lightweight Markdown + script packages that the agent loads on demand.

One-Click Railway Deployment

Mercury Agent deploys to Railway with a single click, making it trivial to run as a cloud service rather than a local process. The Railway deployment handles:

• Persistent 24/7 uptime
• Public Telegram webhook endpoint
• Automatic HTTPS and domain management
• Environment variable configuration for API keys

In production, running Mercury Agent on Railway with the Telegram channel is the recommended setup — you get the reliability of cloud hosting with the convenience of mobile access.

Tech Stack: TypeScript, ESM, Zero Native Dependencies

Mercury Agent is built entirely in TypeScript running on Node.js 20+ with ES modules. It uses tsup for building and ships with zero native dependencies — no platform-specific binaries, no Docker requirement, no Python runtime.

The agent integrates the Vercel AI SDK v4 for model communication, ensuring consistent tool-calling across all supported providers.

This makes installation trivial on any platform that supports Node.js: macOS, Linux, Windows (WSL), and most CI environments.

Getting Started

# Install globally
npm install -g @cosmicstack/mercury-agent

# Initialize configuration
mercury init

# Customize personality (optional)
nano ~/.mercury/soul.md
nano ~/.mercury/persona.md

# Start the agent
mercury start

# Connect Telegram (optional)
mercury telegram --token YOUR_BOT_TOKEN

The mercury init command generates a default configuration with the four soul files, a safe read/write scope, and a default daily token budget of 500,000 tokens. You can start interacting immediately or customize every aspect of the agent’s behavior.

Comparison: Mercury Agent vs. Other Agent Frameworks

Conclusion

Mercury Agent by cosmicstack-labs represents a thoughtful approach to what AI agents should look like when moving beyond demos and into production. The permission-hardened tooling addresses real security concerns that plague autonomous agents. The soul-driven personality system moves beyond single-bloated prompts into maintainable, composable identity files. The token budget enforcement ensures costs stay predictable. And the dual-channel CLI and Telegram access with always-on daemon makes it genuinely useful beyond a single terminal session.

For developers looking for an AI agent that respects boundaries, has genuine personality, and stays operational 24/7 — Mercury Agent is worth serious consideration.

References

1. Mercury Agent on GitHub (cosmicstack-labs) — Source code and documentation
2. Vercel AI SDK v4 — Model communication layer
3. Railway Platform — One-click deployment
4. DeepSeek AI — Default model provider