kitchen-engineer42/bird-clawd/ai-signal-pipeline

ai-signal-pipeline

The problem: algorithmic feeds adapt to what you like — engagement bait, memes, tribal flamewars — and bury what you need: the source-grounded, production-grade developments in your field. The fix is structural: this pipeline splits "preference" into FIT (domain, depth, healthy diversity, practicality — dimensions it learns about you over time) and GUARDRAILS (bait, memes, ads, flamewars — failure modes it is forbidden from learning, even from your own engagement). Your likes are data about the problem, not the spec.

The loop: morning digest (scheduled) → you comment inline during the day → on-demand taste-update + slide build. birdclaw + bird are the data layer; you (headless Claude) are the brain. Read-only: it screens; it never posts.

You are acting as an installer: walk the user through the steps below, scaffold their project from templates/ (filling placeholders), test it, and schedule it. Do the work; don't just describe it. Ask the questions in Steps 3–5, then proceed.

What it builds

$PIPELINE_ROOT/
├── bin/morning.sh               # scheduled: sync → screen → digest (hardened: trust guard,
│                                #   readiness gate, watchdog, retry, one-shot skip flag)
├── bin/build-slide.sh           # on-demand: day's deck + PNG — audience self|team|demo
├── bin/deck2png.sh              # render deck → one tall scrolling PNG (phone/chat)
├── prompts/{morning,slide,taste-update}.md
├── .claude/settings.json        # READ-ONLY permission model (writes to X blocked)
├── config.env                   # X_HANDLE, DECK_NAME, SLIDE_AUDIENCE, OWNER_LABEL
├── taste.md                     # the two-part taste model (FIT + GUARDRAILS)
├── brand/tokens.css             # deck palette + fonts (customizable, presets included)
├── vendor/frontend-slides/      # slide system (vendored subset, MIT — see its VENDORED.md)
└── digests/ slides/ data/ logs/

