mercury agent - Moses Yebei

The Problem

Developers need an AI agent that can read files, run commands, and fetch URLs without silently executing anything. Existing tools either expose too much power or require manual scripting. The core pain is a safe, permission‑controlled runtime that remembers user preferences and enforces token budgets.

What This Does

@cosmicstack/mercury-agent delivers a soul‑driven agent that runs 24/7 from CLI, Telegram, or Web.

Permission‑hardened tools: the shell blocklist lives in src/capabilities/shell/index.ts and is the single source of truth for what commands may run.
Second Brain: a SQLite database (src/database/index.ts) stores 10 structured memory types with full‑text search.
Token‑aware: daily budgets and the /budget command are handled in src/capabilities/interaction/index.ts.
Extensible skills: community skills are installed under ~/.mercury/skills/ and loaded by src/capabilities/index.ts.
Daemon mode: mercury up installs and starts a system service; the service logic lives in src/daemon.ts.

The agent’s personality is defined by user‑editable markdown files (soul.md, persona.md) located in the user’s config directory.

How It Is Wired

Entry point mercury (bin defined in package.json) resolves to dist/cli/mercury.js, which imports src/cli/index.ts. src/cli/index.ts parses arguments, then calls runCommand in src/commands/index.ts.

Command routing runCommand dispatches to src/capabilities/index.ts.

index.ts loads the appropriate capability module (filesystem, shell, interaction) based on the command.
Each capability exports execute (e.g., filesystem.execute(filePath) or shell.execute(command)).

Side effects

File read/write → src/capabilities/filesystem/index.ts updates the SQLite DB via src/database/operations.ts.
Shell execution → src/capabilities/shell/index.ts checks the blocklist, then runs child_process.exec and streams output back to the CLI.
Interaction commands (e.g., /budget) modify the token ledger in src/capabilities/interaction/index.ts, which writes to the database.

Wider blast radius src/capabilities/index.ts is the hub; changes here affect every command. The SQLite schema in src/database/schema.sql is the only external dependency on the filesystem.

How To Use It

Setup

# Standalone binary (no Node required)
curl -fsSL https://mercuryagent.sh/install.sh | sh
# or via npm (Node 20+)
npx @cosmicstack/mercury-agent
# or global install
npm i -g @cosmicstack/mercury-agent

The first run triggers mercury doctor, which creates ~/.mercury/config.json from .env.example.

Configuration

~/.mercury/config.json holds API keys, token limits, and permission mode.
The user’s soul files (soul.md, persona.md) live in the same directory.

Running

# Interactive CLI
mercury
# Daemon mode
mercury up

The CLI launches the Ink TUI (src/ui/ink.ts) and then hands control to the command loop in src/cli/loop.ts.

Real‑World Use

A team uses Mercury as a nightly build monitor. A build-monitor skill watches the CI log directory, and when a new log is written, filesystem.execute triggers a shell command to parse the log, update the second brain, and send a Telegram message with the result.

// build-monitor skill (auto‑loaded from ~/.mercury/skills)
import { watch } from 'fs';
watch('/var/log/ci', async () => {
  const output = await shell.execute('parse-ci-log /var/log/ci/latest.log');
  await db.update('build', { status: output });
  telegram.send('Build completed: ' + output);
});

Code Health & Issues

Tests: 77 test files under tests/.
CI: /.github/workflows/ci.yml runs lint, type‑check, and tests on every push.
License: MIT (LICENSE).
No structural red flags: all major components have unit tests, and the build pipeline is defined in package.json and ui/vite.config.ts.
Missing docs: while docs/ contains comprehensive HTML, Markdown documentation for the internal API is sparse.

The Bottom Line

Mercury offers a well‑structured, permission‑controlled AI agent with persistent memory and token budgeting. Its TypeScript codebase is heavily tested, and the CLI is straightforward to extend with new skills. Teams needing a safe, always‑on agent for CI/CD or personal automation will find it useful, though the internal API docs could be expanded for easier contribution.

What the analyser found

Deployment readiness

6/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

651 files

TypeScript274
JavaScript70
TSX65
HTML50
Markdown13
JSON12

ReactTailwind

Module dependencies

The 10 most depended-upon modules of 414, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_src_utils_config["config"] n1_src_utils_logger["logger"] n2_src_channels_cli["cli"] n3_src_capabilities_permissions["permissions"] n4_src_types_channel["channel"] n5_src_providers_base["base"] n6_src_ui_types["types"] n7_src_channels_base["base"] n8_src_types_agent["agent"] n9_src_skills_loader["loader"] n3_src_capabilities_permissions --> n0_src_utils_config n3_src_capabilities_permissions --> n1_src_utils_logger n7_src_channels_base --> n4_src_types_channel n2_src_channels_cli --> n4_src_types_channel n2_src_channels_cli --> n7_src_channels_base n2_src_channels_cli --> n1_src_utils_logger n2_src_channels_cli --> n6_src_ui_types n5_src_providers_base --> n0_src_utils_config n9_src_skills_loader --> n0_src_utils_config n9_src_skills_loader --> n1_src_utils_logger n6_src_ui_types --> n8_src_types_agent n6_src_ui_types --> n7_src_channels_base n0_src_utils_config --> n1_src_utils_logger n0_src_utils_config --> n4_src_types_channel classDef cyc stroke:#ef4444,stroke-width:2px; class n2_src_channels_cli cyc;

Dependencies

28 of 85 declared dependencies are a major version behind. Resolved 85 of 85 against the registry.

Package	Declared	Latest	Behind
`marked`	^14.1.4	18.0.9	4 major
`@types/node`	^22.13.0	26.2.0	4 major
`react-devtools-core`	^4.28.5	8.0.0	4 major
`commander`	^12.1.0	15.0.0	3 major
`vite`	^5.4.19	8.2.1	3 major
`ink`	^5.2.1	7.1.1	2 major
`@types/better-sqlite3`	^7.6.13	9.6.0	2 major
`typescript`	^5.7.0	7.0.2	2 major

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

medium4

low2

Declare least-privilege permissions for GITHUB_TOKENmedium

.github/workflows/ci.yml

1 workflow(s) declare no permissions, 1 of them reference secrets

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

3 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/ci.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Set timeout-minutes on the workflow jobslow

.github/workflows/ci.yml

1 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Add the repository convention files this project lackslow3 occurrences

missing .editorconfig, .gitattributes, a formatter config

Without them one contributor's editor writes tabs into a Python file, a shell script commits with CRLF and fails in the container, and a notebook diff is unreviewable.

Fix: Add .editorconfig, .gitattributes with text=auto eol=lf, and a formatter config.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.