proteus

Proteus

Proteus is a plugin for Claude Code and Codex, plus a local runtime, for structured, continuous vulnerability research against arbitrary codebases.

You give it a target repository. Proteus helps the coordinator map the codebase, select high-ROI security surfaces, generate non-obvious exploitability hypotheses, delegate bounded specialist fronts, validate candidates in realistic labs, and preserve structured memory so future rounds do not repeat low-value work.

It is not a scanner and not a generic code review checklist. Proteus is built for professional bug bounty and offensive codebase research where findings must survive realistic attacker modeling, duplicate checks, expected-behavior checks, negative controls, and PoC validation without artificial lab help.

What Proteus Adds

• Continuous research loop: observe, map, hypothesize, prioritize, delegate, validate, kill or promote, then replan.
• Structured memory in .vros/memory.sqlite, with Markdown exports for humans.
• Global learnings in ~/.vros/global.sqlite for reusable cross-target memory such as user preferences, validation patterns, tooling notes, and playbook material.
• ROI-based surface planning to avoid wandering through the same low-signal areas.
• Named specialist fronts for repeatable multi-agent research: Argus, Loom, Chaos, Libris, Mimic, Artificer, and Skeptic.
• Validation gates that aggressively suppress weak hypotheses, duplicates, expected behavior, public-known issues, forced-vulnerable configs, and lab-created bugs.
• CLI and MCP interfaces, so the same memory and planning operations work from the terminal, Codex, Claude Code, or other MCP-capable assistants.
• Realistic PoC lab scaffolding with attacker model, documented/default config, negative controls, limitations, and evidence capture.
• Triage-ready report draft guidance that favors natural language, concise root cause explanation, realistic impact scenarios, and manual blackbox-style PoCs.

Install

Proteus has three install surfaces:

• CLI/runtime: proteus and proteus-mcp
• Codex plugin: the continuous-vuln-research skill plus MCP configuration
• Claude Code plugin: /proteus, plugin subagents, and plugin MCP configuration

Install the CLI first. The plugin instructions and skills can load without it, but target memory, exports, labs, and MCP tools depend on the proteus and proteus-mcp runtime commands.

1. Install The CLI Runtime

Proteus currently requires Node.js 24 or newer because it uses node:sqlite for local structured memory.

npm install -g https://codeload.github.com/rafabd1/Proteus/tar.gz/refs/heads/main
proteus --version

Expected:

@rafabd1/proteus 0.1.23

The codeload tarball is the recommended install path while Proteus is distributed directly from GitHub. It uses the committed runtime and avoids install-time TypeScript builds on the target machine.

2. Add The Codex Plugin

codex plugin marketplace add rafabd1/Proteus

Then install or enable the proteus plugin from Codex's plugin UI if your host does not install marketplace defaults automatically.

Then register the MCP server from the CLI install:

codex mcp add proteus -- proteus-mcp

3. Add The Claude Code Plugin

Install directly inside Claude Code:

/plugin marketplace add rafabd1/Proteus
/plugin install proteus@proteus-marketplace

Then register the MCP server from the CLI install:

claude mcp add -s user proteus -- proteus-mcp

Quick Start

After installing the plugin in Codex or Claude Code, use Proteus with /proteus.

Example prompts:

/proteus initialize continuous vulnerability research for this repository

/proteus plan the next high-ROI offensive research round for this codebase

/proteus use the existing findings and REPORTS folders, avoid duplicates, and focus on realistic exploitability

/proteus validate this candidate with realistic PoC gates, negative controls, and no forced vulnerable config

/proteus draft a triage-ready report without internal workflow references

When available, Proteus should use persistent goal/campaign features for long-running objectives and subagents for bounded fronts such as Argus, Loom, Chaos, Libris, Mimic, Artificer, and Skeptic. The coordinator still owns strategy, memory, dedupe, validation gates, and final kill/promote decisions. Codex can use the packaged role contracts in plugins/proteus/agents/*.md when spawning subagents by reading the contract and inlining it into the delegated prompt. These paths are plugin-package paths, not target-workspace paths. Claude Code loads the same files as plugin subagents. If the package path is not directly exposed, coordinators should resolve contracts from the installed plugin package/cache, never from the target workspace. The same package/cache resolution applies to templates in plugins/proteus/templates/*.md.

CLI Runtime