dsh-crumbs

English · 中文

Fill dead waiting time with one small true thing. While a long task runs, dsh-crumbs surfaces a short, fact-checked "crumb" — topic-relevant to whatever you're waiting on — then gets out of the way the moment the task finishes.

It never touches the agent's context, never changes the task, and never appears in the result. It's for the human staring at a spinner, not for the model.

⏳ working on: "git rebase --onto main feature~3 feature"

   💡 Git was written by Linus Torvalds in a matter of days in 2005, after the
      tool Linux had been using pulled its free license.

✅ task done — crumbs cleared.

Why this exists

Every tool for long-running agents optimizes the same thing: letting the agent run unattended — pause/resume, context compaction, status polling. But a lot of the time a human is watching: local runs, CLI sessions, non-technical users. That attended-but-idle stretch — attention still on, nothing to do — is a gap nobody fills. Loading-screen tips are static and unrelated; general trivia bots aren't tied to what you're doing. dsh-crumbs is the small, opinionated thing that fills exactly that gap.

Install

dsh plugin add dsh-crumbs

Three ways it shows up

1. Automatically, while you wait. When a long-running tool call (e.g. a shell command) runs past minTaskMs, crumbs drip into the notification surface every intervalMs, seeded by the command you're waiting on — a git command nudges toward coding facts, a planet one toward space. This path uses the same configured source as everything else, so by default each crumb is generated on the fly by the side model (see Where crumbs come from). They stop and clear when the task returns.
2. /crumb command — ask for one on demand: /crumb, /crumb git, /crumb concrete.
3. crumb tool — the model can call it directly; used by the command and available to any agent flow that wants a fact.

Where the auto crumb actually appears. A standard cordis host exposes no "toast" API, so the automatic path surfaces each crumb through ctx.logger — i.e. as a host log line, not (yet) a card in the Web UI. A visible in-UI surface needs a small client asset like other notification plugins ship; that's the main piece of future work. The /crumb command and crumb tool return through the normal tool/skill channel and are unaffected.

The crumb tool

Param	Type	Notes
topic	string, optional	Topic hint ("concrete", "git", "space"). Omit for any topic.
mode	"fact" | "quiz"	fact (default) states it; quiz asks first, then reveals the answer.

Recent crumbs are avoided, so repeated calls vary.

Configuration

Everything is opt-out with safe defaults.

• Env: DSH_CRUMBS_DISABLE=1 turns off the automatic long-task surfacing entirely (the /crumb command and crumb tool still work).
• Per repo: .dsh/crumbs.config.json

{
  "autoSurface": true,   // drip crumbs during long tasks
  "minTaskMs": 8000,     // a task must run this long to qualify
  "intervalMs": 12000,   // gap between crumbs while it keeps running
  "mode": "fact",        // "fact" | "quiz"
  "source": "model",     // "pool" | "model" | "auto"  (see below)
  "longTools": ["bash", "shell", "exec", "run"]  // which tool calls count as "long"
}

Where crumbs come from

source	Behavior
pool	Only the curated, fact-checked pool. Zero cost, offline, always accurate.
model (default)	A side model generates a crumb on the fly — ideally about the very thing you're waiting on. Shows nothing if no model surface is available (use auto if you want an offline safety net).
auto	Try the side model; if it's unavailable or returns nothing, fall back to the pool.

Two things worth being explicit about:

• The model is a side call. It uses the harness LLM service (ctx.llm.stream from @deepseek-ai/dsh-llm) with a one-shot user message — it never runs in, or writes to, the main agent's context, so generating a crumb can't pollute or slow the task you're waiting on. If the host exposes no model surface (offline, air-gapped, no endpoint), the default model source shows nothing — switch to auto and it silently degrades to the pool so the plugin always works.
• Model crumbs are unverified. They come back marked verified: false and rendered with a ✨ (pool crumbs use 💡 and are verified: true). Generated trivia can be confidently wrong — the plugin tells the model never to cite or build on a crumb, and you should treat ✨ ones as entertainment, not fact.

The crumb pool

Crumbs live in data/crumbs.json — curated, fact-checked, and general-interest, not tied to any field. They're tagged across coding, science, space, nature, history, geography, language, math, art, food, and body. Each entry carries a stated text and a quiz form. Topic relevance is plain tag matching against keywords in the current task — no model call, no network.

Crumbs are entertainment, not a source of truth. They're accurate to the best of our checking, but the plugin explicitly tells the model not to cite or build on them.

Try it without a host

node --experimental-strip-types scripts/demo.ts --topic "git rebase" --task 9000
node --experimental-strip-types scripts/demo.ts --topic "octopus" --mode quiz
node --experimental-strip-types scripts/demo.ts --source auto --mock-model   # see the ✨ generated path + pool fallback

Development

npm test          # unit tests: pool parsing, ranking, topic seeding, config, sources
npm run demo      # see the waiting experience in your terminal

Layout:

src/crumbs.ts   pool load / rank / pick / render   (pure)
src/topic.ts    task text → topic tags             (pure)
src/source.ts   pool / model / auto crumb sources  (pure + best-effort caller)
src/config.ts   env + per-repo config              (pure)
src/skill.ts    /crumb command payload             (pure)
src/index.ts    plugin: crumb tool + long-task hook + skill wiring
data/crumbs.json  the curated pool

License

MIT © MeghanBao