google/mantis installation guide

Install Google Mantis for Claude Code on Apple-silicon macOS Tahoe

What you are installing

Mantis is a portable collection of security-review skills. It organizes a review into sequential stages that can study repository history and architecture, build a threat model, plan a review, research possible vulnerabilities, remove duplicates, validate findings, attempt isolated reproduction, propose and verify patches, calibrate risk, and generate a report.

Classification relative to Claude Code

• **Mechanism:** context injection and orchestration through portable skills and slash commands.
• **Claude Code installation mode:** **unclassified**. The supplied repository files document a generic `npx skills` installer and say Mantis is platform-agnostic, but they do not document a Claude Code-specific marketplace, plugin manifest, hook, MCP server, or destination directory.
• **Practical relationship:** Mantis can be added to a compatible coding-agent environment and then used as a staged security-review workflow. The repository does not supply a Claude Code version requirement or a macOS Tahoe compatibility matrix.

This is not a standalone macOS application with an icon. The primary installation documented by the repository adds the skills to your coding-agent setup.

Important safety limits

Mantis can direct an agent to generate and execute reproducer code and patches. The repository warns that generated code may be unstable or perform unexpected actions. It says to use Mantis only in isolated, restricted environments and never on a machine that can reach production systems, sensitive data, or internal networks.

For a first run on your Mac:

1. Use a disposable or non-sensitive test project.
2. Keep Claude Code’s approval prompts enabled.
3. Run stages one at a time.
4. Do not use automatic-approval options such as `--yolo` or `--dangerously-skip-permissions`.
5. Do not run generated payloads directly on the macOS host.
6. Manually verify every finding and patch with a security expert before reporting or deploying it.

The project is described as a demonstration, not an officially supported Google product and not intended for production use.

macOS Tahoe and Apple-silicon considerations

The portable skills are described as platform-agnostic. However, the optional ADK reference harness has important macOS restrictions: its installer warns that MicroVM/KVM hardware virtualization is unsupported on macOS. It says dynamic reproduction on macOS requires a container runtime, or the harness must use its `static-only` sandbox.

The supplied files do not provide a first-party macOS installation procedure for Docker, another container runtime, Python, Node.js, `npx`, Claude Code, or the reference harness’s dependencies. This guide therefore does not invent those setup commands. It uses only the repository’s documented portable-skills installation command.

Do not copy the repository’s `sudo runsc install` or `systemctl` commands into macOS Terminal. Those commands are presented for Linux gVisor/Docker configuration, while the repository’s own installer identifies macOS as lacking the MicroVM/KVM path.

Before installation

Have your normal coding-agent CLI environment configured. The repository does not prescribe a particular agent framework, and it does not document how to install or authenticate Claude Code. It also does not state minimum versions.

The documented installer is invoked with `npx`. If Terminal reports that `npx` is unavailable, stop there. The supplied files do not contain a first-party command for installing it, so obtain it using the official instructions for the software that provides `npx`, then return to this guide.

Install the Mantis skills

1. Open **Terminal** on your Mac. You can find it through Spotlight or in the Utilities folder.
2. Paste the repository’s documented installation command and press Return:

npx skills add google/mantis

1. Follow the prompts shown by that installer. Do not approve unrelated software changes or commands that you do not understand.
2. Wait for the installer to finish. The repository supplies no separate verification, listing, update, or uninstall command, so this guide does not invent one.

You do not need to run the ADK reference implementation merely to add the portable skills. The repository presents that implementation as a separate reference harness with its own Python environment, configuration, sandboxing, and cloud options.

Confirm availability in Claude Code

Open Claude Code in a disposable test repository using your usual workflow. Because the repository does not document a Claude-specific launch command, use the same launch method you already use.

At Claude Code’s interactive prompt, enter one Mantis slash command at a time. Begin with a read-oriented planning sequence rather than reproduction or patching. A conservative initial sequence is:

/mantis-history

/mantis-structural-index

/mantis-summarize

/mantis-architecture

/mantis-threat-model

/mantis-plan

The first three stages are optional in the repository’s manual pipeline, while architecture, threat modeling, and planning prepare the later review. Successful recognition of these commands by the agent is the practical confirmation that the skills are available. If Claude Code treats them as unknown commands, the supplied files do not document a Claude-specific repair command or installation directory. Do not guess by manually copying files into an undocumented location; instead, review the output from the `npx skills` installer and its selected target.

Run a cautious first review

After planning succeeds, continue one stage at a time:

/mantis-researcher

/mantis-dedupe

/mantis-review

/mantis-critic

These stages research possible flaws, consolidate duplicate reports, validate code-level reasoning, and assess whether findings are relevant to production configurations. Expect false positives. The repository specifically recommends starting with a narrow scope and tuning the review rather than scanning an entire large repository on the first day.

The next stages carry substantially greater risk:

/mantis-reproduce

/mantis-chain

/mantis-patch

`/mantis-reproduce` may generate proof-of-concept code, `/mantis-chain` may combine findings into higher-impact attack paths, and `/mantis-patch` may create and test source changes. Do not proceed with these on the host unless you have independently established appropriate isolation. The skills are intended to use network-disabled sandboxes, but the repository warns that an AI agent may make mistakes or skip isolation. On macOS, the supplied source does not establish a complete Tahoe-compatible dynamic sandbox setup.

If you do not have a reviewed sandbox configuration, stop before reproduction and patching. Static analysis results can still be useful, but they are not proof that a vulnerability is exploitable.

When safe to continue, the remaining documented stages are:

/mantis-calibrate

/mantis-reflect

/mantis-report

These calculate risk ratings, record lessons, and create a human-readable security review packet. The report skill writes the latest campaign report under `workspace/report/review_packet-latest.md` according to the repository documentation.

Optional proactive advice

After the reference workflow has accumulated its SQLite knowledge database, the repository documents a proactive advisor skill:

/mantis-advise

The advisor is intended to query threat models, historical vulnerability lineages, verified patch patterns, false positives, and learned invariants before or during code changes. It is not a substitute for the full review pipeline, and its documented implementation expects knowledge produced by the reference workflow.

What not to do

• Do not enable unattended execution on your everyday Mac.
• Do not point Mantis at production credentials, production systems, private internal networks, or sensitive data.
• Do not treat successful reproduction as proof of exploitability in every deployment.
• Do not treat failed reproduction as proof that a finding is false.
• Do not mass-file AI-generated vulnerability reports.
• Do not apply generated patches without human review and project-specific testing.
• Do not assume the optional MicroSandbox/KVM backend works on Apple silicon; the repository explicitly says it is unsupported on macOS.
• Do not use undocumented Claude Code file-copy locations, marketplace commands, update commands, or uninstall commands.

Troubleshooting

If later passes repeatedly inspect the same code, the repository says to confirm that `/mantis-architecture` completed and produced the knowledge base under `workspace/kb/`. The planner uses that knowledge to avoid repeating previously analyzed areas. Also ensure the active project permits the agent to write its `workspace/` state.

For other failures, retain the Claude Code conversation and trajectory so you can inspect what happened. Pay particular attention to rejected permissions, missing skills, unavailable sandbox capabilities, and absent local tooling. Do not solve these problems by granting blanket approval. Keep the review interactive and approve only commands you have read and understood.