RAPTOR: a Claude Code harness for offensive and defensive security research

What RAPTOR actually is, and who it is for

RAPTOR stands for Recursive Autonomous Penetration Testing and Observation Robot. The README says the authors wanted the name, and the backronym followed. It is an autonomous security research framework built on top of Claude Code, though the README notes it is not tied to Claude Code and you can plug in your own analysis layer.

The problem it addresses is orchestration. Static analysis, binary analysis, LLM-powered vulnerability validation, exploit generation and patch writing normally live in separate tools with separate output formats, and a human carries findings between them. RAPTOR puts those stages in one workflow that runs against a codebase or a binary.

The intended user is someone who already works with Claude Code and wants a security-shaped configuration rather than a general coding assistant. The README is direct about maturity: "It is not polished software. It was built in free time, held together with enthusiasm and duct tape." That sentence should shape how you evaluate everything else on this page. This is not a product with a support contract. It is a configuration and tooling layer that the authors use themselves.

One detail matters more than it first appears: RAPTOR is mostly AI-generated code. The README states the humans set direction, review output and make design decisions while the AI writes the implementation, and that mechanical verification (tests, static analysis, corpus calibration) holds the quality bar. That is a deliberate position, and it means the interesting review surface is the prompts and rules, not only the Python.

How the Claude Code configuration layer drives tool use

The mechanism is configuration, not a monolithic application. The repository root contains CLAUDE.md and a .claude/ directory, and Claude Code loads configuration from the directory it runs in. The README is explicit that if you run claude from any other directory you get plain Claude Code, not RAPTOR.

Inside that configuration, the README describes rules, sub-agents and skills that configure the agent for adversarial thinking and orchestrate security tool usage. The Python entry points sit alongside: raptor.py, raptor_agentic.py, raptor_codeql.py and raptor_fuzzing.py, with core/, engine/, libexec/, packages/, plugins/ and tiers/ directories holding the rest. The names map onto the stages the README lists, so the dispatch from a Claude Code session into a scanner, a fuzzer or a CodeQL run is visible in the repository layout even though the README does not document each module.

Analysis dispatch is the part worth understanding before you install anything. By default Claude Code handles analysis of individual findings itself, with no extra API keys. If you want multi-model analysis, for example Claude plus GPT plus Gemini, you supply API keys for each provider. The requirements.txt file shows how optional that is: the anthropic, google-genai and botocore lines are commented out, with botocore marked PARENT-ONLY and used only by the credential-isolation dispatcher to SigV4-sign Bedrock requests on the worker's behalf. Bedrock API-key auth through AWS_BEARER_TOKEN_BEDROCK does not need it.

The dependency policy is unusually tight for a project of this kind. requirements.txt pins exact versions, and the comment states that minor and patch upgrades arrive through dedicated PRs so any breakage is bisectable. The instructor pin is explained too: 1.15.1 moved diskcache to an extra, and the bump drops diskcache from RAPTOR's install set, which the comment ties to CVE-2025-69872. That is a concrete supply-chain decision rather than a vague claim about security.

Installing RAPTOR and running a first session

The prerequisites are Claude Code with an active subscription (Max, Pro, Team or Enterprise) or an Anthropic API key, Python 3.10 or newer, Node.js 18 or newer, and Semgrep. CodeQL is optional but recommended. The README states that Semgrep installs with pip install semgrep.

The manual path clones the repository and installs dependencies:

git clone https://github.com/gadievron/raptor.git
cd raptor
pip install -r requirements.txt
npm install -g @anthropic-ai/claude-code
pip install semgrep
export PATH="$PATH:$PWD/bin"
raptor

The README advises appending to PATH rather than prepending, so system directories stay ahead of the repository, and notes that symlinking bin/raptor into a directory already on PATH is an alternative. After that, raptor starts a session. The launcher resolves the RAPTOR installation, remembers the directory you launched from so commands like /scan default to it, runs pre-flight trust and project checks, loads the coverage-tracking plugin and sanitises the environment before handing off to Claude Code. It accepts an optional target path and flags including --project, --continue and --model; the README points to raptor --help for the full list. Running plain claude inside the repository also works, but you skip the pre-flight checks, the coverage tracking and the launch-directory defaulting.

The container path is the one the README recommends, on the grounds that containers restrict which parts of your filesystem an agent can reach and limit the blast radius of malicious code that executes, for example through a supply-chain attack. The image is around 6 GB and starts from the Microsoft Python 3.12 devcontainer with static analysis, fuzzing and browser automation tooling added.

docker pull danielcuthbert/raptor:latest
docker run -it \
  -v "$(pwd):/workspaces/raptor" \
  raptor:latest

