Mercury

Mercury Audit — Intelligent Code Auditing for Claude Code

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 fix issues with a built-in audit→fix→judge workflow.

Quick Start

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/brettrican/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, try:

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

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

---

Features

✨ Smart Audit Modes

• Standard Audit: Full 10-category coverage (correctness, concurrency, security, performance, architecture, etc.)
• Goal-Driven Audit: Provide your problem statement, and Mercury prioritizes findings that block your goal (e.g., "sim trades aren't locking profits")

🏗️ Multi-Agent Workflow

• Auditor: Orchestrates portfolio audits, triages by business impact (P0–P3), applies fintech-first lens
• Fixer: Implements code fixes autonomously
• Judge: Reviews fixes, verifies no regressions, ensures root-cause fixes (not symptoms)

📊 Persistent Tracking via NAMS

• Every audit session, finding, and fix commit 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 audit branch per run
• Clean commit history with finding IDs

⚡ Fintech-First Lens

• Trading correctness (profit-locking, position-sizing, order execution) is always P0
• Price manipulation, race conditions on order state, and credential exposure = stop-ship
• Risk-aware triage for trading systems

---

Usage

Basic Audit (Standard)

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

→ Mercury will ask if you have a goal. Say NO for a full standard audit.

Goal-Driven Audit (Specialized)

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

→ Mercury will ask if you have a goal. Say YES and describe your problem:

"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:

1. Identify findings that explain why profit-locking fails
2. Mark them with blocks_goal: true
3. Elevate severity for high-confidence findings
4. Suggest milestones based solely on what the code reveals

Run the Fix Loop

After the audit completes and shows findings, accept the offer to run fix-and-judge:

Run the fix-and-judge loop on Critical/High findings?
I'll spawn a Fixer agent to implement fixes, then judge each one before 
marking it complete. No fix is closed until I sign off with zero regressions.
[Y / N / just the goal-blocking findings]

• Y: Fix all Critical/High findings
• just the goal-blocking findings: Only fix findings that block your stated goal
• N: Manual review first

---

How It Works

The 10 Audit Categories

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

Audit→Fix→Judge Loop

Auditor (finds issues) 
  ↓
Fixer agent (implements fixes, commits to audit branch)
  ↓
Judge auditor (reviews, approves/rejects with regression checks)
  ↓
Loop until all Critical/High findings are resolved

Judge verdicts:

• ✅ APPROVED — fix is correct & complete, no regressions
• ❌ REJECTED — root cause not addressed, specific file:line given
• ⚠️ PARTIAL — addresses part of issue, missing work listed

Hard rule: P0 findings (stop-ship) must be COMPLETE before approval.

---

Project Structure

mercury/                                  # Claude Code plugin
├── README.md                             # This file
├── mercury-nams-integration.md           # Neo4j entity schema
├── scripts/
│   └── mercury_audit.py                  # Universal audit CLI
├── skills/
│   ├── mercury-audit/
│   │   └── SKILL.md                      # Entry point skill
│   ├── mercury-report/
│   │   └── SKILL.md                      # View existing reports
│   ├── mercury-diff/
│   │   └── SKILL.md                      # Compare audit runs
│   └── mercury-fix-loop/
│       └── SKILL.md                      # Fix orchestration
└── agents/
    └── code-auditor/
        └── AGENT.md                      # Auditor (STANDARD & JUDGE)

Key Files

mercury_audit.py — Universal audit CLI

• Auto-detects file extensions
• Bundles source by extension or directory
• Calls Inception Mercury-2 API
• Outputs findings + reports + manifest

mercury-audit (skill) — Entry point for /mercury-audit

• Asks: standard or goal-driven?
• Creates audit branch
• Runs audit script
• Presents findings
• Offers fix-and-judge loop

code-auditor (agent) — Two modes

• STANDARD: Orchestrates audits, triages P0–P3
• JUDGE: Reviews fixes, approves/rejects with regression checks

mercury-nams-integration.md — Neo4j schema

• Entity definitions (AuditSession, AuditFinding, FixCommit)
• Relationships (GENERATED, FIXED_BY, APPROVED_BY)
• Integration hooks

---

Priority Framework

P0 — STOP SHIP

• Data loss or corruption
• Credential/secret exposure
• Exploitable injection or auth bypass
• Trading: Order execution bugs, position-sizing violations, drawdown limits not enforced, profit-locking failures

P1 — FIX THIS SPRINT

• Correctness bugs affecting live trading/signals
• Silent failures in critical paths
• Race conditions on shared state

P2 — FIX NEXT SPRINT

• Performance hotspots with clear blast radius
• Architectural debt limiting scale

P3 — BACKLOG

• Nits, style, low-confidence warnings

---

NAMS Integration

Every audit is persisted to Neo4j for cross-device tracking:

Entity	Tracks
AuditSession	One complete audit run (project, branch, goal, finding counts, status)
AuditFinding	Individual finding (severity, category, file, symbol, issue, blocks_goal)
FixCommit	Git commit that fixed a finding (sha, finding_id, fixed_by, approved_by)

Query your audit history:

MATCH (s:AuditSession)-[GENERATED]->(f:AuditFinding)
WHERE s.project_dir CONTAINS "gabagool"
RETURN f.issue, f.severity, f.status
ORDER BY f.severity

---

Examples

Example: Goal-Driven Audit

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

Do you have a specific goal or problem in mind for this audit?
> YES: Sim trades started at $50 bankroll, now $50.28 after 2 days 
with 33 trades. Not locking in profits, capital is drifting.

[Running specialized audit with goal context...]

### 🎯 Goal-Blocking Findings (blocks_goal: true)
| # | Sev | Category | File | Symbol | Issue |
|---|-----|----------|------|--------|-------|
| 1 | CRITICAL | CORRECTNESS | strategies/trader.py | lock_profit() | Profit-lock threshold hardcoded to 0.5%, misses 50% of gains |
| 2 | CRITICAL | CONCURRENCY | core/orders.py | submit_order() | Race condition: profit-lock can trigger mid-trade |
...

### Suggested Next Steps & Milestones
1. **Harden profit-locking** — Fix threshold calculation
2. **Add position-state guard** — Prevent concurrent mutations during exit
3. **Backtest with real data** — Validate that locked positions exit

---

Troubleshooting

"INCEPTION_API_KEY not set"

export INCEPTION_API_KEY="your-api-key"

Plugin not showing in Claude Code

1. Verify marketplace was added: Customize → Personal Plugins → check mli-tools
2. Check the URL is correct: https://github.com/brettrican/mercury-audit.git
3. Restart Claude Code
4. Try /mercury-audit again

Reports not generated

Check that the project directory exists and is accessible:

ls -la /path/to/project

Judge rejected my fix

The judge is strict on P0 findings. Common reasons:

• Fix only addresses the symptom, not the root cause
• Regressions detected in callers
• Incomplete implementation

Re-read the judge's feedback — it specifies exactly what's missing.

---

Contributing

This plugin is maintained by MLI and SassyConsultingLLC. Contributions welcome!

1. Clone: https://github.com/brettrican/mercury-audit
2. Create a branch: git checkout -b feature/your-feature
3. Test locally: /mercury-audit on a sample project
4. Commit: git commit -m "feat: your change"
5. Push and open a PR

---

License

MIT — see LICENSE file.

Support

Questions? Open an issue on GitHub or reach out to SassyConsultingLLC.

---

Inspired by the original mercury_audit.py — now universalized and integrated into Claude Code for seamless, cross-device auditing.