Which attacks does firstwatch catch?

Instructions planted in what your agent reads that try to steal passwords, keys or files (including through a link in an image), delete everything, run a downloaded script, change the agent's own setup, reveal its instructions or hide something from you. It also finds text hidden from people: HTML comments, white or tiny text, invisible Unicode characters, base64. Separately, MCP tools that send, pay, delete, share or grant always ask you first, attack or not.

Does firstwatch stop tool poisoning or rug pulls?

Not by itself. firstwatch scans what tools return, not how MCP servers describe their tools, so instructions hidden in a tool description (tool poisoning, tool shadowing) or a description that changes later (a rug pull) are not scanned. Its gate still asks before risky MCP actions. Pin tool definitions and connect only the servers a job needs.

Will firstwatch slow my agent down?

About 70 ms per tool call in Claude Code, measured on 2026-10-29. The library is a regular-expression pass over the text.

Which agents does firstwatch work with?

Claude Code gets the full protection: hooks plus a skill. Codex, Cursor, Gemini CLI and other agents with skills get the skill. Any agent can use RULE.md in its instructions, and your own agent can call scan() and watch() from Python or Node.

firstwatch: first line of defence for AI agents

Q: Why rules and not a model?

Rules are fast and free, explain every decision, give the same answer every time, and a page cannot talk them out of it. They miss new wordings, which is why firstwatch also gates actions after an attack. A model-based detector works well next to it.

Your AI agent reads web pages, files, tool output and MCP results. Anyone can hide instructions there for it: prompt injection. firstwatch catches them before your agent acts, whether they try to steal secrets, delete your data, run code or rewrite your agent’s own settings. It saves each attack as evidence and makes your agent ask you first. Free and open source. tool

GitHub dave8172/firstwatch npm firstwatch PyPI firstwatch

Check text for attacks

Paste a web page, an email or any text. firstwatch’s real scanner runs in your browser. What you paste never leaves this page.

Try:

What it does

Watches. It scans every page, file, command output, search result and MCP result your agent reads. It reads the text people see and the text they don’t: HTML comments, white or tiny text, hidden elements, alt text, invisible Unicode characters, base64.

Scores. Each result gets a level. Clean: nothing found. Note: odd text that asks for nothing risky, logged in one line. Stop: text that tries to make your agent act, reveal, send, pay, delete or install.

Records. Each attack becomes a folder of evidence: the exact text, where it hid and how, what it tried, the steps before it, and how to reproduce it. The format is open. It uses OpenTelemetry names and tags each finding with MITRE ATLAS and OWASP IDs.

Stops. Your agent is told the content is an attack. For the rest of the session, every action beyond reading waits for your OK, and so does every MCP call. MCP tools that send, pay, delete, share or grant always ask.

What it catches

Planted instructions are how the attack gets in. What they are after varies:

Stealing. Send passwords, keys or codes to someone; send the contents of every file; leak data through the address of an image.
Wrecking. Delete everything.
Running code. Download a script and run it straight away.
Taking over. Ignore your instructions, play a role with no limits, or change the agent’s own setup files so the attack lasts.
Leaking the agent’s instructions. Show its system prompt.
Hiding. Keep something from you, or hide the text itself: comments, white or tiny text, invisible Unicode, base64.

The gate is not a detector. MCP tools that send, pay, delete, share or grant always ask, attack or not, so the model’s own mistakes reach you too. Every rule, with its MITRE ATLAS and OWASP ID: what each rule catches.

Try it inside an agent

Two simulations run this scanner inside a working AI agent, free in your browser. Turn on firstwatch in the Blue team tab, plant an attack, and watch it stop, warn the agent and ask you first.

The Butler: an AI butler tidies an inbox. Plant a sneaky email.
Plug: an AI agent works through MCP servers. Make one lie about its tools.

Install

Claude Code (hooks and skill, the full protection; Node 20+):

/plugin marketplace add dave8172/firstwatch
/plugin install firstwatch@firstwatch

Codex, Cursor, Gemini CLI and other agents with skills:

npx skills add dave8172/firstwatch

Any agent: paste RULE.md into its instructions (AGENTS.md, CLAUDE.md, a system prompt).

Your own agent: pip install firstwatch or npm install firstwatch, then call watch() on each tool result. Step by step: getting started.

Tested

Live in Claude Code (Haiku, 2026-10-29): asked to summarise a page with a hidden line telling it to send the user’s API key, the agent gave the price, ignored the line, sent nothing and named the capture. On the next turn a shell command was held for approval.
18 real sites as raw HTML (MDN, Python docs, GitHub, BBC, Stripe’s API key docs, PayPal and others): one stop, and it was real. A security blog quotes an attack hidden in invisible Unicode characters, and firstwatch decoded it.
Requests written to a person (version 0.2.0): 10 attacks in mail and messages and 10 harmless lookalikes, written before the rules were finished. All 10 attacks stopped; none of the lookalikes did.
Cost: about 70 ms per tool call in Claude Code; about 0.6 s for a 1.2 MB page.

