ARGUS

Autonomous Repository Guardian and Unified Scanner

"A hundred eyes on your codebase."

An MCP server that gives any AI agent complete situational awareness of a codebase — security, quality, architecture, type safety, git history, and dead code — with zero infrastructure.

No server. No database. No CI plugin. No API keys. No data leaves your machine.

npx @cerionautomation/argus

---

Why this exists

Ask an AI assistant "is my codebase secure?" and it guesses, because it can only see the file you pasted. It cannot see the other 400 files, run your tests, or check your git history.

ARGUS fixes that. Connect it as an MCP server and the agent gets 24 tools that read the whole repository, score it across 10 dimensions, and return structured JSON it can act on.

---

ARGUS vs SonarQube

	ARGUS	SonarQube
Setup	npx @cerionautomation/argus	Server + PostgreSQL + CI plugin + admin account
Infrastructure	None	Dedicated host, DB, JVM
Cost	Free, MIT	£15k–£150k/year enterprise
Consumer	AI agents (structured JSON)	Humans (HTML dashboard)
Scan speed	68ms security scan on 99k lines	Minutes; full analysis 10–30 min
Autonomous fixing	Yes — self-healing loop	No
False-positive transparency	critique_report shows every rejection + reason	Manual triage in the UI
Git churn hotspots	Built in	Requires plugin/commercial edition
Dead export detection	Built in	Limited
RAG code retrieval	Built in (local BM25)	Not available
Privacy	100% local	Server-side, often cloud
Offline	Works	Needs the server

Where SonarQube still wins: 30+ language support (ARGUS focuses on TS/JS/Python/Go), decades of rule tuning, compliance certifications, and multi-team dashboards with historical trend reporting. ARGUS is not trying to replace an enterprise quality-gate deployment — it replaces the feedback loop between an AI agent and your code.

---

Accuracy: measured, not claimed

Most scanners drown you in false positives. ARGUS validates every finding against its own evidence and rejects the ones that don't hold up.

Real result on a 99,681-line Next.js production codebase:

Detector generation	Findings	True positives	Precision
Naive regex (v0)	7	3	43%
Multi-gate + semantic critique (v1)	3	3	100%

The four eliminated false positives were:

• "select your dates" in FAQ prose flagged as SQL injection
• select=accessToken in a REST URL flagged as SQL injection
• A console.log flagged as a hardcoded credential (correctly reclassified as secret-logging)

Every rejection is inspectable via critique_report.

How the accuracy works

1. Multi-gate detection. A SQL injection finding requires three independent gates:

• A well-formed SQL statement (SELECT … FROM, not the word "select")
• A query executor within 2 lines (.query(, $queryRaw, knex.)
• Not a URL or REST query string

2. Entropy checks on secrets. A credential must have a known key prefix (sk-, ghp_, AKIA, AIza) or genuine entropy — mixed case, digits, 20+ chars. Interpolated values, env references, and type declarations are excluded.

3. Semantic critique. Each surviving finding is re-examined against its own captured evidence. If the evidence contradicts the claim, it is rejected with a stated reason.

4. Honest confidence. The confidence number is the share of findings marked confirmed rather than possible — not a cosmetic 100%.

---

Tools (24)

Diagnosis

• full_diagnose — everything at once: score, findings, hotspots, dead code, types
• quantum_score — 10-dimension weighted grade (S/A/B/C/D/F), reproducible
• swarm_intel — all scanners in parallel + critique loop
• cheat_sheet — ~150 token repo orientation for an agent

Security

• security_scan — secrets, SQLi, XSS, path traversal, weak crypto, CORS, open redirect, prototype pollution, TLS
• standards_check — OWASP Top 10, SOLID, 12-Factor, Clean Architecture
• dependency_risk — risky packages, wildcard versions, missing lockfile

Quality

• code_quality — empty catch, console.log, @ts-ignore, any, oversized files
• type_coverage — TypeScript strictness score
• memory_scan — listener leaks, missing useEffect cleanup, timer leaks
• test_coverage — ratio, assertion-free tests, skipped tests
• dead_exports — exported symbols nothing imports

Git intelligence

• git_hotspots — files with highest 90-day churn (churn correlates with bugs)

RAG grounding

• rag_retrieve — BM25 code retrieval, local, zero API calls
• ground_finding — full enclosing function + every caller of a symbol
• critique_report — every rejected false positive with its reason

Action

• auto_diagnose — self-healing loop: diagnose → fix → re-score → iterate
• verify_all — build, lint, test with captured output
• risk_assess — 4-dimension risk → Full Autonomy / Mixed / Structured mode
• gap_analysis — missing CI, linter, README, tsconfig
• search — ripgrep-powered, 32× faster than grep
• think — structured chain-of-thought scaffold
• memory_set / memory_get — cross-session persistence

3 prompts: deep_audit, production_gate, debug_root_cause 3 resources: argus://{path}/health, /summary, /hotspots

---

Install

Claude Code

claude mcp add argus -- npx -y @cerionautomation/argus

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "argus": {
      "command": "npx",
      "args": ["-y", "@cerionautomation/argus"]
    }
  }
}

From source

git clone https://github.com/CerisonAutomation/argus-mcp
cd argus-mcp && npm install && npm run build

---

Engineering

• Zero runtime dependencies beyond the MCP SDK and Zod
• Circuit breakers on every scanner — an agent never hangs
• Memory-safe walker — 30MB total / 500KB per file caps, depth-limited
• Sanitised exec — execFileSync with argument arrays, never shell: true
• Strict TypeScript — exactOptionalPropertyTypes, noUncheckedIndexedAccess
• MCP Spec 2025-06-18 — tool annotations, structured content, output schemas

---

Benchmarks

Measured on a 99,681-line / 631-file Next.js + TypeScript production codebase:

Tool	Time
cheat_sheet	146ms
security_scan	68ms
quantum_score	189ms
git_hotspots	24ms
rag_retrieve	111ms
dead_exports	286ms

---

Licence

MIT © Cerison Brown

Built by Cerison Brown — SDET | QA Automation Engineer | AI Workflow & Systems Automation Engineer