PlamenTSV/plamen

What it is

Plamen's installation and operation surface — the concrete setup workflow, backend trade-offs, and the ordering/config constraints that determine whether an audit run actually works. The summary tells you what Plamen does; this tells you what you have to get right to run it.

How it works

Two backend CLIs are supported and you install at least one. Claude Code has the broadest MCP support (Slither, ChromaDB, Solodit). OpenAI Codex CLI works but doesn't yet support every MCP server — pure-LLM phases fall back to WebSearch. You can install both and pick per-run in the audit wizard.

plamen install is non-interactive (symlinks, config, Python deps, hook self-heal) and safe in any context including CI and headless servers. plamen setup runs the install then drops into an interactive toolchain wizard (Foundry, Solana CLI, Anchor) — run it from a real terminal; in a non-TTY context it exits cleanly after install rather than crashing on the picker.

Preconditions / Affected

Python 3.11–3.12 + pip, Node.js 18+, Git. macOS needs xcode-select --install; Windows needs Developer Mode on (for symlinks). The optional RAG vulnerability DB needs ~6GB RAM.

What to do

Clone with submodules — ZIP downloads silently omit custom-mcp/slither-mcp/, custom-mcp/farofino-mcp/, and the three opengrep-rules/* sets:

git clone --recurse-submodules https://github.com/PlamenTSV/plamen.git ~/.plamen
cd ~/.plamen && python3 plamen.py install

If you already cloned without submodules: git submodule update --init --recursive from inside ~/.plamen/ before install.

To drive setup from an AI assistant, paste SETUP.md only — it has error handling and blocks the heavy RAG build from a non-TTY context. Do not paste docs/setup.md or docs/getting-started.md; those are human manuals with the RAG build inline.

Put the Solodit key where subprocesses can see it — a shell export is not enough, because Claude Code/Codex spawn non-interactive subshells that don't source .bashrc/.zshrc. Add SOLODIT_API_KEY to ~/.claude/settings.json → "env" (or ~/.codex/config.toml → [env]) before running plamen rag. Free key from solodit.cyfrin.io.

Verify without spending API calls: plamen doctor. Resume an interrupted audit: plamen resume.

Caveats

On externally-managed Python (Homebrew, Ubuntu 23.04+), plamen install auto-adds --break-system-packages and writes into system site-packages, printing a stderr notice. To isolate deps instead, activate a virtualenv first and set PIP_BREAK_SYSTEM_PACKAGES=0. Codex runs lose MCP-backed detection on unsupported phases, degrading to WebSearch.