Morning (default 07:00): sync → screen TODAY against taste.md → write digests/<today>.md with an empty 💬 line under every item. The owner comments inline during the day, then on demand runs `./bin/build-slide.sh [date] [self|team|demo]` (deck + PNG from the digest and its comments) and/or the taste-update step (folds the day's comments back into taste.md, FIT-only). The morning run does NOT build slides or tune taste — same-day, owner-triggered.

The read-only promise (state this to the user up front)

The pipeline reads the user's X session cookies locally via bird (graphql). .claude/settings.json allows only bird READ commands and blocks every write (tweet/reply/follow/unfollow/unbookmark). It screens; it never posts, follows, or likes. Nothing leaves the machine except the web searches Claude runs and the Claude API calls.

Step 1 — Prerequisites (macOS)

Confirm/install: Homebrew, Node, Claude Code. Then:

brew install steipete/tap/birdclaw && birdclaw init
npm install -g @steipete/bird

(birdclaw is MIT; bird is @steipete/bird. We install them — we don't redistribute them.)

Step 2 — Connect X (read-only, free)

Use bird, NOT xurl: bird reads your logged-in browser session over graphql — no developer app, no paid API. (xurl needs the X developer API; X Premium is a consumer sub and does not grant API access.)

• Make sure the user is logged into x.com in Chrome (Safari cookies are often locked by

macOS; bird falls back to Chrome automatically).

• Verify: bird whoami → prints their handle. Capture the handle (without @) for config.env.

Step 3 — Scaffold the project (ask these, then build)

Ask the user:

1. Project root — absolute path. Must NOT be under ~/Desktop, ~/Documents, or ~/Downloads

(macOS TCC blocks background launchd jobs from those folders). Recommend ~/ai-signal.

1. X handle — default to bird whoami's answer.
2. Morning run time — default 07:00.

Then scaffold from this skill's templates/:

• Copy templates/bin/morning.sh, templates/bin/build-slide.sh, templates/bin/deck2png.sh → $PIPELINE_ROOT/bin/ (chmod +x). They self-locate their root; no path edits needed.
• Copy the three templates/prompts/ files → $PIPELINE_ROOT/prompts/.
• Copy templates/settings.json → $PIPELINE_ROOT/.claude/settings.json.
• Copy templates/taste.md → $PIPELINE_ROOT/taste.md and templates/brand/tokens.css → $PIPELINE_ROOT/brand/tokens.css.
• Copy templates/config.env → $PIPELINE_ROOT/config.env and set X_HANDLE.
• Copy the vendored slide system: templates/vendor/frontend-slides/ → $PIPELINE_ROOT/vendor/frontend-slides/ (MIT, by zarazhangrui — provenance in its VENDORED.md).
• Render templates/launchd/morning.plist.tmpl → ~/Library/LaunchAgents/, replacing __PIPELINE_ROOT__ with the real absolute root (and the run time if changed).
• mkdir -p the digests slides data logs subfolders.

Step 4 — Personalize the taste (the FIT interview)

taste.md is the product. Interview the user and edit its four FIT sections from the answers:

1. F1 Business domain — what field/scene are they screening? (default: production AI/LLM

engineering)

1. F2 Knowledge depth — whose bar? (production engineer / researcher / technical founder…)
2. F3 Healthy diversity — which adjacent topics should stay in the mix even when they're

not the user's favorites? Name 2–3 explicitly.

1. F4 Practicality — what are they building or learning right now, so items that double as

reference/benchmark/eval material get a tilt?

Then state plainly: GUARDRAILS are not configured here — they're the point. The engagement- bait/memes/flamewars section is immutable; only a digest comment beginning GUARDRAIL CHANGE: ever edits it. The taste-update step will refuse to learn from engagement with those categories.

Step 5 — Deck identity + audience

Ask, then write into config.env and brand/tokens.css:

1. Deck name (DECK_NAME) — the brand mark on every slide.
2. Default audience (SLIDE_AUDIENCE): self (own review, bluntest), team (internal

brief — default), or demo (public-safe, no owner bubbles). Overridable per run.

1. Owner label (OWNER_LABEL) — how their comment bubbles are labeled in team mode.
2. Palette + fonts — keep the default, pick a preset from tokens.css's comment block, or

take 2–3 brand hexes + a display-font preference and write them into the tokens.

Step 6 — Dry-run test

cd "$PIPELINE_ROOT" && ./bin/morning.sh
cat digests/$(date +%F).md      # good digest?
cat logs/morning.err            # errors?

Then have the user add a comment or two under digest items and build:

./bin/build-slide.sh                      # today's deck, default audience
./bin/build-slide.sh $(date +%F) self     # same day, personal-review mode

Step 7 — Schedule + smoke test

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/sh.ai-signal.morning.plist
launchctl list | grep ai-signal

Smoke test the unattended path (the one thing an interactive run can't prove): schedule a throwaway job ~2 minutes out that runs bird whoami + a trivial claude -p + writes a marker file, then inspect its log. If a macOS Keychain prompt appears (background job reading Chrome cookies / the Claude token), the user clicks Allow once. If it completes clean, it's settled — tomorrow's 07:00 run is the same path doing the real work.

Gotchas (hard-won; bake these in)

• bird, not xurl. X Premium ≠ API access; the dev API is paid. bird (cookies) is free + read-only.
• Keep the project OFF ~/Desktop/Documents/Downloads. macOS TCC blocks background launchd

jobs from writing there — the interactive run works but the scheduled one fails silently.

• Never remove the trust guard in morning.sh. Claude Code periodically drops the workspace

trust flag in ~/.claude.json; without it, headless runs ignore .claude/settings.json and the discovery layer (search/news/lists) silently dies.

• Never add WebFetch back into the slide build, and keep the watchdogs. A single hanging

fetch blocks a headless build 20+ minutes and can't be aborted by a prompt rule; the digest is already source-grounded at screen time. A hung claude -p never exits — that's what the kill-after-15-min watchdogs are for.

• `touch data/skip-next-morning` skips exactly one scheduled run (self-clearing) — for when

a manual catch-up digest already covers today.

• `bird user-tweets` returns posts, not replies. Reply-level tracking isn't available

without the paid API. Don't promise it.

• `bird news --ai-only` leaks sports/entertainment; screen against taste and drop non-AI items.
• Cookies expire. When reads start failing, re-run bird whoami after re-logging into Chrome.
• Mac must be awake + logged in at the scheduled time (launchd catches a missed run on wake).