Mercury
A permission-first, persistent personal agent for CLI, Telegram, and local web workflows.
- Source repo
- cosmicstack-labs/mercury-agent
- Stars
- ★ 3.9k
- Last updated
- today
- License
- MIT
- Primary language
- TypeScript
- FA score
- 66/100 · Some gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformOpenAI API · Claude API
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A solo developer who wants an in-terminal assistant to inspect project files, run approved commands, and assist with Git work.
- Not a fit if
- Individuals unwilling to manage model keys and local permission settings
- Telegram users needing group chats; private chats only
- Source review
- 66/100 · Some gaps
What does this agent do, and when should you use it?
Mercury is a locally run TypeScript and Node.js AI agent with CLI, Telegram bot, and localhost web-dashboard interfaces. Its 31 built-in tools cover files, shell commands, Git, URL fetching, messaging, skills, scheduling, and budget reporting, with approval flows and folder-scoped access for external actions. Its Second Brain combines SQLite, FTS5, and JSONL memory, while the dashboard adds Kanban boards, a Workspace IDE, streamed chat, and management views. Mercury can run interactively or as a daemon backed by user-level system services, and it documents ordered provider fallback across DeepSeek, OpenAI, Anthropic, Grok, Ollama Cloud, and Ollama Local. It fits individuals or small teams that want a persistent, self-hosted assistant and are comfortable managing model credentials and local permission settings.
On first launch, Mercury runs a setup wizard for a name, model provider, and optional Telegram connection. During chat it can invoke read_file, write_file, edit_file, run_command, Git tools, and fetch_url; file, shell, network, and Git actions are routed through permission modes, approvals, and scoped access. Before a message it retrieves relevant Second Brain memories, then automatically extracts a limited set of facts after conversation; the structured store is ~/.mercury/memory/second-brain/second-brain.db using SQLite and FTS5. schedule_task creates delayed or cron-based jobs persisted in ~/.mercury/schedules.yaml and routes responses back to the originating channel, while Kanban cards can be processed in dependency order with result comments. mercury up installs and starts the appropriate user-level service, and daemon mode manages a PID and crash recovery with exponential backoff.
- A solo developer who wants an in-terminal assistant to inspect project files, run approved commands, and assist with Git work.
- A small team that wants to message a continuously running assistant through private Telegram chats while administrators approve access.
- A knowledge worker who wants preferences, goals, projects, and decisions retained in a local SQLite memory store and recalled in later conversations.
- A project lead who wants to create local dashboard boards, track cards and dependencies, and have the agent process cards sequentially.
- A user who needs recurring reminders or checks scheduled with cron and returned to the CLI, web, or Telegram channel where they were created.
How do you install or deploy this agent?
For macOS/Linux without Node.js: curl -fsSL https://mercuryagent.sh/install.sh | sh. On Windows: irm https://mercuryagent.sh/install.ps1 | iex. With Node.js 20+, run npx @cosmicstack/mercury-agent, or install with npm i -g @cosmicstack/mercury-agent and run mercury. The first launch opens setup; configure a provider API key as required by the chosen provider (Ollama Local needs no key), then select the Ask Me or Allow All permission mode.
How do you use this agent?
After setup, run mercury for foreground chat, or run mercury up to install the user-level service and keep it running in the background. Use mercury doctor to reconfigure providers, channels, and default permissions; once web is enabled, open http://127.0.0.1:6174. In chat, /permissions changes the session mode, /budget reports budget status, /memory manages memory, and /tasks lists schedules. For initial Telegram pairing, send /start to the bot and approve the returned code with mercury telegram approve <code>.
What are this agent's strengths and limitations?
- External file, shell, network, and Git actions are backed by approval flow, a shell blocklist, and folder-level read/write scoping instead of silent execution.
- Second Brain keeps structured memory, full-text search, conflict resolution, and automatic consolidation in a local SQLite/FTS5 store.
- One agent is available through an Ink CLI, Telegram, and a localhost web dashboard, with documented user-level services for macOS, Linux, and Windows.
- Built-in scheduling, board execution, and community-skill installation extend chat into persistent local workflows.
- You must configure a model provider; every documented provider except Ollama Local requires an API key, and costs depend on that provider.
- npm installation and source builds require Node.js 20+; building standalone executables additionally requires Bun 1.3+.
- In daemon mode the CLI is log-only and Telegram becomes the primary interactive channel; Telegram is private-chat only and pairing requires admin approval.
- The web dashboard documents default credentials of
mercury/Mercury@123; it binds to localhost by default, but adoption still requires an access-control review.
How does this agent compare with similar options?
Mercury is not tied to one model provider: it documents ordered fallback among DeepSeek, OpenAI, Anthropic, Grok, Ollama Cloud, and Ollama Local. Compared with cloud-chat-only deployments, it keeps configuration, memory, schedules, and board data in the local ~/.mercury/ directory and offers user-level background services.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Mercury This agent | 66 · Some gaps | CLIFree + model costs | ★ 3.9k | today | TypeScript | OpenAI API · Claude API |
| Waku | 65 · Some gaps | CLIFree + model costs | ★ 2.2k | 27d ago | Python | OpenAI API · Claude API |
| Ankita Desktop AI Workspace | 69 · Some gaps | Desktop appFree + model costs | ★ 15 | 7d ago | JavaScript | ChatGPT · OpenAI API |
| Iva Personal Assistant | 72 · Some gaps | Chat botFree + model costs | ★ 289 | 5d ago | TypeScript | ChatGPT · Codex |
How does FollowAgents rate this agent?
Why each dimension lost points
The documentation describes path, channel, and role scoped file permissions, command blocking and approval, SSRF defenses, secret redaction in logs, and constrained permission inheritance for sub-agents. The security policy also states that scheduled tasks run in Allow All and that the permission code lacks per-access auditing, so least privilege, confirmation, and data-flow transparency are incomplete. Keys are stored in a local configuration directory, but the packet gives limited detail on their lifecycle. Dependencies and CI are listed, but this material shows no dependency vulnerability monitoring or mitigation. Git pushes, messaging, and skill installation can cause external effects; approval covers some cases, while Allow All bypasses prompts. Git undo and uninstall are mentioned, but general recovery is not described. Maintainer and security contacts are listed, while publisher identity is unverified, limiting attribution.
The CI configuration covers cross-platform type checking, tests, packaging, and binary smoke workflows, but this is configuration evidence rather than results from this review. README presents Ask Me and Allow All as selectable modes; the security policy adds that scheduled tasks use Allow All, an exception users must account for. Crash recovery, provider fallback, doctor commands, and fail-soft guidance are described. The packet cannot establish runtime availability, and some providers and channels depend on external services.
The material identifies personal terminal use, coding assistance, background bots, team channels, and several operating environments, with substantial scenario coverage. Permissions, budgets, channel roles, and skills provide useful boundaries, but Allow All, unattended scheduled tasks, and unaudited community skills are significant exceptions. Multiple channels, providers, and local models are described, and installation guidance covers macOS, Linux, Windows, and Termux; remaining environment constraints point to external documentation.
The README organizes quick start, features, security, reference material, and documentation, with concrete command and configuration examples. Installation and source-build notes specify Node.js requirements, installers, upgrades, binary builds, and unsigned release binaries. The MIT license text is included. A version and supported security versions are stated, and a changelog is linked, but its contents are not in the packet, limiting review of release history and naming stability. The security policy provides reporting channels, support windows, and boundaries; maintenance responsibility and update paths are partly described, but publisher identity remains unverified.
A shared runtime, cross-channel memory, budgets, permissions, and bot coordination could reduce repeated work, with status, plans, file delivery, and management commands as usable outputs. The README describes these workflows, but the packet contains no usage outcomes or cost evidence, limiting assessment of realized value and ongoing costs. Background work and skills broaden capability while adding review and governance overhead.
README claims can be partially compared with package metadata, the entry module, channel and capability exports, the security policy, and CI configuration. The security policy also names an audit gap and the scheduled-task exception. Only a sample of source is supplied, so permission implementation details cannot be checked end to end; CI configuration does not establish that builds or tests passed. The documentation distinguishes some current behavior from known limits, but many product capabilities remain primarily documented claims without corresponding implementation or result evidence in this packet.
- The security policy explicitly says scheduled tasks run in Allow All and that per-access auditing is absent; assess unattended work with these stated limitations in mind.
- Allow All skips ordinary approval prompts, and community skills are described as unaudited; review skills before installation and keep their permissions narrow.
- This review uses only the supplied static file sample; no program or tests were run, and publisher identity was not verified.
Maintain this project? Add the FARS badge to your README
[](https://followagents.com/en/agents/mercury-agent)<a href="https://followagents.com/en/agents/mercury-agent"><img src="https://followagents.com/badge/mercury-agent.svg" alt="FARS review"></a>Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v1.5.1 Mercury v1.5.1
Release notes excerpt
☿ Mercury Agent v1.5.1 Reading aloud and voice typing now use the voice you chose, Gemini included, and the Optimus update button tells you what it did. Speech - Your voice choice counts everywhere. Reading a reply aloud, voice typing and voice notes from Telegram or WhatsApp use the voice service chosen in Settings → Voice when it has a key. A fresh install with only a Gemini key no longer asks for an OpenAI key. …View on GitHub ↗ -
optimus-v0.5.1 Optimus 0.5.1 (plugin update)
Release notes excerpt
Plugin-only update. Install or update with /plugins update optimus, or Plugins → Optimus → Update in Mercury Desktop. Mercury itself is unchanged; works with Mercury 1.3.9 and newer. - Microphone & permissions on every OS. Mercury Desktop's Optimus page shows the microphone, Accessibility and Screen Recording state at the top, with a microphone picker, a live voice-level test and an off switch. - Checks the microphone before a voice session, so a blocked microphone says so instead of a silent session. The macOS permissions check now includes the microphone. …View on GitHub ↗ -
v1.5.0 Mercury v1.5.0
Release notes excerpt
☿ Mercury Agent v1.5.0: Mercury Desktop Mercury now has a desktop app for macOS, Windows and Linux. It runs Mercury on your computer or connects to Mercury on a server, keeps itself and your servers up to date, and asks you before anyone new gets in. Mercury Desktop (new) - One app for chat, code, bots and research. It installs and starts Mercury on this computer for you, or connects to any number of Mercury servers and switches between them from the top bar. …View on GitHub ↗
FAQ
Can it run commands or change files without approval?
Ask Me and Allow All. File, shell, network, and Git actions use the permission system, pending approvals, and scoped access; the stated shell blocklist never executes.What does it cost to use?
/budget controls. Model API costs depend on the configured provider; Ollama Local is documented as requiring no API key.What happens if a model provider fails?
Where is its data stored?
~/.mercury/. The Second Brain database is local at ~/.mercury/memory/second-brain/second-brain.db; the documentation states that this data does not go to the cloud.Thanks — we use this to improve the page.