slop-writer: Instructions file for Claude Code

tg-scraper / slop-writer

A skill plus an MCP server that analyze a Telegram channel, can queue a post to it, and can ban the bot subscribers an audit flags. The thirteen MCP tools are the whole agent-facing surface; the skill under skills/slop-writer/ says which tool answers which question and what the numbers mean. Published to PyPI as slop-writer; two install channels (slop-writer install, npx skills@latest add …) serve that same skill directory, and one version covers package and skill. install wires it into a client — Claude Code or Codex, each independently (adr/0009).

Rationale for a decision lives in docs/adr/; vocabulary in CONTEXT.md; structure (what calls what, where a symbol is) in codegraph.

Commands

• uv run pytest — the suite, from the repo root. uv installs the project editable, so it exercises the working tree.
• uv run tools/check_schema_doc.py — dev-only drift guard; run after editing SCHEMA or references/schema.md. CI runs it as its own step.
• uv run --with-editable . tools/tg_*.py — the dev CLIs against the tree.
• slop-writer (the shipped console script): install wires this project's client config (--client claude|codex, repeatable; bare = claude), uninstall removes exactly what it wrote, serve --mcp runs the server over stdio, init writes Telegram credentials and logs in. init needs a TTY for the SMS code — the user runs it, not the agent.

Library rules (src/slop_writer/)

• The domain raises, the entrypoint reports. Nothing under src/slop_writer/ prints an error or exits: it raises SlopWriterError (UsageError for exit 2) and cli.py or server.py decides how to report. That is what lets the server call the same function and build JSON instead.
• errors.ERROR_CODES is a closed vocabulary, enforced at construction. Reuse a code; adding one is a deliberate edit with a raise site.
• A message or a hint names an argument or an operation, never a surface — the same string reaches a human at stderr and a model at a tool result, and only one of them has a flag or a script. tests/test_errors.py scans every literal statically over the modules server.py can reach. When the surface genuinely differs, the caller supplies the noun (prepare_schedule( body_source=…)) or the boundary swaps the hint (server._SETUP_HINT).
• The domain uses a client, the entrypoint owns it. Scrape and scan paths come in twins: X_with_client(client, …) does the work, X(…, session_file) wraps it in one channel_session. A new command adds both forms.
• resolve_peer runs before any open_db — open_db lives inside the channel_session body (for the group scan, inside scan_group_with_client after resolve_group_target). A typo then fails on the handle instead of leaving a stray empty .tg-analytic/<typo>.db, and zero posts always means an empty window.
• Renderers return a string. render.py takes plain dicts and returns Markdown — no Telethon or SQLite types, and no print: on a stdio server stdout is the JSON-RPC transport. The domain returns the result shape (ScrapeResult, GroupScanResult, …); the entrypoint calls summarize_*.
• db.py, errors.py and query.py stay stdlib-only — a query stays answerable without a Telegram client.
• publish.py is the write surface (adr/0003) — posting and banning (adr/0008); nothing on a read path imports it, which is why scheduled.py and audit.py are separate. publish reads them, never the reverse.
• MESSAGE_TOO_LONG comes from the network, by design — the cap depends on the account, so _too_long translates Telethon's error rather than measuring the body.
• A refusal is not an absence. CANNOT_RESOLVE means the handle names nothing, NOT_A_MEMBER means Telegram confirmed the peer and refused this account — one is fixed by correcting the handle, the other by joining. Every new Telethon call that can refuse classifies the two.
• cli.py is argparse, so an installed server carries no CLI framework; typer stays a tools/ script dependency. install.py reads TOML with tomllib and writes it with a local emitter for the same reason — no runtime dependency for one config format (adr/0009).
• A client is selected, never detected, and each is wired independently: install_project/uninstall_project take the selection, return one result per client, and read first-install from that client's own config key. A new client adds an installer, an uninstaller and a renderer section — plus its gate emitter in server.py. The cross-agent pair (AGENTS.md block, .agents/skills/) belongs to no client: written on every install, removed only by an unnarrowed uninstall.
• .tg-analytic/ is runtime state at the project root (gitignored): .env, session.session, one <channel>.db per channel, media/. Entrypoints anchor it on the cwd (--project overrides); the library never reads the cwd.