Usage

June 18, 2026 · View on GitHub

Just installed? See getting-started.md first — what's required, what's optional, and how to run your first audit.

All invocations -- terminal CLI, Claude Code slash commands, and Codex CLI -- launch the same V2 deterministic driver (plamen_driver.py). Most phases run as a single isolated claude -p (or codex exec) subprocess; breadth, depth, and rescan run as driver-supervised PTY worker pools with one Claude PTY per worker artifact and disk-derived completion (). See pipeline-phases-presentation.md for the per-phase execution shape. The driver provides automatic checkpointing, manifest-exact retry (only missing/bad worker rows re-spawn, not whole phases), gating, rate-limit pause/resume, and haltless resilience — late phases repair-then-degrade and flag unfinished obligations in the report instead of throwing away a finished audit. Bookkeeping-heavy stages (report_index recovery, verify backfill, finding dedup) run as deterministic Python rather than fragile LLM prose-parsing.

Quick Start

Terminal (recommended)

plamen                                  # Interactive wizard
plamen core /path/to/project            # SC audit, Core mode
plamen l1 thorough /path/to/node-client # L1 audit, Thorough mode

Claude Code

/plamen-wizard          # SC audit — interactive config then driver launch
/plamen-l1-wizard       # L1 infrastructure audit

Codex CLI (beta)

The OpenAI Codex CLI (codex exec) is supported as an alternative, cost-saving backend (beta). It runs one codex exec per depth job, detects usage caps from natural-language output and auto-waits instead of halting, and seeds the full mandatory first-pass artifact set so recon/depth degrade losslessly.

Before relying on Codex, read codex-backend.md — it consolidates the known BETA limitations: reduced fan-out vs Claude, MCP tools partially disabled (WebSearch fallback), interactive-only MCP permissions, speculative model mapping with silent downgrade, ChatGPT-auth/usage-cap behavior, and that plamen compare is Claude-only.

Codex requires prior setup: plamen install --codex, which also installs the slash commands into ~/.codex/commands/ (from codex-adapter/commands/). After that, either invoke the slash commands (e.g. /plamen-wizard, /plamen-l1-wizard) the same way as in Claude Code, or use the terminal wrapper directly:

$plamen core /path/to/project
$plamen l1 core /path/to/node-client

CLI Reference (`plamen` / `plamen.py`)

All commands below launch the V2 deterministic driver. The plamen command is a symlink to plamen.py in your PATH.

Audit Commands

Command	Description
`plamen`	Interactive wizard: mode selection, target, docs, scope, cost estimate, launch
`plamen light /path`	Smart contract audit in Light mode (Pro plan, ~18-22 agents)
`plamen core /path`	Smart contract audit in Core mode (Max plan, ~30-50 agents)
`plamen thorough /path`	Smart contract audit in Thorough mode (Max plan, ~40-100 agents)
`plamen l1 light /path`	L1 infrastructure audit in Light mode
`plamen l1 core /path`	L1 infrastructure audit in Core mode
`plamen l1 thorough /path`	L1 infrastructure audit in Thorough mode
`plamen compare`	Diff two audit reports (post-mortem analysis)
`plamen resume`	Resume an interrupted audit from last checkpoint
`plamen resume /path/config.json`	Resume a specific audit config

Setup Commands

Command	Description
`plamen setup`	Toolchain installer: installs chain tools, checks dependencies, shows status
`plamen install`	Symlink installer for Claude Code (`~/.claude/`)
`plamen install --codex`	Symlink installer for Codex CLI (`~/.codex/plamen/`)
`plamen rag`	Build or rebuild the RAG vulnerability knowledge base
`plamen uninstall`	Remove Plamen from `~/.claude/` (and `~/.codex/plamen/` if installed)

Options

Option	Applies to	Description
`--docs PATH`	SC audits	Path to whitepaper or spec file
`--scope PATH`	SC audits	Path to scope file listing contracts
`--notes TEXT`	SC audits	Free-text scope notes
`--network NAME`	SC audits	Target network (ethereum, arbitrum, optimism, base, polygon, bsc, avalanche)
`--proven-only`	SC audits	Cap findings with only `[CODE-TRACE]` evidence at Low severity
`--tier T0\|T1\|T2\|T3`	L1 audits	L1 tier override (auto-detected from LOC by default)
`--modules a,b,c`	L1 T1 audits	Module selection for T1 subsystem scope
`--codex`	All audits	Force Codex CLI backend
`--claude`	All audits	Force Claude Code backend (default)

Examples

# SC audit with docs and scope
plamen core /path/to/project --docs whitepaper.pdf --scope scope.txt

# SC Thorough with proven-only and network
plamen thorough /path/to/project --network ethereum --proven-only

# L1 audit targeting specific modules
plamen l1 core /path/to/geth --tier t1 --modules consensus,p2p

