Why

Coding agents have become genuinely useful testers. They have a shell, they run the same tooling you do, and they cover ground fast. Point one at a target and it will find things.

Then the context window fills up, and the engagement is gone. The next session rescans hosts it already cleared, re-tests what it already ruled out, and cannot tell you which parts of the scope were ever touched. Somewhere in the transcript is a confirmed SQL injection nobody wrote down.

Red Clippy fixes that by giving the agent two things it does not have on its own.

A place to put the work. Every asset, observation, check, and finding lands in a database as testing happens, not in a scrollback buffer. Coverage becomes a query instead of a memory: which assets exist, which checks are cleared on each, what has already been reported. Tomorrow's session picks up exactly where the last one stopped.

Rules to work by. A Red Team Instructions document reaches the agent in the MCP handshake, before it does anything: verify before reporting, prove every claim, take the minimum access needed to demonstrate impact, leave third-party systems alone. Override it per organization and per engagement, because house rules differ between teams and clients.

You stay in the loop the whole time. Everything the agent writes is an ordinary row in the web UI that you can review, correct, reclassify, or throw away.

[!CAUTION] Authorized testing only. Red Clippy is for penetration testers working under an engagement. Test only systems you own or have explicit written permission to assess. Scope marking and the Red Team Instructions exist to keep an agent inside the rules of engagement, but they are guardrails, not authorization. An agent acts on your authority, and you remain responsible for everything it does.

Quick start

Download a binary from the latest release and run it. It sets up the database and serves the panel on 127.0.0.1:7337.

Linux

Windows

Unzip the archive, then from that folder:

Open http://127.0.0.1:7337 and the setup wizard takes over from there.

The database is created in the directory where you run the binary. Uploaded evidence is stored there too, in red-clippy-storage. Both paths can be changed in the config file, see Configuration.

Prefer to compile it yourself? See Building from source.

How the data is organized

Red Clippy groups work into organizations. An organization holds your pentests, and each pentest holds the assets, findings, and evidence for that engagement. If you test for one company, a single organization is all you need. If you consult for several clients, give each client its own: an organization sees nothing belonging to another, so their engagements never mix.

An organization has two names. The display name ("Acme Corp") is what you see in the panel and can be changed later. The slug (acme) is a short lowercase identifier used in the evidence folder on disk (red-clippy-storage/org_acme/pentest_PT-2026-08-27/), so it is fixed once set.

You can belong to several organizations and switch between them from the avatar menu. In each one you are either an owner, who can add and remove people and rename or delete the organization, or a member, who works the engagements.

First run

On first launch the database is empty, so the browser shows a setup wizard instead of a login form. It asks for:

• a slug and display name for your first organization
• a username, and optionally an email
• a password (minimum 8 characters)

The account it creates is the owner of that organization. The wizard only appears while the database has no users; once the first account exists it is permanently disabled, so it cannot be used to create extra accounts later.

After setup, manage organizations and teammates in the app under avatar menu > Organizations.

If nobody can sign in, the CLI is the way back:

Using it

The intended flow is agent-driven. You set up the engagement, then work through the target with Claude Code while it keeps the record.

You set up:

1. Create a pentest. Code, scope, dates. The methodology checklist is seeded automatically.
2. Define scope. Add the domains, hosts, and IP ranges you are authorised to test, and mark anything explicitly out of scope. You can type these in yourself, or paste the client's scope list to the agent and have it enter them for you.
3. Connect the agent over MCP, pinned to this engagement (see below).

The agent then works, and records as it goes:

• Runs recon and testing tools from its own shell, the way it normally would.
• Hands raw scanner output over with ingest_tool_output, or writes assets and observations directly.
• Promotes real scope units to assets, leaves the rest as observations.
• Marks methodology checks as it clears them.
• Files findings with CVSS, PoC, and evidence attached.

You supervise:

• Watch it land in the browser in real time.
• Correct anything: every row the agent wrote is an ordinary record you can edit, reclassify, or delete.
• Check the coverage view for what is still untouched.
• Review on the cross-engagement dashboard, which shows every finding in the organization alongside the pentest it came from.

