bunqueue-dev

An internal development guide for contributing to bunqueue, a Bun job-queue library that uses SQLite to persist jobs and can run inside one process or through a separate server.

In plain words
What is it for?
Use it when modifying bunqueue’s queues, workers, retry and failure handling, SQLite persistence, TCP communication, or related tests and tools.
Why use it?
It gives contributors the project’s architecture, request flow, directory layout, testing expectations, and coding conventions so changes fit the existing system.

Skill for Claude CodeCodex

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 skills/egeominotti/bunqueue/bunqueue-dev
Any agent
npx skills add egeominotti/bunqueue --skill bunqueue-dev
Clone the repo
git clone --depth 1 https://github.com/egeominotti/bunqueue

Made for: Claude Code, Codex.

Per session 22 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.
When invoked 1,033 The whole file, excluding the scripts and references it only reads on demand.
Security scan A 0 findings. 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.00022 $0.01033
Opus 5 $0.00011 $0.00517
Sonnet 5 $0.00004 $0.00207
Haiku 4.5 $0.00002 $0.00103

Measured yesterday against content hash 32dcc71a7784, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade A, and why

bunqueue-dev scanned grade A with 0 findings 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 yesterday.

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.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

.claude/skills/bunqueue-dev/SKILL.md · 96 lines

How it starts

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

bunqueue Development Guide

You are working on bunqueue, a high-performance job queue for Bun with SQLite persistence.

Architecture

bunqueue uses a sharded priority queue architecture:

  • Shards: Auto-detected from CPU cores (power of 2, max 64). Jobs are assigned via fnv1aHash(queue) & SHARD_MASK
  • Persistence: SQLite in WAL mode with a 10ms WriteBuffer for batching writes
  • Transport: TCP (msgpack) on port 6789, HTTP on port 6790
  • Two modes: Embedded (in-process) and TCP (client-server)

Request Flow

  1. PUSH: Client -> TcpPool -> TcpServer -> QueueManager -> Shard -> PriorityQueue -> WriteBuffer -> SQLite
  2. PULL: Client -> TcpServer -> QueueManager -> Shard -> PriorityQueue.pop()
  3. ACK: Client -> TcpServer -> AckBatcher -> Shard.complete() -> jobResults (LRU)
  4. FAIL: Client -> TcpServer -> Shard.fail() -> retry (backoff) OR -> DLQ

Directory Structure

src/
  cli/              # CLI interface
  client/           # SDK (Queue, Worker, FlowProducer, Bunqueue)
    queue/          # Queue with DLQ, stall detection
    worker/         # Worker with heartbeat, ack batching
    tcp/            # Connection pool, reconnection
    workflow/       # Workflow Engine (Workflow DSL, Engine, Executor, Store)
  domain/           # Pure business logic
    queue/          # Shard, PriorityQueue, DlqShard, UniqueKeyManager
  application/      # Use cases and managers
    operations/     # push, pull, ack, query, queueControl
  infrastructure/   # Persistence, server, scheduler, backup
  shared/           # Utilities (hash, lock, lru, skipList, minHeap)

Workflow Engine

Located in src/client/workflow/. Pure consumer layer on bunqueue (no core modifications).

  • workflow.ts — Fluent DSL: .step(), .branch(), .path(), .waitFor()
  • engine.ts — Public facade: register, start, signal, getExecution, close
  • executor.ts — Core logic: step execution, branching, compensation, signals
  • store.ts — SQLite persistence for execution state (workflow_executions table)
  • types.ts — StepContext, Execution, StepJobData, EngineOptions, etc.
  • Export: import { Workflow, Engine } from 'bunqueue/workflow'

Read the full file on GitHub · 96 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. yesterday First seen · 96 lines · 22 tokens per session scan A 32dcc71a7784

Subscribe to this mod's changes

bunqueue-dev is a skill published in the GitHub repository egeominotti/bunqueue (544 stars, last pushed yesterday), licensed MIT. It adds 22 tokens to every session and 1,033 once invoked, about $0.0001 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.

Related

Other skills, from other repositories