Mercury
A permission-first, persistent personal agent for CLI, Telegram, and local web workflows.
- Source repo
- cosmicstack-labs/mercury-agent
- Stars
- ★ 3.2k
- Last updated
- 2d ago
- License
- MIT
- Primary language
- TypeScript
- FA score
- 56/100 · Major gaps
At a glance
- Works with
- Universal · cross-platformOpenAI API · Claude API
- 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.
- Main limitation
- You must configure a model provider; every documented provider except Ollama Local requires an API key, and costs depend on that provider.
- Source review
- 56/100 · Major 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 | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|
| Mercury This agent | 56 · Major gaps | ★ 3.2k | 2d ago | TypeScript | OpenAI API · Claude API |
| Waku | 47 · Major gaps | ★ 1.8k | 6d ago | Python | OpenAI API · Claude API |
| Iva Personal Assistant | 85 · Good | ★ 217 | 1d ago | TypeScript | ChatGPT · Codex |
| AgentRQ | 64 · Some gaps | ★ 1.1k | today | Go | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows permission modes (Ask Me/Allow All), shell blocklist, folder-level read/write scoping, pending approval flow, and Telegram access control. However, data flow transparency is limited, sensitive data handling details are insufficient, dependency security is not fully documented, rollback mechanisms are unclear, and source attribution is based only on repository metadata.
Self-consistency is good, README and package.json align; dependency availability is supported by CI matrix; failure messages have basic descriptions but not in-depth.
Audience is clear (individual users), scenarios are diverse (CLI/Telegram/Web), capability boundaries are defined by permission system, trigger precision is supported by commands and skills, environment fit has cross-platform support.
Information architecture is clear, install notes are detailed, naming is stable, examples and FAQ are partial, known limitations are only a one-line disclaimer, license is clear, versioning and changelog are missing, maintenance responsibility has contribution guidelines.
Output usability has streaming and multiple formats, marginal value is high (memory, permissions, multi-channel), cost-benefit has token budget and free local models.
Claim traceability is average, cross-source corroboration is limited, fact-inference separation is unclear.
- Default credentials (mercury/Mercury@123) pose a security risk; should be changed immediately.
- Skills registry content is unaudited; review before installing.
- Dependency security is not fully documented; check for known vulnerabilities.
- Rollback mechanisms are unclear; back up configuration before upgrading.
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.