The agent is optional. It works through the same API the panel does, so anything it records you can also enter, correct, or delete yourself in the browser. Run an engagement entirely by hand, entirely through the agent, or switch between the two as you go.

Connecting an AI agent (MCP)

This is the main way Red Clippy is meant to be used.

red-clippy mcp covers the whole application: scope and assets, observations, methodology coverage, findings, evidence, the attack graph, and tool-output ingestion. A connected agent works the engagement rather than just answering questions about it.

On connect, the server hands the client the Red Team Instructions document, the operating doctrine for how to behave during testing, in the MCP handshake, so it is in the agent's context before the first tool call. It resolves most-specific-first, from a per-engagement override, to an organization default, to the built-in document. Edit the org default under Settings > Red Team Instructions, or set a per-engagement override from the pentest's settings page. get_instructions re-reads it on demand.

Create an API key

Issue one under Settings > API keys. The Connect MCP section below it then gives you ready-to-paste config for each client, with that key, this server's URL, and the binary's own path already filled in. There is nothing to substitute by hand.

To create the key from the CLI instead, and paste it into the snippets yourself:

Claude Code

The name after add is only a label Claude Code shows. The command after -- is what it actually launches, so use the binary's full path: Claude Code will not necessarily find red-clippy on its PATH. If you copy the command from Connect MCP in the panel, the right path is already filled in.

z.ai GLM

z.ai serves an Anthropic-compatible endpoint, so Claude Code can drive Red Clippy with GLM instead of an Anthropic model.

Add this to Claude Code's settings: .claude/settings.local.json inside your working folder to scope it to one engagement, or ~/.claude/settings.json to apply it everywhere.

Two things to substitute:

• your-z-ai-api-key with your own key. Prefer the project-local .claude/settings.local.json, which Claude Code keeps out of git, so the key does not end up committed.
• glm-5.3 with whichever model z.ai currently offers. Model names change, so check z.ai's Claude Code guide for the current one and set every entry to it.

Then add the MCP server exactly as above. Red Clippy is unaffected by the choice of model: MCP runs client-side, so the tools behave identically whichever model is behind the agent.

OpenAI Codex CLI

As per the Codex CLI config, in ~/.codex/config.toml:

Any other MCP client

red-clippy mcp is a plain JSON-RPC 2.0 stdio server. It needs two things in its environment, and takes an optional engagement pin:

--pentest binds the session to one engagement so the agent does not have to name it on every call. Run one MCP entry per active engagement and switch engagements by switching servers.

Once connected, you can just ask: "add a finding to PT-2026-Q2-ACME: reflected XSS in /search, high severity, here is the PoC".

[!NOTE] Your agent and red-clippy serve run on the same machine, which is why RED_CLIPPY_URL points at 127.0.0.1.

Features

A full MCP tool surface. Near-complete parity with the web UI, not a token subset. An agent can create and scope assets, attach observations, mark methodology checks, file and update findings, upload evidence, build graph edges, and search across the organization.

Scope that stays clean. Assets are the units you actually test: domains, hosts, URLs, APIs, mobile packages, IP ranges. Each carries its own checklist, reachability marking, and in/out-of-scope flag. Recon noise (discovered paths, tech fingerprints, certificates, wayback URLs) attaches to an asset as an observation rather than entering the scope list, and is promoted to an asset only when it warrants one. Without that split, a single content-discovery run leaves the asset list unusable.

Findings through to reporting. Severity, CVSS 3.1 with a calculator built into the form, CWE/CVE, PoC, remediation, and file evidence. A cross-engagement dashboard lists every finding in the organization against its source pentest, which is the view a retest needs.

Coverage you can query. 135 built-in checks mapped to OWASP WSTG, plus recon, network, cloud, and OSINT checks. Rollups report what has been tested per asset and per engagement, so cleared ground is not re-tested.

