Plamen (v2.1.1)

Autonomous Web3 security auditor for Claude Code and OpenAI Codex CLI.

Orchestrates 18-100 AI agents across 8 phases to produce audit reports with verified PoC exploits — for smart contracts and L1 node-client infrastructure.

Supports EVM/Solidity, Solana/Anchor, Aptos Move, Sui Move, Soroban/Stellar, DAML/Canton, and L1 Go/Rust node clients.

Prerequisites

Claude Code CLI or OpenAI Codex CLI, Python 3.11-3.12 + pip, Node.js 18+, Git

Backend CLIs. Install at least one. If you only have time to install one, pick Claude Code — it has the broadest MCP support (Slither, ChromaDB, Solodit). Codex is a strong alternative when you'd rather use OpenAI models, but pure-LLM phases fall back to WebSearch where MCPs aren't available. You can install both side-by-side; the audit wizard lets you pick per-run.

• Claude Code:

  npm install -g @anthropic-ai/claude-code
  

• OpenAI Codex CLI — install without sudo using a user-local npm prefix to avoid EACCES on Homebrew/system Node installs:

  mkdir -p ~/.npm-global && npm config set prefix ~/.npm-global
  echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc   # or ~/.bashrc
  npm install -g @openai/codex
  

  Codex doesn't yet support every MCP server — pure-LLM phases use a WebSearch fallback. See docs/mcp-servers.md.

macOS: Also run xcode-select --install (needed for C++ dependency compilation).

Windows: Enable Developer Mode before installing (required for symlinks). Settings > System > For Developers > toggle ON. Or in admin PowerShell: reg add HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock /v AllowDevelopmentWithoutDevLicense /t REG_DWORD /d 1 /f

Per-language tools (Foundry, Solana CLI, etc.) are installed automatically via plamen setup.

PEP 668 / externally-managed Python: On Homebrew Python and Ubuntu 23.04+, system pip refuses to write into the system site-packages. plamen install detects this and adds --break-system-packages to its pip invocations, printing a notice on stderr. If you'd rather isolate Plamen's Python deps in a virtualenv, activate one before plamen install and set PIP_BREAK_SYSTEM_PACKAGES=0 to opt out.

Install

Option A: Let your AI assistant set it up

Open Claude Code or Codex CLI in any project directory and paste the contents of SETUP.md. It is the only Plamen doc designed for AI-assistant consumption — it has step-by-step error handling, expected-output anchors, and stops the assistant from running the heavy RAG build or the toolchain wizard from a non-TTY context. The assistant handles cloning, the non-interactive install (plamen install), and plamen install --codex if you have Codex.

Do not paste docs/setup.md or docs/getting-started.md into the AI — those are long-form manuals for humans and contain the RAG build inline.

After paste-setup, run plamen setup from a real terminal yourself to install chain toolchains (Foundry, Solana CLI, Anchor, etc.) and plamen rag to build the optional vulnerability DB (~6GB RAM).

Option B: Terminal

Linux / macOS:

git clone --recurse-submodules https://github.com/PlamenTSV/plamen.git ~/.plamen
cd ~/.plamen && python3 plamen.py install
python3 plamen.py install --codex    # optional: add Codex CLI backend

Windows (PowerShell):

git clone --recurse-submodules https://github.com/PlamenTSV/plamen.git $HOME\.plamen
cd $HOME\.plamen; python plamen.py install
python plamen.py install --codex     # optional: add Codex CLI backend

Use git clone --recurse-submodules, not "Download ZIP". The repo ships custom-mcp/slither-mcp/ and custom-mcp/farofino-mcp/ as git submodules; ZIP downloads silently omit them. If you already cloned without --recurse-submodules, run git submodule update --init --recursive from inside ~/.plamen/ before plamen install.

install vs setup: plamen install is non-interactive (symlinks + config + Python deps + dangling-hook self-heal) and is safe in any context — Claude Code Bash, Codex shell, CI, headless servers. plamen setup runs the install then drops into an interactive toolchain wizard (Foundry, Solana CLI, etc.) — run it from a real terminal. In a non-TTY context, plamen setup exits cleanly after the install rather than crashing on the picker.

