# firstwatch: first line of defence for AI agents

firstwatch is free, open-source security for AI agents. Your agent reads web pages, files, tool output and MCP results, and 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.

- Code: https://github.com/dave8172/firstwatch (MIT)
- npm: https://www.npmjs.com/package/firstwatch · PyPI: https://pypi.org/project/firstwatch/
- Check text in your browser: https://quirkyagents.com/firstwatch/#check (the real scanner runs in the page; nothing you paste leaves it)
- Video, how it works (2 min): https://pub-21da2bddd9cf4685b4374f3e9115db36.r2.dev/firstwatch/firstwatch-how-it-works.mp4

## What it does

- **Watches.** It scans every page, file, command output, search result and MCP result your agent reads, in 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.** Clean: nothing found. Note: odd text that asks for nothing risky, logged in one line. Stop: text that tries to make the 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, how to reproduce it. Open format with OpenTelemetry names, MITRE ATLAS and OWASP LLM Top 10 IDs.
- **Stops.** The 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: https://github.com/dave8172/firstwatch/blob/main/docs/rules.md

## Try it inside an agent

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

- [The Butler](https://quirkyagents.com/butler/): an AI butler tidies an inbox. Plant a sneaky email.
- [Plug](https://quirkyagents.com/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`, then `/plugin install firstwatch@firstwatch`
- Codex, Cursor, Gemini CLI and other agents with skills: `npx skills add dave8172/firstwatch`
- Any agent: paste RULE.md (https://github.com/dave8172/firstwatch/blob/main/RULE.md) into its instructions.
- Your own agent: `pip install firstwatch` or `npm install firstwatch`, then call `watch()` on each tool result. `firstwatch/scan` also runs in a browser.

## 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: one stop, and it was real (an attack hidden in invisible Unicode characters, quoted on a security blog).
- Requests written to a person (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.
- 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 (https://quirkyagents.com/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, https://quirkyagents.com/plug/, shows both).
- Hooks are Claude Code only, for now.

## Questions

- **What is prompt injection?** Text written for an AI agent to find and obey, placed in something it reads. 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 (list above).
- **Does it stop tool poisoning or rug pulls?** Not by itself: it scans tool results, not tool descriptions.
- **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 (`FIRSTWATCH_REFETCH=0` turns it off).
- **Why rules and not a model?** Fast, free, explainable, 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.

## 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.