Summary Mercury-agent is a "soul-driven" AI agent for 24/7 CLI or Telegram operation. It addresses the need for a controllable, transparent, and secure AI assistant through permission-hardened tools, explicit user approvals, and token budgeting, offering enhanced safety and predictability for engineers and power users.

How It Works The agent defines personality via user-owned markdown files (soul.md, etc.). Security features include a shell command blocklist, folder-level scoping, and an approval flow for actions. It manages daily token budgets, auto-conciseness, and interacts via real-time streaming CLI or a feature-rich Telegram interface. It runs as a persistent daemon with crash recovery.

Quick Start & Requirements Install via npx @cosmicstack/mercury-agent or npm i -g @cosmicstack/mercury-agent. First run triggers a 30-second setup wizard for name, API keys, and optional Telegram token. mercury up enables 24/7 daemon mode, installing platform-specific system services (macOS LaunchAgent, Linux systemd, Windows Task Scheduler) for auto-start on boot. Requires Node.js 20+.

Highlighted Details

• Security: Permission-hardened tools, shell blocklist, folder scoping, pending approval flow.
• Customization: "Soul-driven" personality via markdown; extensible skills.
• Channels: Real-time streaming CLI and feature-rich Telegram (HTML, file uploads).
• Persistence: 24/7 daemon mode with auto-restart, crash recovery, system services.
• Token Budgeting: Daily limits, auto-conciseness, overrides.
• LLM Flexibility: Multi-provider support with automatic fallback.

Maintenance & Community Contact support@cosmicstack.org for suggestions, contributions, or inquiries. Specific community channels or contributor details are not provided in the README.

Licensing & Compatibility Licensed under the MIT license, generally permitting commercial use and integration into closed-source projects.

Limitations & Caveats Includes a disclaimer: "This is AI - it can break sometimes, please use this at your own risk." Telegram pairing is single-owner and private chat only. Daemon mode CLI is log-only for input. Relies on flat-file persistence.