Random Thought

A thinking engine that reads your workspace and writes about what it finds — not summaries,
not status updates, but genuine reflection on what's unresolved, alive, or worth questioning.

Two Stages

Writer

Curator

Quick Start

Manual invocation

Cron-driven (recommended)

Each cron invocation runs in an isolated session — no context bleed between runs.

Configuration

Create random-thought.config.json in your workspace root (all fields optional):

CODEBLOCK2

Configuration Reference

• - corpus.watchDirs — Directories to scan (relative to workspace). Default: INLINECODE1
• corpus.excludePatterns — Glob patterns to exclude. Sensible defaults included.
• freshness.enabled — Prevent revisiting files within N days. Default: INLINECODE2
• freshness.days — Cooldown period per file. Default: INLINECODE3
• freshness.historyFile — Where to track visited files. Default: INLINECODE4
• actionTags — Labels the Curator uses to classify observations. Override to match your workflow.
• output.dir — Where digests are written. Default: INLINECODE5

Writer Stage

What it does

1. 1. Run scripts/corpus-pick.sh to select a random file (respecting freshness gate)
2. Read the selected file (up to 200 lines if large)
3. Write a reflective observation — not a summary, not a review. Follow the thread wherever it leads.
4. Deliver the output (post to configured channel, write to file, or return to caller)

Writer output format

• - First line: INLINECODE7
• Blank line
• Flowing prose. No bullets. No headers. No preamble.
• Follow what's unresolved, surprising, half-finished, or alive.
• Make connections to other things in the workspace if they surface naturally.
• Last line: INLINECODE8

Avoid these crutches

• - "quietly elegant" / "speaks to something deeper" / "testament to" / "tapestry"
• "there's something almost [adjective] about"
• "beautiful in its simplicity"

Concrete observations beat ornamental ones.

Curator Stage

What it does

1. 1. Read all Writer outputs from the configured period (default: last 24 hours)
2. Classify each observation using configured action tags
3. Identify recurring themes or convergent patterns across observations
4. Write a structured digest to INLINECODE9

Digest format

Curator guidelines

• - Classify every observation into exactly one action tag
• Surface theme convergence — if multiple observations point at the same gap, name it explicitly
• Keep the digest scannable — each item should be one line with context
• Do NOT re-surface items from previous digests unless they've evolved

Scripts

scripts/corpus-pick.sh

Usage: INLINECODE11

• - Reads configuration from random-thought.config.json if present
• Falls back to sensible defaults if no config exists
• Records selected file to the history file for freshness tracking
• Outputs the absolute path of the selected file

scripts/freshness-gate.sh

Usage:

• - bash scripts/freshness-gate.sh check <file> [config_path] — exits 0 if file is fresh (OK to visit), 1 if recently visited
• INLINECODE15 — records a file visit
• INLINECODE16 — removes entries older than the configured window

References

• - architecture.md — Design rationale: why two stages, why cron-driven isolation matters, the hybrid skill+cron model. Read when customizing the pipeline or understanding trade-offs.