What is pupila CLAUDE.md?

Project instructions for Pupila, a configurable job-listing aggregator that gathers public listings, filters and scores them, removes duplicates, and writes job data, an RSS feed, and a Markdown table.

Use them when adding job sources or companies, changing filtering and scoring, working on the interface, modifying the MCP server, or following the project’s local development workflow.

They show where different project rules live, so changes can be made in the right place. The repository uses separate instructions for fetchers, filters, the user interface, and its MCP server.

pupila CLAUDE.md — Instructions file for coding agents by FranRom: Project instructions for Pupila, a configurable job-listing aggregator th

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods

npx agentmods add instructions/franrom/pupila/claude-md

Clone the repo

git clone --depth 1 https://github.com/FranRom/pupila

Wrote this? Show the measurements

A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.

README.md

[![agentmods](https://agentmods.dev/badge/instructions/franrom/pupila/claude-md.svg)](https://agentmods.dev/instructions/franrom/pupila/claude-md)

Your own site

<a href="https://agentmods.dev/instructions/franrom/pupila/claude-md"><img src="https://agentmods.dev/badge/instructions/franrom/pupila/claude-md.svg" alt="Measured on agentmods" height="20"></a>

Per session 4,040 This file is loaded in full into every session.

When invoked 4,040 The same file — it is already loaded in full.

Security scan A 0 findings. Scan, not verified.

Origin original No closer match found in the catalogue.

Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

Model	Per session	Once invoked
Fable 5	$0.04040	$0.04040
Opus 5	$0.02020	$0.02020
Sonnet 5	$0.00808	$0.00808
Haiku 4.5	$0.00404	$0.00404

Measured 5d ago against content hash a23386431724, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade A, and why

pupila CLAUDE.md scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 5d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

CLAUDE.md · 202 lines

How it starts

The opening of the file, as written. The whole thing — 202 lines — stays where its author put it; the contents beside it link to each section on GitHub.

CLAUDE.md

Guidance for future Claude Code sessions working in this repo. Slim by design — this file is loaded every turn. Subsystem details live next to the code that needs them; procedural how-tos live in skills.

Where things live

Topic	Source
Adding a fetcher / tier-S slug	`pupila-fetchers` skill
Tuning filter weights / debugging `_signals`	`pupila-filters` skill
AI review + AI Apply pipelines	`pupila-ai-review` skill
UI patterns (CSS modules, `lib/api/`, hooks, perf)	`ui/CLAUDE.md` (auto-loaded in `ui/`)
MCP server invariants + add-a-tool recipe	`src/mcp/CLAUDE.md` (auto-loaded in `src/mcp/`)
Fetcher security checklist	`src/fetchers/CLAUDE.md` (auto-loaded in `src/fetchers/`)

Overview

pupila is a config-driven, forkable daily job aggregator. Fetches from 19 public sources (5 ATS APIs — Ashby, Greenhouse, Lever, Recruitee, Personio (XML) — plus RSS, JSON boards, Hacker News, HTML scrapers, an Aave Next.js scraper, ashby-private for orgs whose public posting-API is disabled, jobicy and himalayas — no-key remote-jobs feeds with region/country-tagged locations and structured salary, and bluedoor — a free aggregator over ~1.6M postings/31 ATS, queried by profile.location), normalizes them, applies hard exclusion filters, computes a per-job fitScore, deduplicates, and writes data/jobs.json, an RSS feed at data/feed.xml, and an auto-regenerated JOBS.md. README.md is hand-maintained — never overwrite it from code. No external services, no DB.

Cross-cutting invariants (apply repo-wide):

config/profile.json is gitignored — encodes personal scoring preferences. Auto-bootstraps from committed config/profile.default.json on first pnpm run dev / pnpm run ui via bootstrapProfileIfMissing() (idempotent — COPYFILE_EXCL no-ops on the steady state). Don't bypass; don't commit personalized weights.
Mandatory CV gate: pnpm run dev checks for config/candidate-brief.md at startup and exits 1 if missing. Bypass with PUPILA_NO_BRIEF_CHECK=1 or --no-brief-check.
config/candidate-brief.md is the only natural-language config (gitignored). Generated via pnpm run setup-brief --file ~/cv.pdf or via the UI's Profile tab (drop PDF/DOCX/MD CV). CLI shells out to claude/codex/gemini/opencode — auto-detected, override PUPILA_LLM=<provider>.
Local-first scheduling: daily aggregation runs via scripts/install-launchd.sh (macOS) or scripts/install-cron.sh (Linux), not GitHub Actions cron. CI runs only on push/PR for gates.
config/slugs.local.json is gitignored: a personal overlay of per-ATS company-slug add/removes layered on the committed config/slugs.json baseline (effective list = shipped baseline plus overlay adds, minus overlay removes; resolved at fetch time in src/lib/slugs.ts). Written only by the UI's Settings → Job sources panel (/api/sources); never write config/slugs.json from app code. See the pupila-fetchers skill.
config/applied.json source of truth for application tracking (gitignored personal data; the UI writes it via Vite middleware). It's your private application history, so it's NOT committed (that would leak it to anyone cloning the repo); copy the file if you need it on another machine. Don't filter applied jobs out of the main list: the user wants them visible.

Read the full file on GitHub · 202 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

5d ago First seen · 202 lines · 4,040 tokens per session scan A a23386431724

Subscribe to this mod's changes

pupila CLAUDE.md is an instructions file published in the GitHub repository FranRom/pupila (35 stars, last pushed 2mo ago), licensed MIT. It adds 4,040 tokens to every session, about $0.0202 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.

ai-agents ai-tools mcp

pupila CLAUDE.md

Getting it into your agent

Wrote this? Show the measurements

What it costs to keep this loaded

Grade A, and why

Nothing flagged

How it starts

CLAUDE.md

Where things live

Overview

What this file has done since we first saw it

Other instructions, from other repositories

ai-workflow AGENTS.md

trackly-cli CLAUDE.md

vibetags com-example-config-AsyncTestConfig.instructions.md

claude-bridge AGENTS.md

McpServer AGENTS.md

AmbyKit CLAUDE.md