mercury

Mercury Audit — Intelligent Code Auditing for Claude Code and Codex

A sophisticated, goal-aware code auditing system powered by Inception Mercury-2. Audit any codebase with a single command, get actionable findings triaged by business impact, and automatically [...]

Quick Start

Installation (Codex)

1. Add the marketplace from this repository:

   codex plugin marketplace add https://github.com/MLI-Corp/mercury-audit.git
   

2. Install or enable the mercury plugin from the mli-tools marketplace in Codex.

3. Verify the plugin is available by asking Codex to use one of the Mercury skills:

   • mercury-audit — Run a new audit (standard or goal-driven)
   • mercury-report — View existing audit reports
   • mercury-diff — Compare two audit runs
   • mercury-fix-loop — Orchestrate fix implementations with judge approval

Installation (Claude Code)

1. Open Claude Code Settings

   • Click Customize → Personal Plugins

2. Add a New Marketplace

   • Click + Add marketplace
   • Name: mli-tools
   • Source: Git
   • URL: https://github.com/MLI-Corp/mercury-audit.git
   • Ref: master
   • Click Add

3. Enable the Mercury Plugin

   • Find mercury@mli-tools in your plugin list
   • Toggle it ON

4. Verify Installation In any Claude Code session, you now have access to all Mercury tools:

   • /mercury-audit — Run a new audit (standard or goal-driven)
   • /mercury-report — View existing audit reports
   • /mercury-diff — Compare two audit runs
   • /mercury-fix-loop — Orchestrate fix implementations with judge approval

Set Your API Key

Export your Inception API key (get it from https://inceptionlabs.ai):

export INCEPTION_API_KEY="your-key-here"

Or add to ~/.zshrc or ~/.bash_profile for persistence:

echo 'export INCEPTION_API_KEY="your-key-here"' >> ~/.zshrc
source ~/.zshrc

Audit Modes: Standard vs Specialized

Standard Audit

Run a full, comprehensive audit across all 10 categories:

/mercury-audit ~/path/to/your/project

When prompted: Do you have a specific goal or problem in mind for this audit?

→ Answer NO

Mercury will scan your entire codebase for issues in:

• CORRECTNESS — logic errors, off-by-one, broken invariants, dead code
• CONCURRENCY — race conditions, unsafe shared state, deadlock risk
• MEMORY / RESOURCE SAFETY — leaks, unsafe blocks, buffer overruns
• SECURITY — crypto misuse, PII leakage, injection vectors, hardcoded secrets
• ARCHITECTURE / COUPLING — god objects, circular imports, layer violations
• PERFORMANCE — hot-path allocations, blocking I/O, quadratic loops
• ERROR HANDLING — swallowed exceptions, silent failures, retry storms
• IDIOMATIC / API USAGE — deprecated APIs, misused stdlib types
• FEASIBILITY — will this actually work as claimed?
• IMPROVEMENTS — refactor suggestions ranked by impact/effort

Specialized Audit (Goal-Driven)

Run an audit focused on a specific problem you're experiencing:

/mercury-audit ~/path/to/your/project

When prompted: Do you have a specific goal or problem in mind for this audit? → Answer YES and describe your problem in detail.

Example:

"Sim trades started at $50 bankroll, now $50.28 after 2 days with 33 trades — 
not locking in profits, capital is drifting"

Mercury will then:

• Identify findings that explain why your system fails to meet that goal
• Mark goal-blocking findings with blocks_goal: true
• Elevate severity for high-confidence findings that directly block your goal
• Suggest milestones based solely on what the code reveals (not invented)

This transforms the audit into a targeted investigation that answers: "Why isn't this working?"

Features

✨ Smart Audit Modes

• Standard Audit: Full 10-category coverage across your entire codebase
• Goal-Driven Audit: Laser-focused on your stated problem — finds why the system fails to achieve your goal

🏗️ Multi-Agent Workflow

• Auditor: Finds issues, triages by business impact (P0–P3)
• Fixer: Implements code fixes autonomously
• Judge: Reviews fixes, verifies no regressions, ensures root-cause solutions

📊 Persistent Tracking via NAMS

• Every audit session, finding, and fix is tracked in Neo4j
• Query audit history across time and devices
• Link findings to commits and approvals

🔄 Git-First Workflow

• Automatic audit branch creation (audit/mercury-YYYYMMDD-HHMMSS)
• One clean branch per audit run
• Finding IDs in commit messages

Using the Mercury Tools

/mercury-audit — Run an Audit

Entry point for all audits. Asks if standard or specialized, creates a branch, runs Mercury-2, presents findings, and offers the fix loop.

/mercury-audit ~/Coding/finance/gabagool/v2

/mercury-report — View Audit Reports

Read existing audit reports without re-running the API call.

/mercury-report ~/Coding/finance/gabagool/v2

/mercury-diff — Compare Audits