mercury-agent Agent工作流

Prerequisites

• Node.js ≥ 20 (for the build toolchain)
• Bun ≥ 1.3 (only required for standalone binaries; install with curl -fsSL https://bun.sh/install | bash)

Standalone executable (no Node.js required for end users)

Mercury can be compiled into a single self-contained binary using bun build --compile. The resulting file embeds the Bun runtime and the full Mercury bundle.

npm run build:bin            # host platform only
npm run build:bin:all        # all 5 targets (macOS arm64/x64, Linux x64/arm64, Windows x64)
npm run build:bin:force      # rebuild (overwrite existing binary for the same version)
npm run build:bin:all:force  # rebuild all targets

Output is versioned so older builds are never overwritten:

release/
├── latest                       → symlink to most-recent version
├── v1.1.9/
│   ├── mercury-macos-arm64
│   ├── mercury-macos-x64
│   ├── mercury-linux-x64
│   ├── mercury-linux-arm64
│   ├── mercury-win-x64.exe
│   └── checksums.txt            (SHA-256 for every binary)
└── v1.2.0/ …

The version is read from package.json — bump it before building to produce a fresh folder. Re-running for the same version skips already-built targets unless --force is passed.

Cross-compilation: Bun produces binaries for every target from a single host. Native modules (better-sqlite3) can't cross-compile, but Mercury gracefully falls back to sql.js (pure JS + wasm) so the cross-compiled binaries still work end-to-end.

macOS Gatekeeper: unsigned binaries trigger a warning on first launch. For distribution, sign with codesign --sign "Developer ID" release/v<version>/mercury-macos-arm64 and notarize.

Installing Skills

Mercury can pull community-contributed skills from the registry at skills.mercuryagent.sh (126+ skills, no auth required).

mercury skills search prompt                  # search the registry
mercury skills browse ai-ml                   # browse by category
mercury skills view ai-ml/prompt-engineering  # render SKILL.md in the terminal
mercury skills view ai-ml/prompt-engineering --web   # open the registry page
mercury skills install ai-ml/prompt-engineering      # install to ~/.mercury/skills/
mercury skills list                           # show installed skills
mercury skills update                         # refresh all installed skills
mercury skills remove ai-ml/prompt-engineering
mercury skills doctor                         # check install root + registry

Installed skills land at ~/.mercury/skills/<category>/<slug>/SKILL.md and are picked up by the agent on the next boot — they're treated identically to built-in skills.

Review before you ship. Skills are community-contributed and unaudited. Run mercury skills view <id> before installing.

Overrides: --registry <url> (or MERCURY_SKILLS_REGISTRY) for self-hosted registries, MERCURY_SKILLS_INSTALL_ROOT for an alternate install path, --json for machine-readable output.

Also installable from:

• Web dashboard — http://127.0.0.1:6174/skills has a registry installer (paste category/slug) and a URL installer side by side.
• Telegram — /skills, /skills search <q>, /skills view <id>, /skills install <id> (admin-only). Every result includes the registry URL so you can review before installing.

See the Skills reference for the full command surface, frontmatter spec, and API endpoints.

Build From Source

You can build Mercury yourself from source — either the standard Node bundle (for npm link / local development) or a standalone executable that bundles the entire runtime, so end-users don't need Node.js installed at all.

Standard build (ESM bundle)

git clone https://github.com/cosmicstack-labs/mercury-agent.git
cd mercury-agent
npm install
npm run build           # builds dist/ via tsup + post-build (UI, static assets)
npm start               # node dist/index.js

Getting Started

1. Fork the repo
2. Run npm install
3. Make your changes
4. Run npm run build to verify it compiles
5. Test with mercury locally
6. Open a PR with a clear description of what you changed and why

Quick Start

One-liner install (no Node.js required) — downloads the latest standalone binary for your OS:

```bash

PR Guidelines

• Keep PRs focused — one feature/fix per PR
• Include before/after behavior in the description
• Tag related issues if applicable
• Be responsive to review feedback

Configuration

All runtime data lives in ~/.mercury/ — not in your project directory.

CLI Commands