What is subscope CLAUDE.md?

A contributor guide explains how to work on Subscope, a Python engine and set of Claude Code skills for collecting and scoring Reddit content. It covers the code layout, conventions, and how to add pattern skills.

It is for orienting developers, finding files, understanding the Python engine and skill folders, and adding new pattern skills.

It gives contributors the project-specific information they need before changing the code. It also clarifies that plugin users should read the README instead.

subscope CLAUDE.md — Instructions file by dancolta

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/dancolta/subscope/claude-md

Clone the repo

git clone --depth 1 https://github.com/dancolta/subscope

Per session 3,399 This file is loaded in full into every session.

When invoked 3,399 The same file — it is already loaded in full.

Security scan B 3 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.03399	$0.03399
Opus 5	$0.01699	$0.01699
Sonnet 5	$0.00680	$0.00680
Haiku 4.5	$0.00340	$0.00340

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

Security

Grade B, and why

subscope CLAUDE.md scanned grade B with 3 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 3d 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.

Asks for rootmediumPrivilege escalation

A mod that escalates privileges can change anything on the machine, not only the project.

- **`chmod 600` on every config + DB file.** Atomic creation via `os.open(path, O_WRONLY|O_CREAT|O_TRUNC, 0o600)` — never `open()` then `chmod()` (umask race).

Makes network callslowCapability

Not a fault in itself. Listed so you know the mod talks to something, and to what.

`engine/tests/conftest.py` stubs the batched Reddit prefetch out of every test, so the suite never reaches the network. A test that exercises the prefetch itself opts in with `@pytest.mark.live_prefetch` and mocks the tr

Runs shell commandslowCapability

Expected in a hook, worth knowing in a rule or an instructions file.

- **No new shell=True subprocess calls.** Use `subprocess.run([..., args], shell=False)` with list args. The engine has zero `shell=True` calls today; keep it that way.

CLAUDE.md · 163 lines

How it starts

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

subscope — Contributor Guide

This file is for contributors working on the codebase, not plugin users. Plugin users want README.md. Plugin behavior is defined in skills/, not here. (claude plugin validate flags this file as "not loaded as plugin context" — that's correct, by design.)

If you opened a clone and asked Claude to help you contribute, this is the orientation document.

What this codebase is

A Python engine + Claude Code skills:

engine/subscope/ — Python. Fetches Reddit via public JSON, runs regex + optional LLM gates, scores survivors, writes to SQLite, prints JSON to stdout. Stdlib + pyyaml + optional openai, notion-client.
skills/*/SKILL.md — 15 user-invocable Claude Code skills. Each one is a single Markdown file that tells Claude how to orchestrate a workflow (Notion sync via MCP, Obsidian write via MCP, Playwright blog refresh, etc.). The Python engine does no MCP work — the skill layer does.
config/ — YAML defaults: weights, default subreddits, default keywords, scoring caps. Public users override by writing to ~/.config/subscope/.
presets/ — 4 starter bundles (b2b-saas-founder, agency-owner, indie-hacker, consultant) for users who don't want to run /subscope-onboard.
assets/ — README hero GIF + the Python+Pillow render script.

The engine is intentionally separable: you could pipe its JSON output to any orchestrator, not just Claude Code.

File layout

.
├── .claude-plugin/plugin.json    # plugin manifest (required by Claude Code)
├── engine/
│   ├── subscope/
│   │   ├── cli.py                # all CLI subcommands (fetch-score, status, op-vet, ...)
│   │   ├── lib/                  # the engine modules
│   │   │   ├── store.py          # SQLite + XDG paths + enrichment cache helpers
│   │   │   ├── score.py          # gate + score + selection
│   │   │   ├── reddit.py         # public-JSON fetcher
│   │   │   ├── classify.py       # OpenAI-compat bulk LLM grader
│   │   │   ├── author_vet.py     # OP karma/age/audience pre-gate
│   │   │   ├── discover.py       # live subreddit discovery for /onboard T5 (recall stage)
│   │   │   ├── archetype_map.py  # 6 archetypes, fallback seed for /onboard + /profile
│   │   │   ├── profile_synth.py  # 8-Q + 3-Q config synthesis
│   │   │   ├── obsidian_sync.py  # weekly pulse digest builder
│   │   │   ├── enrich.py         # DataForSEO + Firecrawl conditional consumers
│   │   │   ├── net.py            # SSRF guard + certifi-aware SSL context
│   │   │   ├── slack.py          # optional webhook push
│   │   │   ├── tune_engine.py    # /tune ranker back-prop
│   │   │   └── output.py         # markdown + table renderers
│   │   └── prompts/              # system prompts (classify, profile_synth)
│   ├── scripts/                  # one-shot helpers (write_dataforseo_config, write_firecrawl_config, notion_admin, ...)
│   └── tests/                    # pytest
├── skills/                       # 15 SKILL.md files, one per pattern
├── config/                       # default YAML (subreddits, keywords, weights, presets)
├── presets/                      # 4 starter bundles
├── assets/                       # hero.gif + render_hero.py
└── docs/                         # setup-notion.md (public only)

Read the full file on GitHub · 163 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.

3d ago First seen · 163 lines · 3,399 tokens per session scan B 03ff6696057e

Subscribe to this mod's changes

subscope CLAUDE.md is an instructions file published in the GitHub repository dancolta/subscope (25 stars, last pushed 21d ago), licensed MIT. It adds 3,399 tokens to every session, about $0.0170 per session on Opus 5. A static security scan graded it B with 3 findings (asks for root, makes network calls, runs shell commands). No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.

Research claude-code reddit reddit-monitoring social-listening sqlite

subscope CLAUDE.md

Getting it into your agent

What it costs to keep this loaded

Grade B, and why

Asks for rootmediumPrivilege escalation

Makes network callslowCapability

Runs shell commandslowCapability

How it starts

subscope — Contributor Guide

What this codebase is

File layout

What this file has done since we first saw it

Other instructions, from other repositories

last30days-skill AGENTS.md

databasement CLAUDE.md

openalgo CLAUDE.md

ZhiWei CLAUDE.md

codemark GEMINI.md

grain AGENTS.md