# cosmicstack-labs/mercury-agent

> mercury-agent is an open-source AI agent that lives on your machine and keeps working after you close the terminal. It keeps a memory of durable facts on your disk and checks file access, shell commands and outbound requests against rules you set before acting. You reach the same agent from a terminal, Telegram, Discord, Slack or Signal, and it is written mainly in TypeScript.

Source: https://github.com/cosmicstack-labs/mercury-agent
Indexed: commit 3e3b44a on 2026-10-14 by Repowise. Facts come from the source and git history, not from the maintainer.

## Facts

- Type: App
- Language: TypeScript
- Stars: 4,032 at index time
- License: MIT
- Code health: 6.5/10, Fair
- Last commit: 2026-10-13
- Contributors: 16

## Install

From the README: https://github.com/cosmicstack-labs/mercury-agent#quickstart

Install Mercury with npm on Node.js 22 or newer.
    npm i -g @cosmicstack/mercury-agent

## How it works

Messages enter through channels: the terminal, Telegram, Discord, Slack, Signal and a local web dashboard all reach the same agent. src/channels/cli.ts implements the terminal channel, and src/index.ts is one of the entry points for starting the program. A single background process owns the channels, bots and web dashboard, so running mercury in a terminal attaches to that process instead of starting a separate one. The agent logic lives in src/core/agent.ts, and each action it takes is checked against permission rules and a daily token budget. src/bots holds the code that defines and checks Mercury Bots, the persistent specialists that run on schedules and deliver finished files. The ui directory holds the browser UI foundation, with src/ui/App.tsx as one of its entry points, and website holds the Docusaurus documentation site. scripts holds build-adjacent tooling such as vendor patching and native dependency checks.

- src/bots/cli.ts: entry point
- src/channels/cli.ts: entry point
- src/index.ts: entry point
- src/skills/cli.ts: entry point
- src/ui/App.tsx: entry point
Modules: src, ui, docs, scripts, website, root. 733 files, 95,776 lines, 4,898 symbols.

## Code health

- Score: 6.5/10 (Fair)
- Rank: #184 of 4,000+ indexed repos
- Hotspots: src/core/agent.ts, src/ui/App.tsx, src/channels/cli.ts, src/index.ts, src/bots/bot-manager.ts
- Lowest file: src/channels/telegram.ts
- Dead code: 34 findings

## Maintenance

- Last commit 2026-10-13, first commit 2026-04-19, 498 commits
- 16 contributors, bus factor 1

## Security

- Security findings are shown to signed-in users at https://repowise.dev/repo/cosmicstack-labs/mercury-agent/security

## More

- Page: https://repowise.dev/repo/cosmicstack-labs/mercury-agent
- Ask this codebase: https://repowise.dev/repo/cosmicstack-labs/mercury-agent/chat
- Docs: https://repowise.dev/repo/cosmicstack-labs/mercury-agent/docs
- MCP (signs in with Repowise on first use):
    claude mcp add --transport http repowise https://api.repowise.dev/mcp/cosmicstack-labs/mercury-agent