# Build RAG database (requires ~6GB RAM)
export SOLODIT_API_KEY=your_key_here
plamen rag

PATH Setup

To use plamen as a command (instead of python plamen.py):

# 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;" + $env:Path, "User")

Or run directly: python3 ~/.plamen/plamen.py (macOS/Linux) or python ~/.plamen/plamen.py (Windows).

Resuming an Interrupted Audit

The driver checkpoints after each phase. If the process crashes, hits rate limits, or is interrupted:

# Auto-detect and resume
plamen resume

# Resume a specific config
plamen resume /path/to/project/.scratchpad/config.json

# Direct driver launch (advanced)
python3 ~/.plamen/scripts/plamen_driver.py /path/to/project/.scratchpad/config.json

# Fresh restart (discard previous progress)
python3 ~/.plamen/scripts/plamen_driver.py --fresh /path/to/project/.scratchpad/config.json

From Claude Code, running /plamen-wizard auto-detects an existing scratchpad and offers to resume.

Each scratchpad has a .plamen_run.lock that prevents concurrent driver invocations against the same audit. If a stale process owns the lock from a previous crash, the driver refuses to start until the lock is cleared — rm .scratchpad/.plamen_run.lock removes it.

Running from inside Claude Code

/plamen and /plamen-wizard can be launched while a parent Claude Code session is active. The driver strips the parent's Claude identity env vars (CLAUDECODE, CLAUDE_CODE_SESSION_ID, CLAUDE_CODE_ENTRYPOINT, CLAUDE_CODE_EXECPATH, AI_AGENT) from every child subprocess so the nested claude invocations start as fresh sessions instead of detecting a nested-active-session and exiting rc=0 with no work done. The same applies on macOS/Linux where the POSIX PTY layer additionally resets inherited SIGCHLD disposition before each spawn (see architecture.md § PTY Transport).

Operator controls and runtime behavior

Escape / halt: pressing Escape (or sending a halt signal) cancels every queued worker immediately via _cancel_pending_worker_futures and terminates in-flight workers with a 2-second grace (_HALT_TERMINATE_GRACE_S = 2.0) before SIGKILL. The driver then exits with rc=−3 so you can resume with plamen resume.
Compaction heartbeat: Claude auto-compacting its context during a worker turn prints a single informational line ("Claude compacted context; continuing normally (disk gate is source of truth)"). This is not a warning — the driver continues under disk-gate validation. If the artifact reaches PLAMEN_STATUS: COMPLETE, the worker is done regardless of compaction notice.
Worker-pool progress: operators see live per-worker progress directly in the UI (no longer hidden inside Claude's Task tool stdio). File creation, marker transitions (IN_PROGRESS → COMPLETE), and worker completion events are all visible.
Multiple Claude PTY processes: during breadth/rescan/depth you will see multiple claude processes in the process tree — one per worker artifact. This is expected (driver-owned worker pool), not duplication or runaway processes.
Ecosystem auto-detect: the driver mechanically detects the codebase ecosystem (EVM, Solana, Aptos, Sui, Soroban, DAML, or L1 Go/Rust) at startup, shows it on the banner, and auto-corrects a mismatched config.language in place — no halt-to-rerun. Detection is recall-safe: it only overrides on a genuine high/medium-confidence mismatch, and on ambiguity it keeps the configured value and warns rather than guessing. Corrections are surfaced on the TUI ([startup] auto-detected ecosystem=...).
Haltless completion (degrade-with-flag): a finished audit is never discarded at the finish line. If a late phase (report_index, verify, inventory, or resume) cannot fully complete, the driver repairs what it can, then degrades and surfaces the unfinished obligation as a flagged human-review item in AUDIT_REPORT.md rather than halting the run. Stale or corrupt checkpoints recover instead of stranding the audit.

When to Use Which

	Terminal (`plamen`)	Claude Code	Codex CLI
First time	Use this	`/plamen-wizard`	Need Codex + tools
Cost estimate	Shows estimate	No estimate	No estimate
Resume on crash	`plamen resume`	`/plamen-wizard` (auto-detects)	`$plamen resume`
Daily use	`plamen core .`	`/plamen-wizard`	`$plamen core .`

Cost Estimation

The terminal wrapper estimates token usage before launch:

Input/Output tokens (millions)
API cost (USD)
Weekly plan usage (% of Pro, Max x5, Max x20)

Estimates are rough -- actual usage varies with protocol complexity. Run /cost after an audit for actuals.

plamen --estimate TARGET MODE [--scope PATH] [--l1] is an internal flag invoked by the /plamen slash command and the interactive wizard to produce a per-project estimate (printed as JSON). It is not part of the supported direct-CLI option set and is intentionally omitted from plamen help; use the interactive plamen wizard for a standalone cost estimate.