The image expects the framework mounted at /workspaces/raptor. A target folder can be mounted as well, at /workspaces/target, and the README notes you add --privileged if you need the rr deterministic debugger. VS Code devcontainers are supported too, with the target folder added to the mounts section of .devcontainer/devcontainer.json.

Where RAPTOR breaks down and when it is the wrong tool

The largest constraint is the orchestration layer itself. RAPTOR runs inside a Claude Code session, and Claude Code needs an active subscription or an Anthropic API key. That is a recurring cost and a hard dependency on a third-party service for a tool whose value is partly in its local analysis pipeline. If you cannot run Claude Code in your environment, the framework does not apply to you at all.

The second constraint is the licence split. The project's own pyproject.toml declares license = "MIT", and the README says MIT with a LICENSE file. But the repository metadata reports NOASSERTION, and the README adds a note that CodeQL has its own licence and does not permit commercial use. CodeQL is described as optional but recommended, which puts the most useful optional component behind terms that differ from the rest of the project. If your use is commercial and you enable CodeQL, that note is the thing to read before you build a workflow around it. This is not legal advice; the point is that the single MIT label does not describe the whole dependency set.

The third constraint is reproducibility. The README describes LLM-powered vulnerability validation and exploit generation. Those stages depend on a model, and the README does not document deterministic behaviour, fixed seeds or a way to replay a run and get the same findings. For a security workflow where you may need to justify a finding to someone else, that is a real gap, and the README is silent on it.

Finally, the README does not document rollback or how to undo changes the agent makes to a target. Combined with the container advice about blast radius, the sensible reading is that the authors expect you to isolate the agent rather than trust it to clean up after itself. If you need a tool that only reads and reports, RAPTOR is doing more than you asked for.

RAPTOR versus wiring Semgrep and CodeQL together yourself

The obvious alternative is not another agent framework. It is the conventional pipeline: run Semgrep and CodeQL yourself, triage the results, and use an LLM only where you choose to. Semgrep installs with pip install semgrep and CodeQL is already the recommended optional scanner here, so both are available to you without RAPTOR.

The difference in approach is where the judgement lives. In the manual pipeline, you decide which findings deserve model attention, you write the prompt, and you keep the output. In RAPTOR, the sub-agents, rules and skills in the .claude/ configuration make those decisions, and the README describes the result as an agent configured for adversarial thinking that performs research or attack and defense operations. You are trading control for throughput.

That trade has a cost the README acknowledges in its own way. Because RAPTOR is mostly AI-generated code with mechanical verification holding the quality bar, the verification is the thing you are trusting. A hand-built pipeline has no such layer and no such claim; it is exactly as good as the scripts you wrote. If your team already has a working triage process and a prompt library, RAPTOR replaces judgement you have already encoded. If you do not, it gives you a starting configuration, and the README invites you to improve it by opening a PR rather than treating it as finished.

Maintenance, versions and what a fork costs

The last push to the default branch was on 2026-09-15, and the most recent release is v3.1.0 from 2026-09-07, following v3.0.0 from 2026-04-23. The gap between the two major versions is roughly five months, and the patch release followed about a week before the last push. That is a project moving in occasional bursts rather than on a schedule, which fits the README's description of free-time work.

The upgrade cost is shaped by the pinning policy. requirements.txt pins exact versions and states that minor and patch upgrades arrive through dedicated PRs so breakage is bisectable. For a user this cuts both ways: you get a known-good dependency set, and you get a file that will conflict with whatever else pins requests, urllib3, pydantic or typer in your environment. If you install RAPTOR into a shared virtualenv, expect to negotiate those pins.

Because so much behaviour lives in CLAUDE.md and .claude/, a fork diverges quickly. Your local edits to rules, sub-agents and skills are the parts most likely to conflict when you pull a new release, and the README does not describe a migration path for configuration between versions. Treat your configuration changes as something you track separately from the upstream checkout.

On licensing, the practical reading is that the project declares MIT in pyproject.toml and the README, while the repository metadata reports NOASSERTION and CodeQL carries its own non-commercial terms. If your use is commercial, confirm the CodeQL terms and whether your workflow depends on it before relying on the MIT label alone.

Editorial conclusion

Adopt RAPTOR if you already pay for Claude Code and want static analysis, LLM validation and patch writing driven from one session rather than stitched together by hand; skip it if you need a supported product, reproducible results or anything you can run without an Anthropic subscription. Before you invest time, read CLAUDE.md and the .claude/ directory to see how much of the behaviour is prompt rather than code, and decide whether you can live with the CodeQL non-commercial restriction if your work is commercial.

Frequently asked questions

Official sources

1. gadievron/raptor on GitHub
2. Issues
3. README
4. Releases