bunqueue CLAUDE.md

Project instructions for bunqueue, a TypeScript job queue that runs on Bun and uses SQLite for storage. They define coding, testing, language, and review rules.

In plain words
What is it for?
Developing or repairing queue processing, persistence, network clients, workers, tests, and related documentation in the bunqueue repository.
Why use it?
They require bugs to be reproduced with tests first and changes to pass isolated validation, helping catch regressions and concurrency problems.

Instructions file

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/egeominotti/bunqueue/claude-md
Clone the repo
git clone --depth 1 https://github.com/egeominotti/bunqueue
Per session 7,401 This file is loaded in full into every session.
When invoked 7,401 The same file — it is already loaded in full.
Security scan A 1 finding. 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.

ModelPer sessionOnce invoked
Fable 5 $0.07401 $0.07401
Opus 5 $0.03700 $0.03700
Sonnet 5 $0.01480 $0.01480
Haiku 4.5 $0.00740 $0.00740

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

Security

Grade A, and why

bunqueue CLAUDE.md scanned grade A with 1 finding 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 2d 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.

Makes network callslowCapability

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

curl http://localhost:6790/health # Health + memory
CLAUDE.md · 615 lines

How it starts

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

bunqueue

MANDATORY — SKEPTIC AGENT: before every git commit and every git push, invoke the skeptic agent and wait for its verdict. It must read the complete staged diff, identify at least three potential failure points per changed file, and verify race conditions, error handling, idempotency, type safety and test coverage. FAIL blocks commit and push; CONDITIONAL requires the user's explicit confirmation. The project profile is .claude/agents/skeptic.md.

ENGLISH ONLY: keep all repository content in English, including source comments, tests, technical documentation, user documentation and agent configuration.

"When I report a bug, don't start by trying to fix it. Instead, start by writing a test that reproduces the bug. Then, have subagents try to fix the bug and prove it with a passing test."

MANDATORY: After ANY code modification, run the isolated validation before committing:

bun run test:sandbox

It builds the current worktree once and runs ALL THREE required suites concurrently in separate disposable containers:

bun test --parallel=4                   # Unit tests (four isolated file workers)
bun scripts/tcp/run-all-tests.ts        # TCP integration tests (~50 suites)
bun scripts/embedded/run-all-tests.ts   # Embedded integration tests (~35 suites)

Never commit without all three passing. No exceptions.

MANDATORY for core queue semantics: run the real-broker model before the sandbox:

bun run test:model

Run it after every change to lifecycle transitions, SQLite/write buffering, startup or stall recovery, priority/FIFO/LIFO/delay scheduling, FIFO groups, dependencies, dedup/custom IDs, leases, limits, TTL, counters, temporal indexes, or jobIndex. The fast-check model executes generated command histories against a fresh TCP broker and SQLite database, including actual SIGKILL restarts. It checks conservation, no loss/resurrection/duplicate active lease, retry and stall bounds, legal transitions, ordering, resource limits, counter/index coherence, idempotent recovery, and DLQ exactly-once.

On failure, retain the seed, minimized command history, and replay path. If the engine is wrong, add a deterministic test/repro-model-*.test.ts that fails before changing runtime code; if the specification is wrong, correct the model with evidence. Never weaken an invariant to make a campaign green. Deeper replay:

BUNQUEUE_MODEL_RUNS=500 BUNQUEUE_MODEL_COMMANDS=150 \
BUNQUEUE_MODEL_SEED=-1959189325 bun run test:model

This targeted command does not replace bun run test:sandbox; the full bun test --parallel=4 unit command inside the sandbox runs the model again.

MANDATORY: After ANY modification under sdk/, run before handoff (and run again before committing if the SDK changed afterward):

bun run test:sandbox:sdk

It runs every official external SDK's native tests and shared protocol conformance checks in isolated disposable containers. SDK changes require both full gates (test:sandbox and test:sandbox:sdk); targeted native tests do not replace either one. Review artifacts/test-sandbox-sdk/<timestamp>/summary.md and its JSON/NDJSON artifacts before handoff.

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

  1. 2d ago First seen · 615 lines · 7,401 tokens per session scan A 69145d9b624d

Subscribe to this mod's changes

bunqueue CLAUDE.md is an instructions file published in the GitHub repository egeominotti/bunqueue (544 stars, last pushed 2d ago), licensed MIT. It adds 7,401 tokens to every session, about $0.0370 per session on Opus 5. A static security scan graded it A with 1 finding (makes network calls). No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.