signal-loom

signal-loom

Turn the sources you already follow into a small, searchable research library and a brief you can read.

Signal Loom watches the feeds, channels, blogs, and listing pages you care about. It saves new items as plain Markdown, asks a model to add useful metadata, validates that metadata, builds a queryable index, and renders a topic-grouped brief.

The intent is simple: keep your information diet out of a black box. Sources, topics, aliases, generated notes, and briefs are all files you can inspect, edit, commit, sync, or point Obsidian/static-site tooling at.

What It Is For

Signal Loom is useful when you have a recurring set of sources and want to know:

• What changed since I last checked?
• Which items belong to the same topic across different sources?
• What are the important entities, summaries, and takeaways?
• Can I keep the output in my own files instead of a closed dashboard?

It is domain-agnostic. Bring your own sources and your own topic vocabulary: AI, climate, finance, healthcare, policy, local news, research papers, or anything else that works as feeds, channels, pages, or articles.

How It Works

flowchart LR
    Sources["config/sources.yaml<br/>Feeds, channels, pages"] --> Fetch["Fetch + scrape<br/>RSS, YouTube, listings"]
    Fetch --> Notes["Markdown notes<br/>content/"]
    Notes --> Enrich{"Enrich?"}
    Enrich -->|"Codex, Claude, or API"| Metadata["Validated metadata<br/>summary, topics, entities"]
    Enrich -->|"--no-enrich"| Index["index.json<br/>Queryable catalog"]
    Metadata --> Index
    Index --> Brief["Brief<br/>Topic-grouped digest"]

The model is not trusted with the whole system. Python owns the mechanical parts: fetching, writing files, validating model output, normalizing entities, building the index, and rendering briefs. The model only fills bounded enrichment packets, and its response is parsed before anything is written.

Design Principles

• Plain files first. Output is Markdown plus YAML frontmatter in content/, with a JSON index beside it.
• Configuration over code. Add sources, topic vocabulary, aliases, and paths in YAML.
• One core, multiple front doors. Codex, Claude Code, and headless Python all use the same core pipeline.
• Cheap and inspectable by default. Start with --no-enrich to prove your sources before spending on API enrichment.
• Model output is data, not instructions. Enrichment results go through an allow-list validator before writeback.

Ways To Run It

flowchart TB
    Core["Python core<br/>scrape, validate, index, brief"]
    Codex["Codex plugin<br/>$pipeline, $enrich, $brief"] --> Core
    Claude["Claude Code plugin<br/>/pipeline, /enrich, /brief"] --> Core
    Headless["Headless Python<br/>python -m core.pipeline"] --> Core
    Codex --> CodexModel["Model work in active Codex session<br/>no API key required by Python"]
    Claude --> ClaudeModel["Claude interactive path<br/>or Anthropic API for headless enrichment"]
    Headless --> ApiModel["Scheduled runs<br/>API enrichment optional"]

Path	Best for	Model/auth behavior
Codex plugin	Interactive use in Codex with $pipeline, $enrich, and $brief	Codex does model work through the active session. Python does not read Codex auth files or require API keys for Codex-native enrichment.
Claude Code plugin	Interactive use in Claude Code with /pipeline, /enrich, and /brief	Claude sub-agents handle interactive enrichment.
Headless Python	Cron, launchd, CI-like checks, or plain local runs	--no-enrich is free. API enrichment uses Anthropic and requires ANTHROPIC_API_KEY.

---

Quickstart (Codex plugin)

The Codex path is the seat-auth path: Python emits bounded work packets, validates model output, writes frontmatter, and builds the index. Codex itself does the model work in your active Codex session. The plugin code does not read ~/.codex/auth.json and does not require OPENAI_API_KEY, CODEX_API_KEY, or ANTHROPIC_API_KEY for Codex-native enrichment.

For local e2e verification from this checkout:

uv run python scripts/codex_plugin_e2e.py

For manual Codex runs, start Codex with API-key variables removed and isolate zsh startup so local shell profiles cannot re-export them:

ZDOTDIR="$(mktemp -d)" \
env -u OPENAI_API_KEY -u CODEX_API_KEY -u ANTHROPIC_API_KEY \
codex exec \
  --enable plugins \
  --enable hooks \
  -c 'forced_login_method="chatgpt"' \
  -c 'allow_login_shell=false' \
  -c 'shell_environment_policy.experimental_use_profile=false' \
  -c 'shell_environment_policy.exclude=["OPENAI_API_KEY","CODEX_API_KEY","ANTHROPIC_API_KEY"]' \
  '$pipeline refresh my sources'

Current Codex CLI builds may not fire plugin SessionStart hooks. The runtime commands still lazy-bootstrap config/*.yaml from examples before use; the e2e harness records whether hook bootstrap was observed.