kleinanzeigen-reader: Instructions file for Codex

AGENTS.md — kleinanzeigen-reader

Vendor-neutral instructions for any AI coding/agent system (Cursor, GitHub Copilot, Codex, Cline, Aider, Windsurf, Zed, Gemini CLI, Claude Code …). Claude Code additionally reads CLAUDE.md; the Claude skill lives in SKILL.md / claude-skill/.

What this is

A zero-dependency Python toolkit + CLI that reads and analyzes any kleinanzeigen.de listing (Germany's largest classifieds): dealer vs. private detection, hidden damage flags, duplicate detection, image download, view/watch counters, price tracking, and an optional authenticated mode. Works on cars, electronics, real estate, furniture — any category.

How an agent should use it

Prefer these over re-implementing scraping:

# CLI — machine-readable JSON for any system to consume
kl-read "https://www.kleinanzeigen.de/s-anzeige/..." --json
kl-read URL1 URL2 --json          # compare
python -m kl_reader URL --json    # without installing the entry point

# Python API
from kl_reader import fetch, extract, get_flags, get_rating
from kl_reader import view_counter, seller_other_ads, price_reduction, PriceTracker, Session
data = extract(fetch(url)["html"])

# MCP server (Claude, ChatGPT desktop, Cursor, Cline, Windsurf …)
pip install "kleinanzeigen-reader[mcp]" && python mcp_server.py
# tools: read_listing, compare_listings, listing_views, seller_other_listings, track_price

Function-calling schemas (OpenAI / Gemini / Mistral / Ollama): tools/openai-tools.json.

Key data sources & references

• references/mobile-api.md — reverse-engineered mobile CAPI map, auth scheme, hidden fields
• references/ad-attributes-fields.md — all listing attribute names
• Three always-present HTML sources: JSON-LD, the ad_attributes GTM string, the DFP block

Scope & rules

• Read-only, public data, or your own account (bring-your-own-token, Session).
• Do not access other users' paused/deleted/draft ads, and do not edit/delete listings that aren't yours (owner-scoped → 403). See references/mobile-api.md §7–§8.
• Never store or repeat personal data (names, phone numbers) from listings.
• Keep the core dependency-free — new hard dependencies are not accepted; use optional extras.
• kl_reader/ exists twice (root + claude-skill/kl_reader/) — apply code changes to both.