Little Canary Prompt Sensor
Screen untrusted input with a powerless probe model before your host agent acts.
- Source repo
- hermes-labs-ai/little-canary
- Stars
- ★ 39
- Last updated
- 4d ago
- License
- Apache-2.0
- Primary language
- Python
- FA score
- 78/100 · Good
At a glance
- How it runs
- Works with
- Universal · cross-platformClaude Code · OpenAI API
- Cost
- Free, no paid service needed
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A team maintaining Claude Code workflows can screen submitted prompts at UserPromptSubmit and block unsafe turns.
- Not a fit if
- Teams that need screening across all history and tool results
- Teams that require PASS to prove content is harmless
- Source review
- 78/100 · Good
What does this agent do, and when should you use it?
Little Canary is a preflight sensor for untrusted text: it sends input to a canary model with no tools or credentials, then checks whether the model's behavior changed. Its Python SecurityPipeline combines structural checks with behavioral probing and returns PASS, FLAG, BLOCK, or an insufficient-coverage state for the host to enforce. It ships as a CLI and Python library, plus a loopback-only local HTTP service, and documents integrations for hosts including Claude Code, Gemini CLI, and the OpenAI Agents SDK. The default live probe uses local Ollama and a selected model; StructuralFilter and the offline demo can run without a model call. It is a defense-in-depth layer: PASS means no covered signal was found in that inspection, not that the input is guaranteed safe.
It preflights text end to end: StructuralFilter checks locally for known suspicious patterns; when the canary is enabled, SecurityPipeline sends untrusted text to a model without tools or credentials, inspects the response for behavioral signals, and produces a verdict. Use little-canary demo for an offline replay of a packaged capture, or add --live to call Ollama. little-canary serve exposes /check and /health on 127.0.0.1:18421; it defaults to advisory mode, while --mode block opts into blocking policy. Python applications can call SecurityPipeline.check() directly, and little-canary screen checks JSONL items individually. Host integrations apply results at their own interception points, which may support only warnings or downstream tool restrictions.
- A team maintaining Claude Code workflows can screen submitted prompts at UserPromptSubmit and block unsafe turns.
- A Gemini CLI user can inspect the current prompt at BeforeAgent and choose whether screening failures warn or deny the run.
- An agent developer receiving web pages, email, or tool results can preflight that untrusted text before passing it to the primary model.
- A Python application team can integrate structural and behavioral checks through SecurityPipeline.check() or the local /check service.
- An operations team processing JSONL documents can use screen for independent item verdicts or experimental ingest for evidence-backed admission decisions.
How do you install or deploy this agent?
Python 3.9+ is required; the offline demo and structural-only filter do not require a model download. Live canary screening requires Ollama, its server, and a pulled model. Install the package:
pip install little-canaryStart Ollama and pull the default model for live checks:
ollama serve
ollama pull qwen2.5:1.5bFor a host extension, the README documents Gemini CLI installation with:
gemini extensions install https://github.com/hermes-labs-ai/little-canaryHow do you use this agent?
Start with the offline demo. It replays a packaged capture and makes no model or network call:
little-canary demoRun the live Ollama demo:
little-canary demo --live --backend ollama --model qwen2.5:1.5b --endpoint http://127.0.0.1:11434Start the local service in blocking mode; advisory mode is the default:
little-canary serve --mode block --canary-model qwen2.5:1.5b --ollama-url http://127.0.0.1:11434Submit text to screen:
curl -sS http://127.0.0.1:18421/check \
-H 'Content-Type: application/json' \
-d '{"text":"untrusted text"}'A Python project can use the package's structural filter. This is pattern screening only, not a behavioral PASS:
from little_canary import StructuralFilter
screen = StructuralFilter()
result = screen.check("Summarize this quarterly report.")
print(result.blocked, result.reasons)What are this agent's strengths and limitations?
- Combines known-pattern checks with a behavioral probe that observes whether untrusted input changes a powerless canary's response.
- Includes StructuralFilter and an offline replay demo that need no model call, useful for a first run or structural-only screening.
- Offers Python, loopback HTTP, and several host integrations; its host capability matrix documents where each integration can block.
- The screen and experimental ingest workflows keep per-item results, while ingest separates detection from coverage before admission.
- Live behavioral screening requires Ollama and a local model by default; on CPU-only hardware, a demo call can take several minutes.
- Effectiveness depends on the selected canary model, policy, and attack; the README makes no Little Canary detection-rate claim.
- Structural rules can block quoted attack phrases, and behavioral rules can flag harmless canary acknowledgements.
- Blocking varies by host: OpenCode is advisory only, while Hermes Agent removes downstream tool authority but still passes the original prompt to the model.
How does this agent compare with similar options?
The README distinguishes structural pattern filtering from behavioral canary probing. It also discusses independent decision-model gates as a related but different method, and explicitly says those research results are not Little Canary product metrics.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Little Canary Prompt Sensor This agent | 78 · Good | CLIFree | ★ 39 | 4d ago | Python | Claude Code · OpenAI API |
| Agentic Security | 45 · Major gaps | CLIFree + model costs | ★ 2k | 20d ago | Python | OpenAI API |
| Open Computer Use (MCP desktop service) | 44 · Major gaps | CLIFree + model costs | ★ 2.4k | today | Swift | Codex · Claude Code |
| Local OpenAI LLM (Home Assistant Custom Integration) | 66 · Some gaps | Self-hosted serviceFree + model costs | ★ 296 | 2d ago | Python | OpenAI API |
How does FollowAgents rate this agent?
Why each dimension lost points
The materials say the canary has no tools or application credentials and its output is not automatically forwarded; the HTTP service binds to loopback, defaults to advisory mode, and requires explicit selection to block. Batch and ingest budgets, refusals, and publication rollback are described in detail; manifests omit record text, exports are opt-in, and pair consistency can be verified. Deductions: failures can still route as safe=True under fail-open behavior, and runtime confirmation is not required; the backend receives raw input, low-level objects retain sensitive responses, and an optional judge receives the response. Dependency versions have bounds, CI, and automated updates, but no dependency audit result is provided. Publisher identity is unverified; README attribution and package metadata do not independently establish identity or maintenance responsibility.
The materials describe degraded status, null risk on failures, visible coverage states, and distinctions among unexercised, error, and incomplete, with a startup health-check recommendation. Deductions: fail-open routing can still yield safe=True, so integrations must recognize degraded status; live detection depends on Ollama availability, and some ingest configurations require context verification first. Diagnostics are detailed, but the security policy promises best-effort handling without a response time.
Developer use is covered through structural filtering, live canary checks, HTTP, Python integration, batch screening, experimental ingest, and host plugins. The materials distinguish structural from behavioral checks, advisory from block mode, supported backends, and ingest exclusions for providers and judges. Deductions: triggering relies on a limited set of structural signals and canary behavior analysis, with no demonstrated coverage of novel attacks; deployment depends on Ollama, model weights, and hardware, and CPU calls may take minutes.
The README is organized around the concept, quick start, integrations, batch screening, ingest, and evaluation, with detailed commands, input/output examples, and limitations; the Apache-2.0 license is present, and version and changelog references are clear. Deductions: the supported-version table lists only 0.1–0.3 while package metadata says 0.5.0, leaving maintenance information inconsistent; a contact and reporting route exist, but handling is best-effort and publisher identity is unverified.
Results include PASS/FLAG/BLOCK, status fields, signals, risk, per-item batch states, and ingest coverage/admission evidence. Behavioral canary checks add a detection path beyond structural pattern matching. Deductions: the README says a historical detection rate was withdrawn and provides no current frozen evaluation; structural filtering can reject quoted attack phrases, live model calls add latency and cost, and detection has stated coverage limits.
The README separates the demo, structural screening, external decision-model research, and this product's measurements, explicitly saying external figures are not Little Canary results. It describes benchmark methods, corpora, withdrawn results, and claim boundaries; CI, test source, package configuration, and security notes provide corroborating repository evidence. Deductions: the external benchmark only offers directional evidence for a related mechanism, not this product, and static materials cannot establish runtime behavior.
- Under fail-open behavior, safe=True may mean the input was not inspected; integrations must separately handle degraded, canary_status, and analysis_status.
- Do not treat a clean structural check as a behavioral PASS; the README says it only catches known patterns.
- Assess data-handling requirements before sending raw input to the selected backend; low-level responses and optional judge input may also contain sensitive content.
- The README supported-version table ends at 0.3.x, inconsistent with the stated package version 0.5.0.