Before building the RAG database: add SOLODIT_API_KEY to ~/.claude/settings.json → "env" section (or ~/.codex/config.toml → [env] for Codex). Free key from solodit.cyfrin.io. This is the only place the key is reliably visible to both plamen rag and audit agent subprocesses. A terminal export is not sufficient — Claude Code and Codex CLI spawn non-interactive subshells that don't source .bashrc/.zshrc.

Python dependencies are installed automatically on first run. On macOS/Linux use python3, on Windows use python.

After install, add to PATH so you can run plamen from anywhere:

Linux (bash):

echo 'export PATH="$HOME/.plamen:$PATH"' >> ~/.bashrc && source ~/.bashrc

macOS (zsh):

echo 'export PATH="$HOME/.plamen:$PATH"' >> ~/.zshrc && source ~/.zshrc

Windows (PowerShell, one-time):

[System.Environment]::SetEnvironmentVariable("Path", "$env:USERPROFILE\.plamen;" + [System.Environment]::GetEnvironmentVariable("Path", "User"), "User")

Then use plamen from anywhere:

plamen                              # interactive audit wizard
plamen resume                       # resume an interrupted audit from last checkpoint
plamen doctor                       # verify install (no audit run, no API calls)
plamen setup                        # toolchain wizard + optional RAG build
plamen migrate                      # upgrade a v1.x install layout
plamen rag                          # rebuild RAG database only
plamen compare                      # diff two audit reports
plamen uninstall                    # remove Plamen symlinks
plamen help                         # full command + option reference

Audit runs accept additional options (--tier, --modules, --network, --notes, --claude, ...). Run plamen help or see docs/usage.md for the complete list.

Important: Always use plamen (not python3 plamen.py) after PATH is set. The python3 plamen.py form only works from inside ~/.plamen/.

The installer (plamen install):

• Creates symlinks from ~/.plamen into ~/.claude/ so Claude Code discovers Plamen's agents, rules, prompts, and commands
• Merges Plamen's permissions into your existing ~/.claude/settings.json (additive only — won't remove your entries)
• Merges MCP server definitions into ~/.claude/mcp.json (won't overwrite your existing servers)
• Injects Plamen instructions into ~/.claude/CLAUDE.md between <!-- PLAMEN:START/END --> markers (preserves your content)
• Installs Python dependencies (RAG database is built separately via plamen rag)

For Codex CLI support, also run plamen install --codex. This sets up ~/.codex/plamen/ (symlinked from ~/.plamen/) with:

• Codex orchestrator config in ~/.codex/AGENTS.md (equivalent of CLAUDE.md), generated from codex-adapter/AGENTS.md
• MCP/tool config in ~/.codex/config.toml (equivalent of settings.json + mcp.json), generated from codex-adapter/config.toml
• Codex-specific slash commands in ~/.codex/commands/, generated from codex-adapter/commands/

Your existing Claude Code and Codex CLI configuration is preserved.

The Plamen repo stays at ~/.plamen. The installer creates symlinks (shortcuts) pointing back to ~/.plamen/:

• Claude Code (plamen install): symlinks into ~/.claude/ — agents, rules, skills, prompts, commands
• Codex CLI (plamen install --codex): symlinks ~/.codex/plamen/ → ~/.plamen/ (shared methodology), and copies codex-adapter/{AGENTS.md,config.toml,agents/,skills/,commands/} into ~/.codex/

When the AI runtime reads ~/.claude/agents/depth-edge-case.md (or ~/.codex/plamen/agents/depth-edge-case.md), the OS transparently reads ~/.plamen/agents/depth-edge-case.md. This means:

• git pull in ~/.plamen updates symlinked files (agents, rules, skills, prompts) automatically for both backends
• You still need plamen install (and plamen install --codex) after pull — CLAUDE.md/AGENTS.md, settings.json/config.toml, and mcp.json are injected/merged copies, not symlinks. Without re-install, the orchestrator follows stale rules. See docs/updating.md.
• Your own files in ~/.claude/ or ~/.codex/ (custom agents, commands) are untouched
• Deleting ~/.plamen would break the symlinks for both backends — don't delete it while Plamen is installed

Migrating from v1.0.x (installed directly in ~/.claude): Close Claude Code (and Codex CLI if running) first, then run:

Linux/macOS:

cd ~/.plamen 2>/dev/null || cd ~/.claude    # cd into whichever exists
python3 plamen.py migrate

Windows (PowerShell):

cd $HOME\.plamen 2>$null; if (-not $?) { cd $HOME\.claude }  # cd int