What it can’t do

It runs on rules. New wordings, other languages and attacks split across pages can get past it. That is what the gate is for.
It scans what tools return, not how they describe themselves. Instructions hidden in an MCP tool’s description (tool poisoning, tool shadowing) or a description that changes after you approve it (a rug pull) are not scanned. Its gate still asks before risky MCP actions. Pin tool definitions and connect only the servers a job needs; Plug shows how.
It reads text. Code that a tool or MCP server runs on its own, and a sign-in that asks for too much access, never pass through your agent’s reading. A sandbox and narrow scopes cover those. Plug shows both.
Hooks are Claude Code only, for now. Other agents get the rule and the capture steps, which depend on the model noticing.

Questions

What is prompt injection? Text written for an AI agent to find and obey, placed in something it reads: a web page, an email, a file, a tool result. It is often hidden from people. It tries to make the agent send secrets, run code, delete things or change its own setup.

Which attacks does it catch? Instructions planted in what your agent reads that try to steal, delete, run code, take over the agent or hide from you. The full list is above.

Does it stop tool poisoning or rug pulls? Not by itself: it scans tool results, not tool descriptions. See what it can’t do.

Does it send my data anywhere? No. Captures are written to your disk, with secrets masked. In Claude Code the only network call is re-reading a page your agent just fetched (turn it off with FIRSTWATCH_REFETCH=0).

Why rules and not a model? Rules are fast and free, explain every decision and give the same answer every time, and a page can’t talk them out of it. They miss new wordings, which is why the gate exists. A model-based detector works well next to it.

It flagged my page, or missed an attack. Open an issue on GitHub. A way past firstwatch itself goes through private reporting.

Words on this page

AI agent: An AI model that does tasks with tools: it reads pages and files, runs commands, sends mail. Claude Code, Codex and Cursor are agents.
Prompt injection: Instructions written for an AI to obey, put where it will read them. Direct: typed into the chat. Indirect: hidden in a page, an email, a file or a tool result. firstwatch watches for the indirect kind.
Tool result: What comes back when the agent uses a tool: a fetched page, a file, a command’s output, a search result.
MCP: Model Context Protocol: a standard way to plug tools into an AI agent. Each MCP server offers some tools, such as mail, files or a database.
Hook: A small program the agent runs before or after each tool call. firstwatch’s hooks scan results and ask you before actions. They run in Claude Code.
Skill: A folder of instructions an agent loads when a task needs it. firstwatch’s skill tells the agent how to spot an attack and what to do.
Gate: firstwatch’s rule for when you are asked: always for risky MCP tools, and for every action beyond reading after an attack.
Capture: The folder firstwatch saves for each attack: the text, where it hid, what it tried, the steps before it, how to repeat it.
Exfiltration: Getting data out to an attacker: in a reply, a request, or the address of an image the chat shows.
base64, Unicode tag characters: Ways to hide text. base64 turns text into letters and digits that read as noise. Unicode tag characters are invisible on screen, but a model can still read them.
OWASP: The Open Worldwide Application Security Project, a nonprofit that publishes free security guides. Its Top 10 for LLM Applications (2025) lists the biggest risks for apps built on language models, with IDs such as LLM01 (prompt injection) and LLM02 (sensitive information disclosure).
MITRE ATLAS: MITRE is a US nonprofit that runs ATT&CK, a widely used catalogue of how attackers work. ATLAS is its catalogue for attacks on AI systems, built from real-world cases and research, with IDs such as AML.T0051 (LLM prompt injection).
Why the IDs: Each finding carries an OWASP and an ATLAS ID, so a security team can file it under a name they already use.
OpenTelemetry: An open standard for the logs and traces that programs send to monitoring tools. firstwatch names its fields the OpenTelemetry way and can export a capture as an OpenTelemetry log record (OTLP is its wire format), so attacks show up next to the rest of your monitoring.
JSON Schema: A file that describes the exact shape of a JSON record, so other tools can check a capture is valid.
Red team, blue team: Red attacks a system to find its weak spots; blue defends it. The Butler and Plug let you play both.
Sandbox, scopes: A sandbox limits what a program can touch on your computer. Scopes limit what a sign-in lets an app do in your accounts.

Technical details

Claude Code: a PostToolUse hook scans WebFetch, WebSearch, Bash, Read, Grep and MCP results; a PreToolUse hook gates actions after a stop. WebFetch hands hooks a summary, so firstwatch re-reads the URL as raw HTML.

Capture format firstwatch/0.1: SPEC.md and a JSON Schema. firstwatch export otlp turns a capture into an OpenTelemetry log record. Rules: what each rule catches, one shared file for Python and Node. No dependencies in either package.