Operating doctrine. The Red Team Instructions document, served over MCP and resolved per-engagement, then per-organization, then built-in default.

Tool output ingestion. Raw scanner output is submitted in a single call, which is how an agent moves results out of its own shell and into the record. Parsers for nmap, burp, nessus, openvas, masscan, naabu, and subfinder, with format auto-detection. Findings, recon, and raw output land together in one transaction.

An attack graph. Link any two nodes with a free-form relation, then traverse neighbours or compute shortest attack paths between them.

Multi-tenant. Every record belongs to an organization. One user can belong to many and switch without signing out, so client data stays separated.

REST API. Org-scoped bearer keys, same surface as everything above.

Optional: a built-in scan runner. A convenience for driving subfinder, nmap, masscan, and naabu from the Scanning page, with resumable per-target coverage. It exists for manual operator use and is not part of the normal agent-driven workflow, where the agent runs its own tooling and ingests the output.

The documentation covers all of this screen by screen, with the MCP tool reference, the REST API and the data model. This README covers getting up and running.

Configuration

Settings come from a TOML file. red-clippy serve reads ./red-clippy.toml by default. Copy the example and edit:

Every field can also be set by CLI flag or environment variable. Precedence is CLI flag > environment variable > TOML > built-in default, per field.

Two settings are file-only:

• frontend_dist overrides the built SPA. Release binaries embed it, so this is normally unset; point it at a directory to serve a patched bundle without recompiling.
• local_open lets the Files page's "reveal in file manager" button shell out to xdg-open / open / explorer.exe on the machine running the server. It ships off. Turn it on only when the server is your own desktop in a logged-in graphical session, never under systemd or when serving remotely.

A key it does not recognise stops startup with an error rather than being ignored, so a typo cannot silently leave you on a default.

Log filtering uses RUST_LOG (default info,sqlx=warn).

Run red-clippy serve --help for the full list.

[!WARNING] Run it locally. Red Clippy binds to 127.0.0.1 and is meant to run on your own machine, next to the agent driving it. It is not built to be exposed to a network or the internet.

CLI reference

Add --help to any subcommand for its flags.

The REST API lives under /api/v1 and authenticates with Authorization: Bearer rcl_<prefix>_<secret>. Keys are org-scoped, so no endpoint takes an organization in its URL. The in-app Help page documents the endpoints.

Building from source

Linux and macOS

make all builds the web UI first, then compiles the binary with that bundle embedded.

[!NOTE] Build order. The React bundle is embedded at compile time. Running cargo build --release on its own works, but if the UI has never been built the binary ships a placeholder page (cargo prints a warning). Run make frontend first, or just use make all.

Windows

Build natively with rustup, the MSVC build tools, and Node installed:

Or cross-compile from Linux using the mingw-w64 toolchain (apt install gcc-mingw-w64-x86-64):

Copy that single .exe to the Windows host and run it. Nothing else to install.

Development

Debug builds read frontend/dist from disk at runtime rather than embedding it, so you can rebuild the UI without recompiling Rust.

Before opening a pull request, run what CI runs: cargo fmt --all --check, make clippy, make test, make lint, and make frontend. make install-hooks wires the formatting and lint gates into a pre-commit hook. See CONTRIBUTING.md for the fuller version, including how to add a parser.

Cutting a release

Bump version in Cargo.toml, then push a matching tag:

CI builds a static Linux binary and a Windows executable, then publishes both as a GitHub release with checksums. The tag must match the crate version or the build fails. To rehearse without publishing, run the Release workflow manually from the Actions tab: it builds and uploads the archives as workflow artifacts and skips the release step.

Contributing

Bug reports, parsers for new tools, and MCP coverage are welcome - see CONTRIBUTING.md.

Found a security issue? Please report it privately via SECURITY.md rather than opening an issue.

License

Copyright (C) 2026 Cyber Security & Privacy Foundation

Released under the GNU General Public License v3.0. This program comes with ABSOLUTELY NO WARRANTY; see the license for details.