Mercury
A permission-first, persistent personal agent for CLI, Telegram, and local web workflows.
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.
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 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>.
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.